macro-agent 0.1.1 → 0.1.2

package/src/teams/__tests__/team-system.test.ts

@@ -17,6 +17,8 @@ import type { MessageRouter } from "../../router/message-router.js";
 import type { EventStore } from "../../store/event-store.js";
 import type { SpawnAgentOptions } from "../../agent/types.js";
 import type { AgentId, Event } from "../../store/types/index.js";
+import { TeamLoadError } from "../types.js";
+import type { MacroResolvedTemplate, ResolvedTeamRole, McpServerEntry } from "../types.js";
 
 // =============================================================================
 // Helpers
@@ -209,7 +211,7 @@ describe("Team Template Loading", () => {
     const manifest = await loadTeam("structured", roleRegistry, PROJECT_ROOT);
 
     expect(manifest.name).toBe("structured");
-    expect(manifest.roles).toEqual(["lead", "developer", "reviewer"]);
+    expect(manifest.roles).toEqual(["lead", "developer", "reviewer", "merger"]);
     expect(manifest.macro_agent.task_assignment?.mode).toBe("push");
     expect(manifest.macro_agent.integration?.strategy).toBe("queue");
   });
@@ -283,12 +285,23 @@ describe("TeamRuntime", () => {
       );
     });
 
-    it("sets spawn interceptor on agent manager", async () => {
+    it("does not install spawn interceptor directly (TeamManager responsibility)", async () => {
       const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
       const runtime = new TeamRuntime(manifest, services);
 
       await runtime.initialize();
 
+      // initialize() no longer installs interceptor — that's TeamManager's job
+      expect(agentManager.setSpawnInterceptor).not.toHaveBeenCalled();
+    });
+
+    it("installOnServices() sets spawn interceptor on agent manager", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+      runtime.installOnServices();
+
       expect(agentManager.setSpawnInterceptor).toHaveBeenCalledWith(
         expect.any(Function)
       );
@@ -401,6 +414,7 @@ describe("TeamRuntime", () => {
       const runtime = new TeamRuntime(manifest, services);
 
       await runtime.initialize();
+      runtime.installOnServices();
       await runtime.bootstrap();
 
       // Now spawn a grinder through the interceptor
@@ -422,6 +436,7 @@ describe("TeamRuntime", () => {
       const runtime = new TeamRuntime(manifest, services);
 
       await runtime.initialize();
+      runtime.installOnServices();
       await runtime.bootstrap();
 
       // Spawn a grinder
@@ -442,6 +457,7 @@ describe("TeamRuntime", () => {
       const runtime = new TeamRuntime(manifest, services);
 
       await runtime.initialize();
+      runtime.installOnServices();
       await runtime.bootstrap();
 
       const customPrompt = "My custom prompt";
@@ -479,14 +495,33 @@ describe("TeamRuntime", () => {
   });
 
   describe("teardown()", () => {
-    it("clears spawn interceptor", async () => {
+    it("does not clear interceptor directly (caller responsibility)", async () => {
       const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
       const runtime = new TeamRuntime(manifest, services);
 
       await runtime.initialize();
+      runtime.installOnServices();
       await runtime.bootstrap();
+
+      // Reset mock to track only teardown-related calls
+      vi.mocked(agentManager.setSpawnInterceptor).mockClear();
+
       await runtime.teardown();
 
+      // teardown() no longer clears interceptor — that's the caller's responsibility
+      expect(agentManager.setSpawnInterceptor).not.toHaveBeenCalled();
+    });
+
+    it("uninstallFromServices() clears spawn interceptor", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+      runtime.installOnServices();
+      await runtime.bootstrap();
+      await runtime.teardown();
+      runtime.uninstallFromServices();
+
       expect(agentManager.setSpawnInterceptor).toHaveBeenLastCalledWith(null);
     });
   });
@@ -679,13 +714,17 @@ describe("TeamRuntime", () => {
   });
 
   describe("signal filtering", () => {
-    it("installs signal filter on message router after bootstrap", async () => {
+    it("installOnServices() installs signal filter on message router", async () => {
       const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
       const runtime = new TeamRuntime(manifest, services);
 
       await runtime.initialize();
+      // bootstrap/initialize alone should NOT install filter
       await runtime.bootstrap();
+      expect(messageRouter.setSignalFilter).not.toHaveBeenCalled();
 
+      // installOnServices() installs the filter
+      runtime.installOnServices();
       expect(messageRouter.setSignalFilter).toHaveBeenCalledTimes(1);
       expect(messageRouter.setSignalFilter).toHaveBeenCalledWith(expect.any(Function));
     });
@@ -696,6 +735,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       // Extract the installed filter
       const filterFn = vi.mocked(messageRouter.setSignalFilter).mock.calls[0][0] as (
@@ -716,6 +756,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const filterFn = vi.mocked(messageRouter.setSignalFilter).mock.calls[0][0] as (
         from: string, to: string, signal: string | undefined
@@ -734,6 +775,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const filterFn = vi.mocked(messageRouter.setSignalFilter).mock.calls[0][0] as (
         from: string, to: string, signal: string | undefined
@@ -752,6 +794,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const filterFn = vi.mocked(messageRouter.setSignalFilter).mock.calls[0][0] as (
         from: string, to: string, signal: string | undefined
@@ -773,6 +816,7 @@ describe("TeamRuntime", () => {
       const runtime2 = new TeamRuntime(manifest, services);
       await runtime2.initialize();
       const result2 = await runtime2.bootstrap();
+      runtime2.installOnServices();
 
       // Simulate grinder spawn via lifecycle event
       const deferredCallback = vi.mocked(agentManager.onLifecycleEvent).mock.calls.at(-2)![0];
@@ -799,6 +843,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const filterFn = vi.mocked(messageRouter.setSignalFilter).mock.calls[0][0] as (
         from: string, to: string, signal: string | undefined
@@ -817,6 +862,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const filterFn = vi.mocked(messageRouter.setSignalFilter).mock.calls[0][0] as (
         from: string, to: string, signal: string | undefined
@@ -833,13 +879,17 @@ describe("TeamRuntime", () => {
   });
 
   describe("emission validation", () => {
-    it("installs emission validator on message router after bootstrap", async () => {
+    it("installOnServices() installs emission validator on message router", async () => {
       const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
       const runtime = new TeamRuntime(manifest, services);
 
       await runtime.initialize();
       await runtime.bootstrap();
+      // bootstrap alone should NOT install validator
+      expect(messageRouter.setEmissionValidator).not.toHaveBeenCalled();
 
+      // installOnServices() installs the validator
+      runtime.installOnServices();
       expect(messageRouter.setEmissionValidator).toHaveBeenCalledTimes(1);
       expect(messageRouter.setEmissionValidator).toHaveBeenCalledWith(expect.any(Function));
     });
@@ -850,6 +900,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const validatorFn = vi.mocked(messageRouter.setEmissionValidator).mock.calls[0][0] as (
         agentId: string, signal: string | undefined
@@ -869,6 +920,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const validatorFn = vi.mocked(messageRouter.setEmissionValidator).mock.calls[0][0] as (
         agentId: string, signal: string | undefined
@@ -890,6 +942,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const validatorFn = vi.mocked(messageRouter.setEmissionValidator).mock.calls[0][0] as (
         agentId: string, signal: string | undefined
@@ -909,6 +962,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const validatorFn = vi.mocked(messageRouter.setEmissionValidator).mock.calls[0][0] as (
         agentId: string, signal: string | undefined
@@ -928,6 +982,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       const result = await runtime.bootstrap();
+      runtime.installOnServices();
 
       const validatorFn = vi.mocked(messageRouter.setEmissionValidator).mock.calls[0][0] as (
         agentId: string, signal: string | undefined
@@ -945,6 +1000,7 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       await runtime.bootstrap();
+      runtime.installOnServices();
 
       const validatorFn = vi.mocked(messageRouter.setEmissionValidator).mock.calls[0][0] as (
         agentId: string, signal: string | undefined
@@ -961,7 +1017,9 @@ describe("TeamRuntime", () => {
 
       await runtime.initialize();
       await runtime.bootstrap();
+      runtime.installOnServices();
 
+      // createEmissionValidator() returns null when no emissions → setEmissionValidator not called
       expect(messageRouter.setEmissionValidator).not.toHaveBeenCalled();
     });
 
@@ -988,6 +1046,119 @@ describe("TeamRuntime", () => {
     });
   });
 
+  describe("exposed factory methods (for TeamManager)", () => {
+    it("createSpawnInterceptor() returns a function", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+
+      const interceptor = runtime.createSpawnInterceptor();
+      expect(interceptor).toBeInstanceOf(Function);
+    });
+
+    it("createSpawnInterceptor() injects team context", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+
+      const interceptor = runtime.createSpawnInterceptor();
+      const result = interceptor({
+        task: "test",
+        role: "grinder",
+        parent: "agent_0",
+      });
+
+      expect(result.config?.env?.MACRO_TEAM_NAME).toBe("self-driving");
+      expect(result.config?.env?.MACRO_TASK_MODE).toBe("pull");
+      expect(result.topics).toContain("work_coordination");
+    });
+
+    it("createSignalFilter() returns a function", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+      await runtime.bootstrap();
+
+      const filter = runtime.createSignalFilter();
+      expect(filter).toBeInstanceOf(Function);
+    });
+
+    it("createEmissionValidator() returns a function when emissions exist", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+      await runtime.bootstrap();
+
+      const validator = runtime.createEmissionValidator();
+      expect(validator).toBeInstanceOf(Function);
+    });
+
+    it("createEmissionValidator() returns null when no emissions", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      manifest.communication.emissions = undefined;
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+      await runtime.bootstrap();
+
+      const validator = runtime.createEmissionValidator();
+      expect(validator).toBeNull();
+    });
+
+    it("getAgentRoleMap() returns role mappings after bootstrap", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+      const result = await runtime.bootstrap();
+
+      const roleMap = runtime.getAgentRoleMap();
+      expect(roleMap.get(result.rootId as AgentId)).toBe("planner");
+      expect(roleMap.get(result.companionIds[0] as AgentId)).toBe("judge");
+    });
+
+    it("registerAgent() adds agent to role map", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+      await runtime.bootstrap();
+
+      runtime.registerAgent("new_agent" as AgentId, "grinder");
+
+      const roleMap = runtime.getAgentRoleMap();
+      expect(roleMap.get("new_agent" as AgentId)).toBe("grinder");
+    });
+
+    it("hasAgent() returns true for known agents", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+      const result = await runtime.bootstrap();
+
+      expect(runtime.hasAgent(result.rootId)).toBe(true);
+      expect(runtime.hasAgent(result.companionIds[0])).toBe(true);
+      expect(runtime.hasAgent("unknown_agent")).toBe(false);
+    });
+
+    it("hasAgent() includes dynamically registered agents", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+      await runtime.bootstrap();
+
+      expect(runtime.hasAgent("dynamic_agent")).toBe(false);
+      runtime.registerAgent("dynamic_agent" as AgentId, "grinder");
+      expect(runtime.hasAgent("dynamic_agent")).toBe(true);
+    });
+  });
+
   describe("monitorContinuations()", () => {
     it("auto-continues root agent on unexpected stop", async () => {
       const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
@@ -1133,9 +1304,9 @@ describe("TeamRuntime", () => {
       await runtime.initialize();
       const result = await runtime.bootstrap();
 
-      // Root (lead) + 1 companion (reviewer)
-      expect(agentManager.spawn).toHaveBeenCalledTimes(2);
-      expect(result.companionIds).toHaveLength(1);
+      // Root (lead) + 2 companions (reviewer, merger)
+      expect(agentManager.spawn).toHaveBeenCalledTimes(3);
+      expect(result.companionIds).toHaveLength(2);
 
       // Verify no pull-mode interaction patterns injected
       const rootCall = vi.mocked(agentManager.spawn).mock.calls[0][0];
@@ -1278,3 +1449,1115 @@ describe("Metrics Module", () => {
     expect(metrics.recentErrors).toEqual([]);
   });
 });
+
+// =============================================================================
+// Tests: openteams Migration — Loader Hooks & Error Mapping
+// =============================================================================
+
+describe("openteams Migration: Team Loader", () => {
+  let roleRegistry: DefaultRoleRegistry;
+
+  beforeEach(() => {
+    roleRegistry = new DefaultRoleRegistry();
+  });
+
+  describe("buildResolvedTeamRole — enforcement fields", () => {
+    it("maps macro_agent.workspace from role YAML to RoleDefinition", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // judge.yaml has workspace config
+      const judge = manifest._resolvedRoles.get("judge")!;
+      expect(judge.roleDefinition.workspace).toEqual({
+        type: "own",
+        branchPattern: "judge/{agent-id}",
+        cleanupOnTerminate: true,
+      });
+    });
+
+    it("maps macro_agent.lifecycle from role YAML to RoleDefinition", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // planner.yaml has lifecycle: type: daemon, cascade_terminate: true
+      const planner = manifest._resolvedRoles.get("planner")!;
+      expect(planner.roleDefinition.lifecycle).toEqual({
+        type: "daemon",
+        cascadeTerminate: true,
+      });
+
+      // grinder.yaml has lifecycle: type: ephemeral, task_bound: false, max_duration_ms, self_cleanup
+      const grinder = manifest._resolvedRoles.get("grinder")!;
+      expect(grinder.roleDefinition.lifecycle).toEqual({
+        type: "ephemeral",
+        taskBound: false,
+        maxDurationMs: 3600000,
+        selfCleanup: true,
+      });
+    });
+
+    it("falls back to parent role workspace/lifecycle when no macro_agent override", async () => {
+      const manifest = await loadTeam("structured", roleRegistry, PROJECT_ROOT);
+
+      // structured roles don't have macro_agent workspace/lifecycle in their YAML
+      // so they inherit from parent role definitions
+      const developer = manifest._resolvedRoles.get("developer")!;
+      // Worker parent has workspace config
+      const parentWorker = roleRegistry.resolveRole("worker");
+      expect(developer.roleDefinition.workspace).toEqual(parentWorker.workspace);
+    });
+
+    it("preserves parent role tools and protocol", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const grinder = manifest._resolvedRoles.get("grinder")!;
+      const parentWorker = roleRegistry.resolveRole("worker");
+      expect(grinder.roleDefinition.tools).toEqual(parentWorker.tools);
+      expect(grinder.roleDefinition.protocol).toEqual(parentWorker.protocol);
+    });
+
+    it("sets correct baseRole from extends chain", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // All roles should reference their base role
+      expect(manifest._resolvedRoles.get("planner")!.baseRole).toBe("coordinator");
+      expect(manifest._resolvedRoles.get("grinder")!.baseRole).toBe("worker");
+      expect(manifest._resolvedRoles.get("judge")!.baseRole).toBe("monitor");
+    });
+
+    it("stores prompt file path in resolved role", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const planner = manifest._resolvedRoles.get("planner")!;
+      expect(planner.prompt).toBe("prompts/planner.md");
+
+      const grinder = manifest._resolvedRoles.get("grinder")!;
+      expect(grinder.prompt).toBe("prompts/grinder.md");
+    });
+  });
+
+  describe("enrichRoleWithSpawnRules hook", () => {
+    it("adds agent.spawn.* capabilities from spawn_rules", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // planner: [grinder, planner]
+      const planner = manifest._resolvedRoles.get("planner")!;
+      expect(planner.capabilities).toContain("agent.spawn.grinder");
+      expect(planner.capabilities).toContain("agent.spawn.planner");
+    });
+
+    it("does not duplicate existing spawn capabilities", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const planner = manifest._resolvedRoles.get("planner")!;
+      const spawnGrinderCount = planner.capabilities.filter(
+        (c) => c === "agent.spawn.grinder"
+      ).length;
+      expect(spawnGrinderCount).toBe(1);
+    });
+
+    it("does not add spawn capabilities for roles with empty spawn_rules", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // judge: [] in spawn_rules — should not have spawn caps added by enrichRoleWithSpawnRules
+      // (judge extends monitor which has no spawn caps)
+      const judge = manifest._resolvedRoles.get("judge")!;
+      const spawnCaps = judge.capabilities.filter((c) => c.startsWith("agent.spawn."));
+      expect(spawnCaps).toEqual([]);
+
+      // grinder: [] in spawn_rules — grinder extends worker which has agent.spawn.worker
+      // from parent, but enrichRoleWithSpawnRules should NOT add any additional spawn caps
+      const grinder = manifest._resolvedRoles.get("grinder")!;
+      const grinderSpawnCaps = grinder.capabilities.filter((c) => c.startsWith("agent.spawn."));
+      // Only has parent-inherited spawn caps, not new ones from spawn_rules
+      expect(grinderSpawnCaps).not.toContain("agent.spawn.grinder");
+      expect(grinderSpawnCaps).not.toContain("agent.spawn.planner");
+    });
+  });
+
+  describe("mapRegistryRole hook", () => {
+    it("resolves known registry roles for extends chains", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // planner extends coordinator — coordinator should be resolvable
+      const planner = manifest._resolvedRoles.get("planner")!;
+      expect(planner.baseRole).toBe("coordinator");
+
+      // Coordinator capabilities should be in the planner's set (minus removals, plus additions)
+      const coordinatorRole = roleRegistry.resolveRole("coordinator");
+      // planner should have coordinator capabilities minus removed ones
+      for (const cap of coordinatorRole.capabilities) {
+        if (cap !== "agent.spawn.integrator" && cap !== "agent.spawn.monitor") {
+          expect(planner.capabilities).toContain(cap);
+        }
+      }
+    });
+  });
+
+  describe("prompt loading and assembly", () => {
+    it("loads prompts keyed by role promptFile path", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // Prompts should be stored under the role's promptFile key
+      expect(manifest._loadedPrompts.has("prompts/planner.md")).toBe(true);
+      expect(manifest._loadedPrompts.has("prompts/grinder.md")).toBe(true);
+      expect(manifest._loadedPrompts.has("prompts/judge.md")).toBe(true);
+    });
+
+    it("loads prompts keyed by topology node prompt path", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // Root topology node has prompt: prompts/planner.md
+      // It should also be stored under that topology key
+      expect(manifest._loadedPrompts.get("prompts/planner.md")).toBeDefined();
+      expect(manifest._loadedPrompts.get("prompts/planner.md")!.length).toBeGreaterThan(0);
+    });
+
+    it("prompt content matches actual file content", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const plannerPrompt = manifest._loadedPrompts.get("prompts/planner.md")!;
+      // Should contain the role name from the actual prompt file
+      expect(plannerPrompt).toContain("Planner");
+    });
+  });
+
+  describe("MCP server loading", () => {
+    it("provides _mcpServers map (even if empty)", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      expect(manifest._mcpServers).toBeDefined();
+      expect(manifest._mcpServers).toBeInstanceOf(Map);
+    });
+  });
+
+  describe("error mapping", () => {
+    it("throws MANIFEST_NOT_FOUND for non-existent team", async () => {
+      await expect(
+        loadTeam("nonexistent-team", roleRegistry, PROJECT_ROOT)
+      ).rejects.toThrow(TeamLoadError);
+
+      try {
+        await loadTeam("nonexistent-team", roleRegistry, PROJECT_ROOT);
+      } catch (e) {
+        const err = e as TeamLoadError;
+        expect(err.code).toBe("MANIFEST_NOT_FOUND");
+        expect(err.teamName).toBe("nonexistent-team");
+      }
+    });
+
+    it("includes team name in error", async () => {
+      try {
+        await loadTeam("does-not-exist", roleRegistry, PROJECT_ROOT);
+      } catch (e) {
+        expect(e).toBeInstanceOf(TeamLoadError);
+        expect((e as TeamLoadError).teamName).toBe("does-not-exist");
+      }
+    });
+  });
+
+  describe("communication validation", () => {
+    it("validates self-driving team communication topology", async () => {
+      // Should not throw — well-formed communication config
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      expect(manifest.communication).toBeDefined();
+      expect(manifest.communication.channels).toBeDefined();
+      expect(manifest.communication.subscriptions).toBeDefined();
+      expect(manifest.communication.emissions).toBeDefined();
+      expect(manifest.communication.routing).toBeDefined();
+    });
+
+    it("validates structured team communication topology", async () => {
+      const manifest = await loadTeam("structured", roleRegistry, PROJECT_ROOT);
+      expect(manifest.communication.channels).toBeDefined();
+      expect(Object.keys(manifest.communication.channels!)).toContain("task_updates");
+      expect(Object.keys(manifest.communication.channels!)).toContain("merge_flow");
+      expect(Object.keys(manifest.communication.channels!)).toContain("review_flow");
+    });
+  });
+});
+
+// =============================================================================
+// Tests: openteams Migration — TeamRuntime Type Detection
+// =============================================================================
+
+describe("openteams Migration: TeamRuntime", () => {
+  let roleRegistry: DefaultRoleRegistry;
+  let agentManager: AgentManager;
+  let messageRouter: MessageRouter;
+  let eventStore: EventStore & { _events: Event[] };
+  let services: TeamServices;
+
+  beforeEach(() => {
+    roleRegistry = new DefaultRoleRegistry();
+    eventStore = createMockEventStore() as EventStore & { _events: Event[] };
+    messageRouter = createMockMessageRouter();
+    agentManager = createMockAgentManager(roleRegistry);
+    services = { agentManager, messageRouter, eventStore };
+  });
+
+  describe("MacroResolvedTemplate input", () => {
+    it("accepts MacroResolvedTemplate directly", async () => {
+      // Build a MacroResolvedTemplate from a loaded manifest
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const resolved: MacroResolvedTemplate = {
+        template: {
+          manifest: {
+            name: manifest.name,
+            description: manifest.description,
+            version: manifest.version,
+            roles: manifest.roles,
+            topology: manifest.topology,
+            communication: manifest.communication,
+          },
+          roles: new Map(),
+          prompts: new Map(),
+          mcpServers: manifest._mcpServers,
+          sourcePath: "",
+        },
+        resolvedRoles: manifest._resolvedRoles,
+        macroAgent: manifest.macro_agent,
+      };
+
+      // Should not throw
+      const runtime = new TeamRuntime(resolved, services);
+      expect(runtime.getTaskMode()).toBe("pull");
+      expect(runtime.getStrategyName()).toBe("trunk");
+    });
+
+    it("getResolvedTemplate() returns the resolved template", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const resolved: MacroResolvedTemplate = {
+        template: {
+          manifest: {
+            name: manifest.name,
+            description: manifest.description,
+            version: manifest.version,
+            roles: manifest.roles,
+            topology: manifest.topology,
+            communication: manifest.communication,
+          },
+          roles: new Map(),
+          prompts: new Map(),
+          mcpServers: manifest._mcpServers,
+          sourcePath: "",
+        },
+        resolvedRoles: manifest._resolvedRoles,
+        macroAgent: manifest.macro_agent,
+      };
+
+      const runtime = new TeamRuntime(resolved, services);
+      const result = runtime.getResolvedTemplate();
+
+      expect(result).toBe(resolved);
+      expect(result.resolvedRoles).toBe(manifest._resolvedRoles);
+      expect(result.macroAgent).toBe(manifest.macro_agent);
+    });
+
+    it("initializes and bootstraps with MacroResolvedTemplate", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const resolved: MacroResolvedTemplate = {
+        template: {
+          manifest: {
+            name: manifest.name,
+            description: manifest.description,
+            version: manifest.version,
+            roles: manifest.roles,
+            topology: manifest.topology,
+            communication: manifest.communication,
+          },
+          roles: new Map(),
+          prompts: new Map(),
+          mcpServers: manifest._mcpServers,
+          sourcePath: "",
+        },
+        resolvedRoles: manifest._resolvedRoles,
+        macroAgent: manifest.macro_agent,
+      };
+
+      const runtime = new TeamRuntime(resolved, services);
+      await runtime.initialize();
+      const result = await runtime.bootstrap();
+
+      expect(result.rootId).toBeDefined();
+      expect(result.companionIds).toHaveLength(1);
+      expect(agentManager.spawn).toHaveBeenCalledTimes(2);
+    });
+
+    it("emits team_config event with MacroResolvedTemplate", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const resolved: MacroResolvedTemplate = {
+        template: {
+          manifest: {
+            name: manifest.name,
+            description: manifest.description,
+            version: manifest.version,
+            roles: manifest.roles,
+            topology: manifest.topology,
+            communication: manifest.communication,
+          },
+          roles: new Map(),
+          prompts: new Map(),
+          mcpServers: manifest._mcpServers,
+          sourcePath: "",
+        },
+        resolvedRoles: manifest._resolvedRoles,
+        macroAgent: manifest.macro_agent,
+      };
+
+      const runtime = new TeamRuntime(resolved, services);
+      await runtime.initialize();
+
+      expect(eventStore.emit).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: "status",
+          payload: expect.objectContaining({
+            team_config: expect.objectContaining({
+              teamName: "self-driving",
+              strategy: "trunk",
+              taskMode: "pull",
+            }),
+          }),
+        })
+      );
+    });
+  });
+
+  describe("manifestToResolved conversion", () => {
+    it("converts legacy TeamManifest to MacroResolvedTemplate internally", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // Pass TeamManifest (legacy path)
+      const runtime = new TeamRuntime(manifest, services);
+      const resolved = runtime.getResolvedTemplate();
+
+      // Should have been converted internally
+      expect(resolved.template.manifest.name).toBe("self-driving");
+      expect(resolved.resolvedRoles).toBe(manifest._resolvedRoles);
+      expect(resolved.macroAgent).toBe(manifest.macro_agent);
+      expect(resolved.template.mcpServers).toBe(manifest._mcpServers);
+    });
+
+    it("preserves topology and communication in conversion", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const runtime = new TeamRuntime(manifest, services);
+      const resolved = runtime.getResolvedTemplate();
+
+      expect(resolved.template.manifest.topology).toBe(manifest.topology);
+      expect(resolved.template.manifest.communication).toBe(manifest.communication);
+    });
+  });
+
+  describe("getManifest() backward compatibility", () => {
+    it("reconstructs TeamManifest from MacroResolvedTemplate", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const resolved: MacroResolvedTemplate = {
+        template: {
+          manifest: {
+            name: manifest.name,
+            description: manifest.description,
+            version: manifest.version,
+            roles: manifest.roles,
+            topology: manifest.topology,
+            communication: manifest.communication,
+          },
+          roles: new Map(),
+          prompts: new Map(),
+          mcpServers: manifest._mcpServers,
+          sourcePath: "",
+        },
+        resolvedRoles: manifest._resolvedRoles,
+        macroAgent: manifest.macro_agent,
+      };
+
+      const runtime = new TeamRuntime(resolved, services);
+      const backCompat = runtime.getManifest();
+
+      expect(backCompat.name).toBe("self-driving");
+      expect(backCompat._resolvedRoles).toBe(manifest._resolvedRoles);
+      expect(backCompat._mcpServers).toBe(manifest._mcpServers);
+      expect(backCompat.macro_agent).toBe(manifest.macro_agent);
+    });
+
+    it("reconstructs TeamManifest from legacy TeamManifest input", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const runtime = new TeamRuntime(manifest, services);
+      const backCompat = runtime.getManifest();
+
+      expect(backCompat.name).toBe("self-driving");
+      expect(backCompat._resolvedRoles).toBe(manifest._resolvedRoles);
+      expect(backCompat._loadedPrompts).toBe(manifest._loadedPrompts);
+    });
+  });
+
+  describe("spawn interceptor with MacroResolvedTemplate", () => {
+    it("injects team context when using MacroResolvedTemplate", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      const resolved: MacroResolvedTemplate = {
+        template: {
+          manifest: {
+            name: manifest.name,
+            description: manifest.description,
+            version: manifest.version,
+            roles: manifest.roles,
+            topology: manifest.topology,
+            communication: manifest.communication,
+          },
+          roles: new Map(),
+          prompts: new Map(),
+          mcpServers: manifest._mcpServers,
+          sourcePath: "",
+        },
+        resolvedRoles: manifest._resolvedRoles,
+        macroAgent: manifest.macro_agent,
+      };
+
+      const runtime = new TeamRuntime(resolved, services);
+      await runtime.initialize();
+      runtime.installOnServices();
+      await runtime.bootstrap();
+
+      // Spawn a grinder through the interceptor
+      await agentManager.spawn({
+        task: "test grinder task",
+        role: "grinder",
+        parent: "agent_0",
+      });
+
+      const lastOpts = interceptedSpawnOptions.at(-1)!;
+      expect(lastOpts.config?.env?.MACRO_TEAM_NAME).toBe("self-driving");
+      expect(lastOpts.config?.env?.MACRO_TASK_MODE).toBe("pull");
+      expect(lastOpts.topics).toContain("work_coordination");
+    });
+
+    it("resolves MCP servers from MacroResolvedTemplate", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+
+      // Add a mock MCP server for grinder
+      const mcpServers = new Map<string, McpServerEntry[]>();
+      mcpServers.set("grinder", [{
+        name: "test-server",
+        command: "node",
+        args: ["test.js"],
+      }]);
+
+      const resolved: MacroResolvedTemplate = {
+        template: {
+          manifest: {
+            name: manifest.name,
+            description: manifest.description,
+            version: manifest.version,
+            roles: manifest.roles,
+            topology: manifest.topology,
+            communication: manifest.communication,
+          },
+          roles: new Map(),
+          prompts: new Map(),
+          mcpServers,
+          sourcePath: "",
+        },
+        resolvedRoles: manifest._resolvedRoles,
+        macroAgent: manifest.macro_agent,
+      };
+
+      const runtime = new TeamRuntime(resolved, services);
+      await runtime.initialize();
+      runtime.installOnServices();
+      await runtime.bootstrap();
+
+      // Spawn a grinder
+      await agentManager.spawn({
+        task: "test task",
+        role: "grinder",
+        parent: "agent_0",
+      });
+
+      const lastOpts = interceptedSpawnOptions.at(-1)!;
+      expect(lastOpts.config?.mcpServers).toBeDefined();
+      expect(lastOpts.config?.mcpServers!.length).toBeGreaterThanOrEqual(1);
+      expect(lastOpts.config?.mcpServers!.some((s: any) => s.name === "test-server")).toBe(true);
+    });
+  });
+
+  describe("serialized roles in team_config", () => {
+    it("serializes resolved roles with capabilities", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+
+      const emitCall = vi.mocked(eventStore.emit).mock.calls[0][0] as any;
+      const serializedRoles = emitCall.payload.team_config.roles;
+
+      expect(serializedRoles.planner).toBeDefined();
+      expect(serializedRoles.planner.name).toBe("planner");
+      expect(serializedRoles.planner.capabilities).toContain("task.claim");
+      expect(serializedRoles.planner.capabilities).toContain("agent.spawn.grinder");
+
+      expect(serializedRoles.grinder).toBeDefined();
+      expect(serializedRoles.grinder.name).toBe("grinder");
+      expect(serializedRoles.grinder.capabilities).toContain("task.claim");
+      expect(serializedRoles.grinder.capabilities).toContain("git.push");
+
+      expect(serializedRoles.judge).toBeDefined();
+      expect(serializedRoles.judge.name).toBe("judge");
+    });
+
+    it("includes lifecycle and description in serialized roles", async () => {
+      const manifest = await loadTeam("self-driving", roleRegistry, PROJECT_ROOT);
+      const runtime = new TeamRuntime(manifest, services);
+
+      await runtime.initialize();
+
+      const emitCall = vi.mocked(eventStore.emit).mock.calls[0][0] as any;
+      const serializedRoles = emitCall.payload.team_config.roles;
+
+      // planner has lifecycle config
+      expect(serializedRoles.planner.lifecycle).toBeDefined();
+
+      // All roles have descriptions
+      expect(serializedRoles.planner.description).toBeDefined();
+      expect(serializedRoles.grinder.description).toBeDefined();
+      expect(serializedRoles.judge.description).toBeDefined();
+    });
+  });
+});
+
+// =============================================================================
+// Tests: Auto-Scaling
+// =============================================================================
+
+describe("TeamRuntime auto-scaling", () => {
+  let roleRegistry: DefaultRoleRegistry;
+  let agentManager: AgentManager;
+  let messageRouter: MessageRouter;
+  let eventStore: EventStore;
+
+  beforeEach(() => {
+    roleRegistry = new DefaultRoleRegistry();
+    eventStore = createMockEventStore();
+    messageRouter = createMockMessageRouter();
+    agentManager = createMockAgentManager(roleRegistry);
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function createScalingTemplate(scalingConfig: {
+    min_workers?: number;
+    max_workers?: number;
+    scale_on?: "task_queue_depth" | "manual";
+    idle_drain?: boolean;
+  }): MacroResolvedTemplate {
+    const workerRole: ResolvedTeamRole = {
+      name: "grinder",
+      baseRole: "worker",
+      capabilities: ["file.read", "file.write", "task.claim", "lifecycle.done"],
+      roleDefinition: {
+        name: "grinder",
+        capabilities: ["file.read", "file.write", "task.claim", "lifecycle.done"],
+      },
+    };
+
+    const plannerRole: ResolvedTeamRole = {
+      name: "planner",
+      baseRole: "coordinator",
+      capabilities: ["*"],
+      roleDefinition: {
+        name: "planner",
+        capabilities: ["*"],
+      },
+    };
+
+    return {
+      template: {
+        manifest: {
+          name: "test-scaling",
+          version: 1,
+          roles: ["planner", "grinder"],
+          topology: {
+            root: { role: "planner", prompt: "prompts/planner.md" },
+            spawn_rules: { planner: ["grinder"], grinder: [] },
+          },
+        },
+        roles: new Map(),
+        prompts: new Map(),
+        mcpServers: new Map<string, McpServerEntry[]>(),
+        sourcePath: "",
+      },
+      resolvedRoles: new Map<string, ResolvedTeamRole>([
+        ["planner", plannerRole],
+        ["grinder", workerRole],
+      ]),
+      macroAgent: {
+        task_assignment: { mode: "pull" as const },
+        lifecycle: { scaling: scalingConfig },
+      },
+    };
+  }
+
+  it("spawns worker when task queue depth exceeds active workers", async () => {
+    const mockTaskBackend = {
+      listClaimable: vi.fn().mockResolvedValue([
+        { id: "t1", title: "Task 1" },
+        { id: "t2", title: "Task 2" },
+      ]),
+    };
+
+    // No active workers initially
+    vi.mocked(agentManager.list).mockReturnValue([]);
+
+    const services: TeamServices = {
+      agentManager, messageRouter, eventStore,
+      taskBackend: mockTaskBackend as any,
+    };
+
+    const resolved = createScalingTemplate({
+      max_workers: 5,
+      scale_on: "task_queue_depth",
+    });
+    const runtime = new TeamRuntime(resolved, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    // Advance timer to trigger scaling check (5s interval)
+    await vi.advanceTimersByTimeAsync(5_100);
+
+    // Should have spawned a grinder as child of root
+    const spawnCalls = vi.mocked(agentManager.spawn).mock.calls;
+    const scalingSpawn = spawnCalls.find(
+      call => call[0].role === "grinder" && call[0].parent !== null && call[0].task?.includes("auto-scaled")
+    );
+    expect(scalingSpawn).toBeDefined();
+
+    await runtime.teardown();
+  });
+
+  it("respects max_workers cap", async () => {
+    const mockTaskBackend = {
+      listClaimable: vi.fn().mockResolvedValue([
+        { id: "t1", title: "Task 1" },
+        { id: "t2", title: "Task 2" },
+      ]),
+    };
+
+    // Already at max workers
+    vi.mocked(agentManager.list).mockReturnValue([
+      { id: "w1", role: "grinder", state: "running" } as any,
+      { id: "w2", role: "grinder", state: "running" } as any,
+    ]);
+
+    const services: TeamServices = {
+      agentManager, messageRouter, eventStore,
+      taskBackend: mockTaskBackend as any,
+    };
+
+    const resolved = createScalingTemplate({
+      max_workers: 2,
+      scale_on: "task_queue_depth",
+    });
+    const runtime = new TeamRuntime(resolved, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    // Register the workers in the runtime's agentRoleMap
+    runtime.registerAgent("w1" as AgentId, "grinder");
+    runtime.registerAgent("w2" as AgentId, "grinder");
+
+    const spawnCountBefore = vi.mocked(agentManager.spawn).mock.calls.length;
+
+    await vi.advanceTimersByTimeAsync(5_100);
+
+    // No additional spawns — already at max
+    const scalingSpawns = vi.mocked(agentManager.spawn).mock.calls.slice(spawnCountBefore).filter(
+      call => call[0].task?.includes("auto-scaled")
+    );
+    expect(scalingSpawns).toHaveLength(0);
+
+    await runtime.teardown();
+  });
+
+  it("does not spawn when scale_on is not task_queue_depth", async () => {
+    const mockTaskBackend = {
+      listClaimable: vi.fn().mockResolvedValue([
+        { id: "t1", title: "Task 1" },
+      ]),
+    };
+
+    const services: TeamServices = {
+      agentManager, messageRouter, eventStore,
+      taskBackend: mockTaskBackend as any,
+    };
+
+    const resolved = createScalingTemplate({
+      max_workers: 5,
+      scale_on: "manual",
+    });
+    const runtime = new TeamRuntime(resolved, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    const spawnCountBefore = vi.mocked(agentManager.spawn).mock.calls.length;
+
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    // No scaling spawns
+    const scalingSpawns = vi.mocked(agentManager.spawn).mock.calls.slice(spawnCountBefore).filter(
+      call => call[0].task?.includes("auto-scaled")
+    );
+    expect(scalingSpawns).toHaveLength(0);
+
+    // listClaimable should not have been called
+    expect(mockTaskBackend.listClaimable).not.toHaveBeenCalled();
+
+    await runtime.teardown();
+  });
+
+  it("respects cooldown between scale-up actions", async () => {
+    const mockTaskBackend = {
+      listClaimable: vi.fn().mockResolvedValue([
+        { id: "t1" }, { id: "t2" }, { id: "t3" },
+      ]),
+    };
+
+    vi.mocked(agentManager.list).mockReturnValue([]);
+
+    const services: TeamServices = {
+      agentManager, messageRouter, eventStore,
+      taskBackend: mockTaskBackend as any,
+    };
+
+    const resolved = createScalingTemplate({
+      max_workers: 10,
+      scale_on: "task_queue_depth",
+    });
+    const runtime = new TeamRuntime(resolved, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    const spawnCountBefore = vi.mocked(agentManager.spawn).mock.calls.length;
+
+    // First tick at 5s — should spawn
+    await vi.advanceTimersByTimeAsync(5_100);
+    const afterFirst = vi.mocked(agentManager.spawn).mock.calls.slice(spawnCountBefore).filter(
+      call => call[0].task?.includes("auto-scaled")
+    );
+    expect(afterFirst).toHaveLength(1);
+
+    // Second tick at 10s — cooldown (10s from first spawn) not elapsed
+    await vi.advanceTimersByTimeAsync(5_000);
+    const afterSecond = vi.mocked(agentManager.spawn).mock.calls.slice(spawnCountBefore).filter(
+      call => call[0].task?.includes("auto-scaled")
+    );
+    expect(afterSecond).toHaveLength(1); // Still just 1
+
+    // Third tick at 15s — cooldown elapsed, should spawn again
+    await vi.advanceTimersByTimeAsync(5_100);
+    const afterThird = vi.mocked(agentManager.spawn).mock.calls.slice(spawnCountBefore).filter(
+      call => call[0].task?.includes("auto-scaled")
+    );
+    expect(afterThird).toHaveLength(2);
+
+    await runtime.teardown();
+  });
+});
+
+// =============================================================================
+// Tests: Workspace Isolation (Capability-Based)
+// =============================================================================
+
+describe("Workspace Isolation", () => {
+  let roleRegistry: DefaultRoleRegistry;
+  let agentManager: AgentManager;
+  let messageRouter: MessageRouter;
+  let eventStore: EventStore;
+
+  beforeEach(() => {
+    roleRegistry = new DefaultRoleRegistry();
+    agentManager = createMockAgentManager(roleRegistry);
+    messageRouter = createMockMessageRouter();
+    eventStore = createMockEventStore();
+  });
+
+  function createWorkspaceTemplate(): MacroResolvedTemplate {
+    const resolvedRoles = new Map<string, ResolvedTeamRole>();
+    resolvedRoles.set("lead", {
+      name: "lead",
+      baseRole: "coordinator",
+      capabilities: [
+        "file.read", "file.write", "task.create", "task.assign",
+        "agent.spawn.worker", "agent.terminate", "workspace.stream",
+      ],
+      roleDefinition: roleRegistry.resolveRole("coordinator"),
+    });
+    resolvedRoles.set("developer", {
+      name: "developer",
+      baseRole: "worker",
+      capabilities: [
+        "file.read", "file.write", "git.commit", "lifecycle.done",
+        "workspace.worktree",
+      ],
+      roleDefinition: roleRegistry.resolveRole("worker"),
+    });
+    resolvedRoles.set("merger", {
+      name: "merger",
+      baseRole: "integrator",
+      capabilities: [
+        "file.read", "file.write", "git.merge", "lifecycle.done",
+        "workspace.integrate",
+      ],
+      roleDefinition: roleRegistry.resolveRole("integrator"),
+    });
+    resolvedRoles.set("watcher", {
+      name: "watcher",
+      baseRole: "monitor",
+      capabilities: ["file.read", "msg.send"],
+      roleDefinition: roleRegistry.resolveRole("monitor"),
+    });
+
+    return {
+      template: {
+        manifest: {
+          name: "workspace-test",
+          version: 1,
+          roles: ["lead", "developer", "merger", "watcher"],
+          topology: {
+            root: { role: "lead" },
+            companions: [{ role: "merger" }],
+          },
+          communication: {},
+        },
+        roles: new Map(),
+        prompts: new Map(),
+        mcpServers: new Map<string, McpServerEntry[]>(),
+        sourcePath: "",
+      },
+      resolvedRoles,
+      macroAgent: {
+        integration: { strategy: "queue" },
+        task_assignment: { mode: "push" as const },
+      },
+    };
+  }
+
+  it("spawn interceptor injects streamId for role with workspace.worktree", async () => {
+    const template = createWorkspaceTemplate();
+    const mockWorkspaceManager = {
+      createIntegrationStream: vi.fn().mockReturnValue("stream-1"),
+      getMergeQueue: vi.fn().mockReturnValue(null),
+      getWorkspace: vi.fn(),
+    };
+
+    const services: TeamServices = {
+      agentManager,
+      messageRouter,
+      eventStore,
+      workspaceManager: mockWorkspaceManager as any,
+    };
+
+    const runtime = new TeamRuntime(template, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    // Now spawn a developer (extends worker) through the interceptor
+    const interceptor = runtime.createSpawnInterceptor();
+    const result = interceptor({
+      task: "implement feature",
+      role: "developer",
+      parent: "agent_0",
+    });
+
+    expect(result.streamId).toBe("stream-1");
+    expect(result.dataplaneTaskId).toBeDefined();
+    expect(result.capabilities).toContain("workspace.worktree");
+
+    await runtime.teardown();
+  });
+
+  it("spawn interceptor injects streamId for role with workspace.integrate", async () => {
+    const template = createWorkspaceTemplate();
+    const mockWorkspaceManager = {
+      createIntegrationStream: vi.fn().mockReturnValue("stream-1"),
+      getMergeQueue: vi.fn().mockReturnValue(null),
+      getWorkspace: vi.fn(),
+    };
+
+    const services: TeamServices = {
+      agentManager,
+      messageRouter,
+      eventStore,
+      workspaceManager: mockWorkspaceManager as any,
+    };
+
+    const runtime = new TeamRuntime(template, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    const interceptor = runtime.createSpawnInterceptor();
+    const result = interceptor({
+      task: "merge changes",
+      role: "merger",
+      parent: "agent_0",
+    });
+
+    expect(result.streamId).toBe("stream-1");
+    expect(result.dataplaneTaskId).toBeUndefined(); // Integrators don't get dataplaneTaskId
+    expect(result.capabilities).toContain("workspace.integrate");
+
+    await runtime.teardown();
+  });
+
+  it("spawn interceptor does NOT inject workspace fields for role without workspace capability", async () => {
+    const template = createWorkspaceTemplate();
+    const mockWorkspaceManager = {
+      createIntegrationStream: vi.fn().mockReturnValue("stream-1"),
+      getMergeQueue: vi.fn().mockReturnValue(null),
+      getWorkspace: vi.fn(),
+    };
+
+    const services: TeamServices = {
+      agentManager,
+      messageRouter,
+      eventStore,
+      workspaceManager: mockWorkspaceManager as any,
+    };
+
+    const runtime = new TeamRuntime(template, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    const interceptor = runtime.createSpawnInterceptor();
+    const result = interceptor({
+      task: "monitor health",
+      role: "watcher",
+      parent: "agent_0",
+    });
+
+    // Monitor role has no workspace capabilities
+    expect(result.streamId).toBeUndefined();
+    expect(result.streamConfig).toBeUndefined();
+    expect(result.dataplaneTaskId).toBeUndefined();
+
+    await runtime.teardown();
+  });
+
+  it("spawn interceptor does not overwrite explicit workspace values", async () => {
+    const template = createWorkspaceTemplate();
+    const mockWorkspaceManager = {
+      createIntegrationStream: vi.fn().mockReturnValue("stream-1"),
+      getMergeQueue: vi.fn().mockReturnValue(null),
+      getWorkspace: vi.fn(),
+    };
+
+    const services: TeamServices = {
+      agentManager,
+      messageRouter,
+      eventStore,
+      workspaceManager: mockWorkspaceManager as any,
+    };
+
+    const runtime = new TeamRuntime(template, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    const interceptor = runtime.createSpawnInterceptor();
+    const result = interceptor({
+      task: "implement feature",
+      role: "developer",
+      parent: "agent_0",
+      streamId: "custom-stream",
+      dataplaneTaskId: "custom-task",
+    });
+
+    // Explicit values should NOT be overwritten
+    expect(result.streamId).toBe("custom-stream");
+    expect(result.dataplaneTaskId).toBe("custom-task");
+
+    await runtime.teardown();
+  });
+
+  it("merge queue mr:submitted event wakes integrator agent", async () => {
+    const template = createWorkspaceTemplate();
+    let mergeQueueCallback: ((event: any) => void) | null = null;
+    const mockMergeQueue = {
+      onEvent: vi.fn((cb: (event: any) => void) => {
+        mergeQueueCallback = cb;
+        return () => { mergeQueueCallback = null; };
+      }),
+    };
+    const mockWorkspaceManager = {
+      createIntegrationStream: vi.fn().mockReturnValue("stream-1"),
+      getMergeQueue: vi.fn().mockReturnValue(mockMergeQueue),
+      getWorkspace: vi.fn(),
+    };
+
+    const services: TeamServices = {
+      agentManager,
+      messageRouter,
+      eventStore,
+      workspaceManager: mockWorkspaceManager as any,
+    };
+
+    const runtime = new TeamRuntime(template, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    // Verify merge queue subscription was set up
+    expect(mockMergeQueue.onEvent).toHaveBeenCalled();
+    expect(mergeQueueCallback).not.toBeNull();
+
+    // Simulate a merge request submission
+    mergeQueueCallback!({
+      type: "mr:submitted",
+      data: {
+        mrId: "mr-123",
+        workerAgentId: "worker-1",
+        workerBranch: "worker/dev-1/task-1@123",
+      },
+    });
+
+    // Should have prompted the merger agent (companion, agent_1)
+    expect(agentManager.prompt).toHaveBeenCalledWith(
+      "agent_1", // merger is the companion agent
+      expect.stringContaining("mr-123"),
+    );
+
+    await runtime.teardown();
+  });
+
+  it("creates integration stream during bootstrap when workspaceManager is available", async () => {
+    const template = createWorkspaceTemplate();
+    const mockWorkspaceManager = {
+      createIntegrationStream: vi.fn().mockReturnValue("stream-42"),
+      getMergeQueue: vi.fn().mockReturnValue(null),
+      getWorkspace: vi.fn(),
+    };
+
+    const services: TeamServices = {
+      agentManager,
+      messageRouter,
+      eventStore,
+      workspaceManager: mockWorkspaceManager as any,
+    };
+
+    const runtime = new TeamRuntime(template, services);
+    await runtime.initialize();
+    await runtime.bootstrap();
+
+    expect(mockWorkspaceManager.createIntegrationStream).toHaveBeenCalledWith(
+      "agent_0", // root agent ID
+      { name: "workspace-test", forkFrom: "main" },
+    );
+    expect(runtime.getTeamStreamId()).toBe("stream-42");
+
+    await runtime.teardown();
+  });
+});