fix(harness): eliminate agent forking — use single shared agent across modes (#18008)

## Description

Eliminates `__fork()` from the shared-agent path in Harness. Instead of
creating per-mode agent clones, the harness reuses `config.agent`
directly and never mutates its instructions or tools.

**Root cause:** PR #17892 introduced shared harness modes that fork the
base agent per-mode. Signal providers connected to the base agent during
construction skip re-connection on forks (`isConnected` guard), so they
remain pointed at the original memoryless base agent. When GitHubSignals
(or any signal provider) tries to deliver notifications, it crashes:

```
[Processor:task-state] computeStateSignal requires Mastra memory
  with an active resourceId and threadId
```

**Fix — no more forking, no agent mutation:**

```diff
 # getAgentForMode() — shared agent path
-  const forkedAgent = this.config.agent.__fork();
-  forkedAgent.__updateInstructions(instructions);
-  forkedAgent.__setTools(modeTools);
-  this.#legacyAgentMode[mode.id] = forkedAgent;
+  return this.config.agent;  // single instance, no fork, no mutation
```

- `getAgentForMode()`: returns `config.agent` directly — no fork, no
instructions/tools mutation
- `buildAgentMessageStreamOptions()`: resolves mode instructions at call
time via `resolveCurrentModeInstructions()` and passes them as the
`instructions` stream option — the agent's own instructions are never
touched
- `buildToolsets()`: mode-specific tools (`mode.tools` /
`mode.additionalTools`) are delivered through toolsets — the agent's own
tools (including signal-provider tools) are never replaced
- `init()`: propagates runtime services (memory, storage, etc.) once to
the shared agent — signal providers connected during construction retain
full access
- `setBrowser()`: sets browser on the single agent instead of iterating
forks
- Deprecated `mode.agent` and no-backing-agent construction paths are
unchanged

## Related issue(s)

Reported in Slack #mastracode by Tyler Barnes. Regression from #17892
(shared harness modes via `__fork()`).

## Type of change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Code refactoring

## Checklist

- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

Link to Devin session:
https://app.devin.ai/sessions/a7472d903dcd4982bbed590b0bde4c1c

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
Harness can run “agent work” in different modes (like different
capabilities). A bug made Harness create separate agent copies per mode,
but some notification components (signal providers) kept using the
original agent that never got the required memory/services—so
notifications crashed. This PR stops the per-mode agent cloning and
instead reuses one shared agent, wiring mode-specific instructions/tools
at runtime so the shared agent has memory and signals work again.

## Summary
Fixes a regression where Harness signal providers (e.g. `GitHubSignals`)
could crash because they were still connected to a base `Agent` that
lacked Mastra runtime services (especially memory) after PR `#17892`
introduced per-mode agent forking/cloning.

### Key changes
- **Removed agent forking/cloning for the shared-agent (`config.agent`)
path**
- `getAgentForMode()` returns `config.agent` directly (no per-mode
cloning).
- The deprecated `mode.agent` path remains supported via its existing
per-mode caching behavior (agents can still be independent there).
- **Mode instructions are applied dynamically at call time (no mutation
of the shared agent)**
- `resolveCurrentModeInstructions()` computes harness-level + current
mode instructions on demand.
- `buildAgentMessageStreamOptions()` passes these as the `instructions`
stream option, instead of updating the agent’s own instructions (avoids
cross-mode instruction bleed).
- **Mode tools are delivered via toolsets (no replacement of the shared
agent’s tools)**
- `buildToolsets()` supplies mode tool overrides at the toolset level
(via `result.modeTools`) for the shared-agent path, rather than
baking/replacing tools on the shared agent.
- **Runtime services and browser propagation happen once for the shared
agent**
- `init()` propagates runtime services
(memory/storage/workspace/browser/pubsub, etc.) once to the shared
`config.agent`.
  - `setBrowser()` sets the browser on the single shared agent.
- **Deprecated/no-backing-agent behavior remains unchanged**
- When there is no shared backing agent, the harness continues
constructing/caching per-mode agents with combined harness+mode
instructions and merged mode tools, as before.

### Tests
Extended `packages/core/src/harness/fork-clone-metadata.test.ts` to
cover:
- The same `config.agent` instance is reused across mode switches (no
forking).
- The shared agent’s own instruction text is not mutated across mode
switches.
- Mode-specific instructions are resolved dynamically at call time.
- Mode tools appear/disappear correctly in generated toolsets while
using the shared-agent path.
- `SignalProvider`-based regression coverage: a connected base/shared
agent retains access to runtime services (memory) after
`harness.init()`, staying properly connected across mode switches.
- A regression test confirming the deprecated `mode.agent` path still
keeps agents independent per mode.

### Changeset
- Added a patch changeset for `@mastra/core` documenting that signal
providers no longer lose memory access when Harness previously forked
agents per mode.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Abhi Aiyer <abhi@mastra.ai>

Author: devin-ai-integration[bot]

.changeset/clear-buses-judge.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Fixed signal providers losing memory access when harness forks agents per mode. Harness now propagates runtime services (memory, storage, etc.) to the base config agent during init so signal providers connected to it can deliver notifications.

packages/core/src/harness/fork-clone-metadata.test.ts

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import { Agent } from '../agent';
 import { RequestContext } from '../request-context';
+import { SignalProvider } from '../signals/signal-provider';
 
 import { Harness } from './harness';
 import type * as Tools from './tools';
@@ -199,4 +200,353 @@ describe('Harness fork clone metadata wiring', () => {
     expect(builtIn.subagent).toBeDefined();
     expect(builtIn.ask_user).toBeDefined();
   });
+
+  it('shared config.agent is reused across modes without forking', async () => {
+    const memoryFactory = vi.fn().mockResolvedValue({});
+
+    const baseAgent = new Agent({
+      name: 'shared',
+      instructions: 'shared agent',
+      model: { provider: 'openai', name: 'gpt-4o', toolChoice: 'auto' },
+    });
+
+    const harness = new Harness({
+      id: 'test',
+      resourceId: 'test-resource',
+      memory: memoryFactory as unknown as never,
+      modes: [
+        {
+          id: 'build',
+          name: 'Build',
+          default: true,
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Build things.',
+        },
+        {
+          id: 'plan',
+          name: 'Plan',
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Plan things.',
+        },
+      ],
+      agent: baseAgent,
+    });
+
+    await harness.init();
+
+    // All modes should return the same agent instance — no forking
+    const buildAgent = harness.getCurrentAgent();
+    await harness.switchMode({ modeId: 'plan' });
+    const planAgent = harness.getCurrentAgent();
+    await harness.switchMode({ modeId: 'build' });
+    const buildAgentAgain = harness.getCurrentAgent();
+
+    expect(buildAgent).toBe(baseAgent);
+    expect(planAgent).toBe(baseAgent);
+    expect(buildAgentAgain).toBe(baseAgent);
+  });
+
+  it('agent own instructions are never mutated by harness mode switches', async () => {
+    const memoryFactory = vi.fn().mockResolvedValue({});
+    const originalInstructions = 'I am the original agent instructions';
+
+    const baseAgent = new Agent({
+      name: 'shared',
+      instructions: originalInstructions,
+      model: { provider: 'openai', name: 'gpt-4o', toolChoice: 'auto' },
+    });
+
+    const harness = new Harness({
+      id: 'test',
+      resourceId: 'test-resource',
+      memory: memoryFactory as unknown as never,
+      instructions: 'Harness-level instructions.',
+      modes: [
+        {
+          id: 'build',
+          name: 'Build',
+          default: true,
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Build things.',
+        },
+        {
+          id: 'plan',
+          name: 'Plan',
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Plan things.',
+        },
+      ],
+      agent: baseAgent,
+    });
+
+    await harness.init();
+
+    // Switch modes multiple times
+    harness.getCurrentAgent();
+    await harness.switchMode({ modeId: 'plan' });
+    harness.getCurrentAgent();
+    await harness.switchMode({ modeId: 'build' });
+    harness.getCurrentAgent();
+
+    // The agent's own instructions should remain unchanged
+    const agentInstructions = await baseAgent.getInstructions();
+    expect(agentInstructions).toBe(originalInstructions);
+  });
+
+  it('mode instructions are resolved at call time via resolveCurrentModeInstructions', async () => {
+    const memoryFactory = vi.fn().mockResolvedValue({});
+
+    const baseAgent = new Agent({
+      name: 'shared',
+      instructions: 'agent instructions',
+      model: { provider: 'openai', name: 'gpt-4o', toolChoice: 'auto' },
+    });
+
+    const harness = new Harness({
+      id: 'test',
+      resourceId: 'test-resource',
+      memory: memoryFactory as unknown as never,
+      instructions: 'Harness global.',
+      modes: [
+        {
+          id: 'build',
+          name: 'Build',
+          default: true,
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Build mode.',
+        },
+        {
+          id: 'plan',
+          name: 'Plan',
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Plan mode.',
+        },
+      ],
+      agent: baseAgent,
+    });
+
+    await harness.init();
+
+    const resolve = (harness as unknown as { resolveCurrentModeInstructions(): string | undefined })
+      .resolveCurrentModeInstructions;
+
+    // Default mode is 'build'
+    expect(resolve.call(harness)).toBe('Harness global.\nBuild mode.');
+
+    await harness.switchMode({ modeId: 'plan' });
+    expect(resolve.call(harness)).toBe('Harness global.\nPlan mode.');
+
+    await harness.switchMode({ modeId: 'build' });
+    expect(resolve.call(harness)).toBe('Harness global.\nBuild mode.');
+  });
+
+  it('mode tools are included in toolsets when using shared config.agent', async () => {
+    const memoryFactory = vi.fn().mockResolvedValue({});
+    const modeTool = { description: 'a mode tool', parameters: {} as never, execute: async () => null } as never;
+
+    const baseAgent = new Agent({
+      name: 'shared',
+      instructions: 'shared agent',
+      model: { provider: 'openai', name: 'gpt-4o', toolChoice: 'auto' },
+    });
+
+    const harness = new Harness({
+      id: 'test',
+      resourceId: 'test-resource',
+      memory: memoryFactory as unknown as never,
+      modes: [
+        {
+          id: 'build',
+          name: 'Build',
+          default: true,
+          defaultModelId: 'openai/gpt-4o',
+          additionalTools: { buildTool: modeTool },
+        },
+        {
+          id: 'plan',
+          name: 'Plan',
+          defaultModelId: 'openai/gpt-4o',
+        },
+      ],
+      agent: baseAgent,
+    });
+
+    await harness.init();
+
+    const buildToolsets = (
+      harness as unknown as { buildToolsets(ctx: RequestContext): Promise<Record<string, unknown>> }
+    ).buildToolsets;
+
+    // In 'build' mode, mode tools should appear in toolsets
+    const buildResult = (await buildToolsets.call(harness, new RequestContext())) as {
+      modeTools?: Record<string, unknown>;
+    };
+    expect(buildResult.modeTools).toBeDefined();
+    expect(buildResult.modeTools!.buildTool).toBe(modeTool);
+
+    // Switch to 'plan' mode (no mode tools) — modeTools should be absent
+    await harness.switchMode({ modeId: 'plan' });
+    const planResult = (await buildToolsets.call(harness, new RequestContext())) as {
+      modeTools?: Record<string, unknown>;
+    };
+    expect(planResult.modeTools).toBeUndefined();
+  });
+
+  it('signal provider stays connected to same agent across mode switches', async () => {
+    class TestSignalProvider extends SignalProvider<'test-signals'> {
+      readonly id = 'test-signals' as const;
+      getConnectedAgent() {
+        return this.agent;
+      }
+    }
+
+    const signalProvider = new TestSignalProvider();
+    const memoryFactory = vi.fn().mockResolvedValue({});
+
+    const baseAgent = new Agent({
+      name: 'base',
+      instructions: 'base agent',
+      model: { provider: 'openai', name: 'gpt-4o', toolChoice: 'auto' },
+      signals: [signalProvider],
+    });
+
+    const harness = new Harness({
+      id: 'test',
+      resourceId: 'test-resource',
+      memory: memoryFactory as unknown as never,
+      modes: [
+        {
+          id: 'build',
+          name: 'Build',
+          default: true,
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Build things.',
+        },
+        {
+          id: 'plan',
+          name: 'Plan',
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Plan things.',
+        },
+      ],
+      agent: baseAgent,
+    });
+
+    await harness.init();
+
+    // Signal provider should always point at baseAgent, regardless of mode
+    expect(signalProvider.getConnectedAgent()).toBe(baseAgent);
+    expect(signalProvider.getConnectedAgent()!.hasOwnMemory()).toBe(true);
+
+    await harness.switchMode({ modeId: 'plan' });
+    expect(signalProvider.getConnectedAgent()).toBe(baseAgent);
+    expect(signalProvider.getConnectedAgent()!.hasOwnMemory()).toBe(true);
+
+    await harness.switchMode({ modeId: 'build' });
+    expect(signalProvider.getConnectedAgent()).toBe(baseAgent);
+    expect(signalProvider.getConnectedAgent()!.hasOwnMemory()).toBe(true);
+  });
+
+  it('deprecated mode.agent path still works independently per mode', async () => {
+    const memoryFactory = vi.fn().mockResolvedValue({});
+
+    const buildAgent = new Agent({
+      name: 'build-agent',
+      instructions: 'build',
+      model: { provider: 'openai', name: 'gpt-4o', toolChoice: 'auto' },
+    });
+
+    const planAgent = new Agent({
+      name: 'plan-agent',
+      instructions: 'plan',
+      model: { provider: 'openai', name: 'gpt-4o', toolChoice: 'auto' },
+    });
+
+    const harness = new Harness({
+      id: 'test',
+      resourceId: 'test-resource',
+      memory: memoryFactory as unknown as never,
+      modes: [
+        {
+          id: 'build',
+          name: 'Build',
+          default: true,
+          defaultModelId: 'openai/gpt-4o',
+          agent: buildAgent,
+        },
+        {
+          id: 'plan',
+          name: 'Plan',
+          defaultModelId: 'openai/gpt-4o',
+          agent: planAgent,
+        },
+      ],
+    });
+
+    await harness.init();
+
+    // Deprecated mode.agent path — each mode gets its own agent
+    const currentBuild = harness.getCurrentAgent();
+    expect(currentBuild).toBe(buildAgent);
+
+    await harness.switchMode({ modeId: 'plan' });
+    const currentPlan = harness.getCurrentAgent();
+    expect(currentPlan).toBe(planAgent);
+    expect(currentPlan).not.toBe(currentBuild);
+  });
+
+  it('propagates memory to the base config.agent so signal providers have access', async () => {
+    class TestSignalProvider extends SignalProvider<'test-signals'> {
+      readonly id = 'test-signals' as const;
+      getConnectedAgent() {
+        return this.agent;
+      }
+    }
+
+    const signalProvider = new TestSignalProvider();
+    const memoryFactory = vi.fn().mockResolvedValue({});
+
+    const baseAgent = new Agent({
+      name: 'base',
+      instructions: 'base agent',
+      model: { provider: 'openai', name: 'gpt-4o', toolChoice: 'auto' },
+      signals: [signalProvider],
+    });
+
+    // Signal provider is connected to the base agent
+    expect(signalProvider.isConnected).toBe(true);
+    expect(signalProvider.getConnectedAgent()).toBe(baseAgent);
+
+    // Before harness init, base agent has no memory
+    expect(baseAgent.hasOwnMemory()).toBe(false);
+
+    const harness = new Harness({
+      id: 'test',
+      resourceId: 'test-resource',
+      memory: memoryFactory as unknown as never,
+      modes: [
+        {
+          id: 'build',
+          name: 'Build',
+          default: true,
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Build things.',
+        },
+        {
+          id: 'plan',
+          name: 'Plan',
+          defaultModelId: 'openai/gpt-4o',
+          instructions: 'Plan things.',
+        },
+      ],
+      agent: baseAgent,
+    });
+
+    await harness.init();
+
+    // After init, signal provider's connected agent (the base agent) should have memory
+    const connectedAgent = signalProvider.getConnectedAgent()!;
+    expect(connectedAgent).toBe(baseAgent);
+    expect(connectedAgent.hasOwnMemory()).toBe(true);
+  });
 });