@pensar/apex 2.5.0 → 2.6.1-canary.0cc77dcc

package/src/core/agents/offSecAgent/offensiveSecurityAgent.test.ts

@@ -0,0 +1,2899 @@
+/**
+ * Unit tests for OffensiveSecurityAgent.consume().
+ *
+ * Verifies that the command shell's dispose() is called even when the
+ * fullStream throws — the shell-leak bug described in the PR.
+ *
+ * Heavy transitive dependencies (tools, AI SDK, zod) are stubbed so
+ * the test loads cleanly without external provider keys.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, vi } from "vitest";
+// Direct file import: the barrel "./tools" is mocked below, and this test
+// needs the real registry to exercise its retained-handle retry semantics.
+import { CallbackListenerRegistry } from "./tools/callbackListener";
+
+const toolContexts = vi.hoisted(() => [] as Array<Record<string, unknown>>);
+const streamResponseCalls = vi.hoisted(
+  () => [] as Array<Record<string, unknown>>,
+);
+const traceRecordStepCalls = vi.hoisted(() => [] as unknown[][]);
+
+// ---------------------------------------------------------------------------
+// Module stubs — prevent the full tool/AI/zod import chain from loading.
+//
+// vi.mock factories are hoisted above all imports, so they cannot
+// reference top-level variables. All helper logic must be inlined.
+// ---------------------------------------------------------------------------
+
+vi.mock("zod", () => {
+  const handler: ProxyHandler<CallableFunction> = {
+    get(_target, _prop) {
+      return new Proxy(() => {}, handler);
+    },
+    apply(_target, _thisArg, _args) {
+      return new Proxy(() => {}, handler);
+    },
+  };
+  const z = new Proxy(() => {}, handler);
+  return { z, default: z };
+});
+
+vi.mock("./tools", () => ({
+  // The agent constructs via the selective entrypoint; record the tool
+  // context there (createAllTools kept for any direct legacy callers).
+  createToolsForNames: (
+    ctx: Record<string, unknown>,
+    requested: readonly string[] | undefined,
+  ) => {
+    toolContexts.push(ctx);
+    void requested;
+    return {};
+  },
+  listToolRegistryNames: () => [],
+  createAllTools: (ctx: Record<string, unknown>) => {
+    toolContexts.push(ctx);
+    return {};
+  },
+  EMAIL_TOOL_NAMES_ACTIVE: [],
+  SEND_EMAIL_TOOL_NAME: "send_email",
+  SMS_TOOL_NAMES_ACTIVE: [],
+  sessionHasSmsPasswordless: () => false,
+  PLAN_MODE_TOOL_NAMES: [],
+  FAST_STRIKE_EXCLUDED_TOOL_NAMES: [],
+  createResponseTool: () => {},
+  RESPONSE_TOOL_NAME: "response",
+  ASK_USER_QUESTIONS_TOOL_NAME: "ask_user_questions",
+  WORKSPACE_TOOL_NAMES: [
+    "list_workspace_domains",
+    "create_workspace_domain",
+    "list_workspace_apps",
+    "create_workspace_app",
+    "update_workspace_app",
+    "list_workspace_endpoints",
+    "create_workspace_endpoint",
+    "update_workspace_endpoint",
+  ],
+  WORKSPACE_WRITE_TOOL_NAMES: [
+    "create_workspace_domain",
+    "create_workspace_app",
+    "update_workspace_app",
+    "create_workspace_endpoint",
+    "update_workspace_endpoint",
+  ],
+  // Minimal registry stub: the agent constructs one per instance and
+  // finalization drains it; these tests never start listeners.
+  CallbackListenerRegistry: class {
+    register() {}
+    get() {
+      return undefined;
+    }
+    remove() {}
+    async stopAll() {
+      return [];
+    }
+  },
+  PerCommandShell: class {},
+  PlaywrightMcpSession: class {},
+  resolveBrowserHeaderPolicy: () => ({ allowedHosts: [], headers: {} }),
+}));
+vi.mock("../../ai", () => ({
+  streamResponse: (opts: Record<string, unknown>) => {
+    streamResponseCalls.push(opts);
+    return { fullStream: (async function* () {})() };
+  },
+  normalizeStepUsage: (step: {
+    usage?: {
+      inputTokens?: number;
+      outputTokens?: number;
+      inputTokenDetails?: {
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+      };
+    };
+    providerMetadata?: {
+      anthropic?: {
+        cacheReadInputTokens?: number;
+        cacheCreationInputTokens?: number;
+      };
+    };
+  }) => {
+    const meta = step.providerMetadata?.anthropic;
+    const details = step.usage?.inputTokenDetails;
+    return {
+      inputTokens: step.usage?.inputTokens ?? 0,
+      outputTokens: step.usage?.outputTokens ?? 0,
+      cacheReadTokens:
+        meta?.cacheReadInputTokens ?? details?.cacheReadTokens ?? 0,
+      cacheWriteTokens:
+        meta?.cacheCreationInputTokens ?? details?.cacheWriteTokens ?? 0,
+    };
+  },
+}));
+vi.mock("../../session", () => ({ create: () => {} }));
+vi.mock("../specialized/utils", () => ({
+  detectOSAndEnhancePrompt: (p: string) => p,
+}));
+vi.mock("./prompt", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./prompt")>()),
+  buildBaseSystemPrompt: () => "system",
+}));
+vi.mock("./trace", () => ({
+  StepTraceWriter: class {
+    writeInit() {}
+    recordStep(...args: unknown[]) {
+      traceRecordStepCalls.push(args);
+    }
+    markSummarized() {}
+  },
+}));
+vi.mock("../../operator", () => ({
+  ApprovalDeniedError: class extends Error {},
+}));
+vi.mock("ai", () => ({ hasToolCall: () => () => false }));
+
+import type { InferenceRecorder } from "../../ai";
+import { AgentEventBus } from "../../eventBus";
+import type { RunContextRecorder } from "../../runtime/runContext";
+import { createInterruptedStepFinalizer } from "./interruptedStepFinalization";
+import { AgentMessageWriter } from "./messagePersistence";
+import {
+  filterWorkspaceToolsForRun,
+  OffensiveSecurityAgent,
+} from "./offensiveSecurityAgent";
+
+describe("assembled file-workspace instructions", () => {
+  it("does not treat Fast Strike helper tools as permission to edit target source", () => {
+    const rootPath = mkdtempSync(join(tmpdir(), "apex-fast-strike-scope-"));
+    const helperRoot = join(rootPath, "subagents", "worker", "helpers");
+    streamResponseCalls.length = 0;
+    try {
+      const agent = new OffensiveSecurityAgent({
+        prompt: "test",
+        system: "Worker instructions",
+        model: "test-model",
+        mode: "fast-strike",
+        session: {
+          id: "ses_fast_strike_scope",
+          rootPath,
+          scratchpadPath: join(rootPath, "scratchpad"),
+          config: { codebasePath: join(rootPath, "target-repo") },
+        },
+        fileWorkspaceRoot: helperRoot,
+        activeTools: [],
+        extraTools: { profile_codebase: {}, create_file: {} },
+        sandbox: {},
+      } as never);
+      void agent.streamResult;
+      const request = streamResponseCalls[0];
+      expect(request.activeTools).toContain("profile_codebase");
+      expect(request.activeTools).toContain("create_file");
+      const assessment = (request.system as string).split(
+        "# Source Code Assessment",
+      )[1];
+      expect(assessment).toBeDefined();
+      expect(assessment).toContain("Source access is read-only");
+      expect(assessment).toContain(helperRoot);
+      expect(assessment).toContain(
+        "Do not use shell commands to edit target source",
+      );
+      expect(assessment).not.toContain(
+        "Limit repo edits to the change you were dispatched to make",
+      );
+      expect(assessment).not.toContain(join(rootPath, "scratchpad"));
+    } finally {
+      rmSync(rootPath, { recursive: true, force: true });
+    }
+  });
+
+  it.each([
+    "spawned",
+    "root",
+    "custom-cwd",
+  ])("keeps %s worker file paths separate from shell and provided-file paths", (kind) => {
+    const rootPath = mkdtempSync(join(tmpdir(), "apex-workspace-prompt-"));
+    const scratchpadPath = join(rootPath, "scratchpad");
+    const fileWorkspaceRoot =
+      kind === "root"
+        ? scratchpadPath
+        : join(rootPath, "subagents", "worker", "helpers");
+    const agentCwd =
+      kind === "custom-cwd" ? join(rootPath, "commands") : rootPath;
+    const providedPath = join(rootPath, "provided_files");
+    mkdirSync(providedPath);
+    writeFileSync(join(providedPath, "sample.txt"), "user-supplied input");
+    streamResponseCalls.length = 0;
+    try {
+      const agent = new OffensiveSecurityAgent({
+        prompt: "test",
+        system: "Worker instructions",
+        model: "test-model",
+        session: { id: "ses_workspace", rootPath, scratchpadPath },
+        agentCwd,
+        fileWorkspaceRoot,
+        activeTools: [
+          "read_file",
+          "list_files",
+          "create_file",
+          "execute_command",
+        ],
+        sandbox: {},
+      } as never);
+      void agent.streamResult;
+      const system = streamResponseCalls[0].system as string;
+      expect(system).toContain(`Your shell starts in ${agentCwd}`);
+      expect(system).toContain(
+        `Native file tools are confined to ${fileWorkspaceRoot}`,
+      );
+      expect(system).toContain(
+        "Use absolute helper paths with `execute_command`",
+      );
+      expect(system).toContain(providedPath);
+      expect(system).toContain("sample.txt");
+      expect(system).toContain("copy inputs into the file workspace");
+      expect(system).not.toContain("Use relative paths for everything");
+      expect(system).not.toContain("temporary scripts");
+      expect(system).not.toContain("`list_files provided_files/`");
+    } finally {
+      rmSync(rootPath, { recursive: true, force: true });
+    }
+  });
+
+  it("falls back to the session's remote file workspace for the real tool context and prompt", () => {
+    const rootPath = mkdtempSync(join(tmpdir(), "apex-remote-ws-"));
+    const agentCwd = join(rootPath, "agent-cwd");
+    const remoteRoot = join(rootPath, "remote-workspace");
+    toolContexts.length = 0;
+    streamResponseCalls.length = 0;
+    try {
+      const agent = new OffensiveSecurityAgent({
+        prompt: "test",
+        system: "Worker instructions",
+        model: "test-model",
+        session: {
+          id: "ses_remote_ws",
+          rootPath,
+          scratchpadPath: join(rootPath, "scratchpad"),
+          config: { agentCwd, remoteFileWorkspaceRoot: remoteRoot },
+        },
+        activeTools: ["create_file", "read_file"],
+        sandbox: {},
+      } as never);
+      void agent.streamResult;
+      expect(toolContexts[0].fileWorkspaceRoot).toBe(remoteRoot);
+      const system = streamResponseCalls[0].system as string;
+      expect(system).toContain(
+        `Native file tools are confined to ${remoteRoot}`,
+      );
+      expect(system).not.toContain(join(rootPath, "scratchpad"));
+    } finally {
+      rmSync(rootPath, { recursive: true, force: true });
+    }
+  });
+
+  it("lets an explicit child helper root win over the session's remote workspace", () => {
+    const rootPath = mkdtempSync(join(tmpdir(), "apex-remote-ws-explicit-"));
+    const remoteRoot = join(rootPath, "remote-workspace");
+    const childRoot = join(remoteRoot, "subagents", "sub_1", "helpers");
+    toolContexts.length = 0;
+    streamResponseCalls.length = 0;
+    try {
+      const agent = new OffensiveSecurityAgent({
+        prompt: "test",
+        system: "Worker instructions",
+        model: "test-model",
+        session: {
+          id: "ses_remote_ws_explicit",
+          rootPath,
+          scratchpadPath: join(rootPath, "scratchpad"),
+          config: { remoteFileWorkspaceRoot: remoteRoot },
+        },
+        fileWorkspaceRoot: childRoot,
+        activeTools: ["create_file"],
+        sandbox: {},
+      } as never);
+      void agent.streamResult;
+      expect(toolContexts[0].fileWorkspaceRoot).toBe(childRoot);
+      const system = streamResponseCalls[0].system as string;
+      expect(system).toContain(
+        `Native file tools are confined to ${childRoot}`,
+      );
+    } finally {
+      rmSync(rootPath, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("spawned-agent usage callbacks", () => {
+  it("requires explicit forwarding when trace events own subagent accounting", () => {
+    toolContexts.length = 0;
+    const onStepFinish = vi.fn();
+    const onCacheMetrics = vi.fn();
+    const input = {
+      prompt: "test",
+      model: "test-model",
+      session: { id: "ses_test", rootPath: "/tmp/apex-usage-test" },
+      activeTools: [],
+      sandbox: {},
+      onStepFinish,
+      onCacheMetrics,
+    };
+
+    new OffensiveSecurityAgent(input as never);
+    new OffensiveSecurityAgent({
+      ...input,
+      forwardUsageCallbacksToSpawnedAgents: true,
+    } as never);
+
+    expect(toolContexts[0]?.onStepFinish).toBeUndefined();
+    expect(toolContexts[0]?.onCacheMetrics).toBeUndefined();
+    expect(toolContexts[1]?.onStepFinish).toBe(onStepFinish);
+    expect(toolContexts[1]?.onCacheMetrics).toBe(onCacheMetrics);
+  });
+});
+
+describe("auxiliary model events", () => {
+  it("keeps the last complete message snapshot while forwarding usage", async () => {
+    streamResponseCalls.length = 0;
+    traceRecordStepCalls.length = 0;
+    const rootPath = join(
+      "/tmp",
+      `apex-auxiliary-model-event-${Date.now()}-${Math.random()}`,
+    );
+    const initialMessages = [
+      { role: "user" as const, content: "original request" },
+    ];
+    const completedMessages = [
+      { role: "assistant" as const, content: "completed step" },
+    ];
+    const onStepFinish = vi.fn();
+
+    try {
+      const agent = new OffensiveSecurityAgent({
+        prompt: "test",
+        model: "test-model",
+        messages: initialMessages,
+        session: { id: "ses_auxiliary", rootPath },
+        activeTools: [],
+        sandbox: {},
+        onStepFinish,
+      } as never);
+
+      void agent.streamResult;
+      const call = streamResponseCalls[0] as {
+        onStepFinish: (event: unknown) => Promise<void>;
+      };
+      await call.onStepFinish({
+        response: { id: "step-1", messages: completedMessages },
+        usage: { inputTokens: 10, outputTokens: 2 },
+      });
+
+      const writer = (agent as unknown as { writer: AgentMessageWriter })
+        .writer;
+      expect(writer.latest).toEqual([...initialMessages, ...completedMessages]);
+
+      await call.onStepFinish({
+        response: { id: "summarization", messages: [] },
+        usage: {
+          inputTokens: 5,
+          outputTokens: 1,
+          inputTokenDetails: { cacheReadTokens: 4, cacheWriteTokens: 1 },
+        },
+      });
+
+      expect(writer.latest).toEqual([...initialMessages, ...completedMessages]);
+      expect(onStepFinish).toHaveBeenCalledTimes(2);
+      expect(traceRecordStepCalls.at(-1)?.[1]).toEqual({
+        inputTokens: 5,
+        outputTokens: 1,
+        cacheReadTokens: 4,
+        cacheWriteTokens: 1,
+      });
+      expect(traceRecordStepCalls.at(-1)?.[2]).toEqual({ usageOnly: true });
+      writer.cancelTimer();
+    } finally {
+      rmSync(rootPath, { recursive: true, force: true });
+    }
+  });
+
+  it("records cache from the step event without onCacheMetrics", async () => {
+    streamResponseCalls.length = 0;
+    traceRecordStepCalls.length = 0;
+    const rootPath = join(
+      "/tmp",
+      `apex-step-cache-${Date.now()}-${Math.random()}`,
+    );
+
+    try {
+      const agent = new OffensiveSecurityAgent({
+        prompt: "test",
+        model: "test-model",
+        session: { id: "ses_step_cache", rootPath },
+        activeTools: [],
+        sandbox: {},
+      } as never);
+
+      void agent.streamResult;
+      const call = streamResponseCalls[0] as {
+        onStepFinish: (event: unknown) => Promise<void>;
+        onCacheMetrics?: unknown;
+      };
+      expect(call.onCacheMetrics).toBeUndefined();
+
+      await call.onStepFinish({
+        response: {
+          id: "step-1",
+          messages: [{ role: "assistant", content: "ok" }],
+        },
+        usage: {
+          inputTokens: 40,
+          outputTokens: 6,
+          inputTokenDetails: { cacheReadTokens: 30, cacheWriteTokens: 2 },
+        },
+      });
+
+      expect(traceRecordStepCalls.at(-1)?.[1]).toEqual({
+        inputTokens: 40,
+        outputTokens: 6,
+        cacheReadTokens: 30,
+        cacheWriteTokens: 2,
+      });
+      const writer = (agent as unknown as { writer: AgentMessageWriter })
+        .writer;
+      writer.cancelTimer();
+    } finally {
+      rmSync(rootPath, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("tool context forwarding", () => {
+  it("forwards structured System scope to spawning tools", () => {
+    toolContexts.length = 0;
+    const systemScope = {
+      systemId: "sys_test",
+      memberHosts: ["https://app.example.com", "https://api.partner.test"],
+    };
+
+    new OffensiveSecurityAgent({
+      prompt: "test",
+      model: "test-model",
+      session: { id: "ses_test", rootPath: "/tmp/apex-scope-test" },
+      activeTools: [],
+      sandbox: {},
+      systemScope,
+    } as never);
+
+    expect(toolContexts[0]?.systemScope).toBe(systemScope);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds a minimal OffensiveSecurityAgent with mocked internals.
+ *
+ * Bypasses the constructor (which needs a real session, model, tools, etc.)
+ * via Object.create so we can unit-test consume() in isolation.
+ */
+function buildStubAgent(overrides: {
+  fullStream: AsyncIterable<unknown>;
+  commandShell?: { dispose: () => Promise<void> };
+  abortSignal?: AbortSignal;
+  resolveResult?: (sr: unknown) => unknown;
+  browserSession?: { disconnect: () => Promise<void> };
+  ownsBrowserSession?: boolean;
+  /** Overrides the default listener-registry stub (real registry in the finalization test). */
+  callbackListeners?: unknown;
+  messagesPath?: string | null;
+  latestMessages?: unknown[] | null;
+  writeImpl?: (messagesPath: string, contents: string) => Promise<void>;
+  responseCaptured?: Promise<unknown>;
+  responseToolResult?: unknown;
+  subagentId?: string;
+  subagentName?: string;
+  agentMode?: "default" | "plan" | "fast-strike";
+  streamIdFactory?: (context: unknown) => string;
+  contextRecorder?: RunContextRecorder;
+}): OffensiveSecurityAgent<unknown> {
+  const agent = Object.create(
+    OffensiveSecurityAgent.prototype,
+  ) as OffensiveSecurityAgent<unknown>;
+
+  const bus = new AgentEventBus();
+  vi.spyOn(bus, "emitStreamPart").mockImplementation(() => {});
+
+  Object.defineProperty(agent, "eventBus", { value: bus });
+  Object.defineProperty(agent, "streamResult", {
+    value: { fullStream: overrides.fullStream },
+  });
+  // Stub bypasses the constructor, so pre-settle the initialization seam —
+  // consume() awaits streamReady before touching the (stubbed) streamResult.
+  Object.defineProperty(agent, "streamInit", {
+    value: Promise.resolve(),
+  });
+  Object.defineProperty(agent, "subagentId", {
+    value: overrides.subagentId,
+  });
+  Object.defineProperty(agent, "subagentName", {
+    value: overrides.subagentName,
+  });
+  Object.defineProperty(agent, "agentMode", {
+    value: overrides.agentMode ?? "default",
+  });
+  // Never resolves by default, so consume() settles via the drain path.
+  Object.defineProperty(agent, "responseCaptured", {
+    value: overrides.responseCaptured ?? new Promise(() => {}),
+  });
+  Object.defineProperty(agent, "_responseToolResult", {
+    value: overrides.responseToolResult,
+  });
+  // Stub bypasses the constructor, so provide a minimal session for busSessionId.
+  Object.defineProperty(agent, "_session", {
+    value: { id: "ses_stub" },
+  });
+  Object.defineProperty(agent, "currentMessageId", {
+    value: null,
+    writable: true,
+  });
+  Object.defineProperty(agent, "commandShell", {
+    value: overrides.commandShell,
+  });
+  Object.defineProperty(agent, "abortSignal", {
+    value: overrides.abortSignal,
+  });
+  Object.defineProperty(agent, "resolveResult", {
+    value: overrides.resolveResult,
+  });
+  Object.defineProperty(agent, "browserSession", {
+    value: overrides.browserSession,
+  });
+  Object.defineProperty(agent, "ownsBrowserSession", {
+    value: overrides.ownsBrowserSession ?? false,
+  });
+  // The constructor is bypassed, so provide the listener registry that
+  // finalizeRun drains; these tests never start listeners.
+  Object.defineProperty(agent, "callbackListeners", {
+    value:
+      overrides.callbackListeners ??
+      ({
+        register() {},
+        get() {
+          return undefined;
+        },
+        remove() {},
+        async stopAll() {
+          return [];
+        },
+      } as object),
+  });
+  Object.defineProperty(agent, "messagesPath", {
+    value: overrides.messagesPath ?? null,
+  });
+  const writer = new AgentMessageWriter({
+    messagesPath: overrides.messagesPath ?? null,
+    ...(overrides.writeImpl ? { writeImpl: overrides.writeImpl } : {}),
+  });
+  if (overrides.latestMessages) {
+    writer.setLatest(overrides.latestMessages as never[]);
+  }
+  Object.defineProperty(agent, "writer", { value: writer });
+  Object.defineProperty(agent, "finalizeInterruptedStep", {
+    value: createInterruptedStepFinalizer({
+      eventBus: bus,
+      sessionId: "ses_stub",
+      writer,
+      responseToolName: "response",
+      responseToolFired: () => false,
+    }),
+  });
+  Object.defineProperty(agent, "streamIdFactory", {
+    value: overrides.streamIdFactory,
+  });
+  Object.defineProperty(agent, "contextRecorder", {
+    value: overrides.contextRecorder,
+  });
+
+  return agent;
+}
+
+async function* yieldChunks(
+  chunks: unknown[],
+): AsyncGenerator<unknown, void, undefined> {
+  for (const c of chunks) yield c;
+}
+
+async function* yieldThenThrow(
+  chunks: unknown[],
+  error: Error,
+): AsyncGenerator<unknown, void, undefined> {
+  for (const c of chunks) yield c;
+  throw error;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("workspace tool access", () => {
+  it("requires both an interactive operator and an explicit current request", () => {
+    const tools = [
+      "execute_command",
+      "list_workspace_domains",
+      "create_workspace_domain",
+      "list_workspace_apps",
+      "create_workspace_app",
+      "update_workspace_app",
+      "list_workspace_endpoints",
+      "create_workspace_endpoint",
+      "update_workspace_endpoint",
+    ];
+    const request =
+      "Can you add a new app called Test App with the endpoint health to console pls";
+
+    expect(filterWorkspaceToolsForRun(tools, request, true)).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Use create_workspace_app for this record",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(filterWorkspaceToolsForRun(tools, request, false)).toEqual([
+      "execute_command",
+    ]);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Pentest the console app and enumerate its endpoints",
+        true,
+      ),
+    ).toEqual(["execute_command"]);
+    for (const request of [
+      "Set up a pentest against the endpoints in the console workspace",
+      "Move on to the console app's admin endpoints",
+      "Change your approach and fuzz the console app endpoints",
+      "Set the scope to the console application and its endpoints",
+      "Update me on progress against the workspace endpoints",
+      "Correct me if I'm wrong but the console app has 3 endpoints",
+      "Change the workspace app testing strategy and continue",
+      "Set the workspace endpoint scan scope to /api",
+      "Move the console endpoint fuzzing to a new phase",
+      "Update the workspace application pentest plan",
+      "Correct the console endpoint test assumptions",
+      "Repair the workspace app vulnerability",
+      "Test whether the workspace app can link to an external domain",
+      "Check whether the workspace domain can link to the app during the test",
+      "Can I link this workspace domain to the Payments app?",
+      "Is it possible to link this workspace domain to the Payments app?",
+      "Tell me whether I should link this workspace domain to the Payments app",
+      "Please don't link the workspace app to its domain",
+      "Please do not create a workspace domain",
+      "Never create a workspace app without asking first",
+      "Can I create a workspace app for Billing?",
+      "How do I update the workspace endpoint transport to grpc?",
+      "Can I link example.com to my workspace?",
+      "How can I link this workspace domain to the Payments app?",
+      "How would we update the workspace application description?",
+      "Get started on the console workspace endpoints",
+      "What if we move on to the workspace apps next?",
+      // A coordinated write verb after `and`/`but` must not escape the leading
+      // interrogative — the whole capability question stays read-only.
+      "How do I enumerate the workspace apps and link this workspace domain to the Payments application?",
+      "Is it possible to review the workspace apps but create a workspace domain?",
+    ]) {
+      expect(filterWorkspaceToolsForRun(tools, request, true)).toEqual([
+        "execute_command",
+      ]);
+    }
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        `<skill name="pentest">${request}</skill>`,
+        true,
+      ),
+    ).toEqual(["execute_command"]);
+  });
+
+  it("exposes read-only listing tools but never mutations for recon phrasing", () => {
+    const tools = [
+      "execute_command",
+      "list_workspace_domains",
+      "create_workspace_domain",
+      "list_workspace_apps",
+      "create_workspace_app",
+      "update_workspace_app",
+      "list_workspace_endpoints",
+      "create_workspace_endpoint",
+      "update_workspace_endpoint",
+    ];
+
+    // Recon verbs (find/search/show/list) targeting the console/workspace must
+    // only unlock the read-only `list_*` tools, never mutations.
+    for (const request of [
+      "Find all endpoints on the console workspace and pentest them",
+      "Search the console workspace for apps in scope",
+      "Show me the endpoints registered in the workspace",
+      "List the apps in my console workspace",
+      "Show the domains in my console workspace",
+      "What domains are in my workspace?",
+      "Get the workspace endpoints",
+      "Which of the workspace apps are registered?",
+      "Show me a list of all workspace endpoints",
+      "What are the domains in my workspace?",
+      "Which of our workspace apps are available?",
+      "Get a list of the workspace endpoints",
+      // A coordinated write verb ("create") after `and` must not escape the
+      // leading capability question: the read verb still exposes `list_*`, but
+      // the mutation tools stay gated.
+      "Can I list the workspace endpoints and create a workspace endpoint?",
+    ]) {
+      expect(filterWorkspaceToolsForRun(tools, request, true)).toEqual([
+        "execute_command",
+        "list_workspace_domains",
+        "list_workspace_apps",
+        "list_workspace_endpoints",
+      ]);
+    }
+  });
+
+  it("exposes mutation tools only for explicit write requests", () => {
+    const tools = [
+      "execute_command",
+      "list_workspace_domains",
+      "create_workspace_domain",
+      "list_workspace_apps",
+      "create_workspace_app",
+      "update_workspace_app",
+      "list_workspace_endpoints",
+      "create_workspace_endpoint",
+      "update_workspace_endpoint",
+    ];
+
+    // Write verbs and "break down <threat model>" imports open the mutation set.
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Register a new app called Billing in the console workspace",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Break down this threat model into apps and endpoints in the workspace",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Change the workspace endpoint transport to grpc",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Link the console application to this domain",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Unlink the workspace app from its domain",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Link this workspace domain to the Payments application",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Can you link this workspace domain to the Payments application?",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "How can you link this workspace domain to the Payments application?",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "How would you update the workspace application description to Primary API?",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Please unlink the workspace app from its domain",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "I need you to link this workspace domain to the Payments application",
+        true,
+      ),
+    ).toEqual(tools);
+    // "I'd like to …" / "I would like to …" without an explicit "you" must
+    // expose writes, matching the "I want to …" / "I need to …" branch.
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "I'd like to link this workspace domain to the Payments application",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "I would like to link this workspace domain to the Payments application",
+        true,
+      ),
+    ).toEqual(tools);
+    // A separate prohibition in another clause must not veto an explicit write.
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Please link this workspace domain to the Payments application, but do not create any new endpoints",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Link this workspace domain to the Payments application; do not create any endpoints",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Don't create any workspace endpoints, but link this workspace domain to the Payments application",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Don't create any workspace endpoints and link this workspace domain to the Payments application",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Link example.com to the Payments application in my workspace",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Unlink example.com from the Payments app in my workspace",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Update the workspace application description to Primary API",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Rename the console app to Payments",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Set the workspace endpoint parent application to app-2",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Add example.com to my console workspace",
+        true,
+      ),
+    ).toEqual(tools);
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Can you link example.com to my workspace?",
+        true,
+      ),
+    ).toEqual(tools);
+
+    // A direct mention of a read tool never unlocks the mutation tools.
+    expect(
+      filterWorkspaceToolsForRun(
+        tools,
+        "Use list_workspace_apps for this record",
+        true,
+      ),
+    ).toEqual([
+      "execute_command",
+      "list_workspace_domains",
+      "list_workspace_apps",
+      "list_workspace_endpoints",
+    ]);
+  });
+});
+
+describe("OffensiveSecurityAgent.consume()", () => {
+  const textDelta = { type: "text-delta", text: "hi" };
+
+  describe("command shell disposal on stream error (leak fix)", () => {
+    it("disposes shell after a successful stream", async () => {
+      const dispose = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        commandShell: { dispose },
+      });
+
+      await agent.consume();
+      expect(dispose).toHaveBeenCalledOnce();
+    });
+
+    it("disposes shell when the stream throws mid-iteration", async () => {
+      const dispose = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([textDelta], new Error("stream exploded")),
+        commandShell: { dispose },
+      });
+
+      await expect(agent.consume()).rejects.toThrow("stream exploded");
+      expect(dispose).toHaveBeenCalledOnce();
+    });
+
+    it("disposes shell when the stream throws immediately (no chunks)", async () => {
+      const dispose = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([], new Error("instant failure")),
+        commandShell: { dispose },
+      });
+
+      await expect(agent.consume()).rejects.toThrow("instant failure");
+      expect(dispose).toHaveBeenCalledOnce();
+    });
+
+    it("drain does not settle before the shell's kill barrier resolves", async () => {
+      // Stream error while a command is still active: dispose() returns a
+      // pending barrier (bounded in production by the runner's kill
+      // protocol). Hosts rely on drained before closeout, so consume() must
+      // not settle while that barrier is pending.
+      let releaseBarrier: (() => void) | undefined;
+      const barrier = new Promise<void>((res) => {
+        releaseBarrier = res;
+      });
+      const dispose = vi.fn(() => barrier);
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([textDelta], new Error("stream exploded")),
+        commandShell: { dispose },
+      });
+
+      let consumeSettled = false;
+      const consumeDone = agent.consume().then(
+        () => {
+          consumeSettled = true;
+        },
+        () => {
+          consumeSettled = true;
+        },
+      );
+
+      // finalizeRun has called dispose, but its barrier is pending — the
+      // drain must still be unsettled.
+      await vi.waitFor(() => expect(dispose).toHaveBeenCalledOnce());
+      await new Promise((r) => setTimeout(r, 50));
+      expect(consumeSettled).toBe(false);
+
+      releaseBarrier?.();
+      await consumeDone;
+      expect(consumeSettled).toBe(true);
+    });
+
+    it("disposes shell when emitStreamPart throws", async () => {
+      const dispose = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        commandShell: { dispose },
+      });
+
+      vi.spyOn(agent.eventBus, "emitStreamPart").mockImplementation(() => {
+        throw new Error("bus emit failed");
+      });
+
+      await expect(agent.consume()).rejects.toThrow("bus emit failed");
+      expect(dispose).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe("browser session teardown on completion (Chromium leak fix)", () => {
+    it("disconnects the owned browser session after a successful stream", async () => {
+      const disconnect = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        browserSession: { disconnect },
+        ownsBrowserSession: true,
+      });
+
+      await agent.consume();
+      expect(disconnect).toHaveBeenCalledOnce();
+    });
+
+    it("disconnects the owned browser session when the stream throws", async () => {
+      const disconnect = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([textDelta], new Error("stream exploded")),
+        browserSession: { disconnect },
+        ownsBrowserSession: true,
+      });
+
+      await expect(agent.consume()).rejects.toThrow("stream exploded");
+      expect(disconnect).toHaveBeenCalledOnce();
+    });
+
+    it("does NOT disconnect an inherited (not-owned) browser session", async () => {
+      const disconnect = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        browserSession: { disconnect },
+        ownsBrowserSession: false,
+      });
+
+      await agent.consume();
+      expect(disconnect).not.toHaveBeenCalled();
+    });
+
+    it("swallows a disconnect failure so it never masks the run result", async () => {
+      const disconnect = vi.fn().mockRejectedValue(new Error("kill failed"));
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        browserSession: { disconnect },
+        ownsBrowserSession: true,
+        resolveResult: () => "ok",
+      });
+
+      await expect(agent.consume()).resolves.toBe("ok");
+      expect(disconnect).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe("no-shell scenarios (sandbox mode)", () => {
+    it("succeeds without shell when stream completes normally", async () => {
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        commandShell: undefined,
+      });
+
+      await expect(agent.consume()).resolves.toBeUndefined();
+    });
+
+    it("propagates stream error without shell (no dispose to call)", async () => {
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([], new Error("sandbox boom")),
+        commandShell: undefined,
+      });
+
+      await expect(agent.consume()).rejects.toThrow("sandbox boom");
+    });
+  });
+
+  describe("disposal ordering", () => {
+    it("disposes shell before resolveResult runs", async () => {
+      const callOrder: string[] = [];
+
+      const dispose = vi.fn(() => {
+        callOrder.push("dispose");
+        return Promise.resolve();
+      });
+      const resolveResult = vi.fn(() => {
+        callOrder.push("resolveResult");
+        return "result";
+      });
+
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        commandShell: { dispose },
+        resolveResult,
+      });
+
+      const result = await agent.consume();
+      expect(result).toBe("result");
+      expect(dispose).toHaveBeenCalledOnce();
+      expect(resolveResult).toHaveBeenCalledOnce();
+      expect(callOrder).toEqual(["dispose", "resolveResult"]);
+    });
+  });
+
+  describe("abort signal", () => {
+    it.each([
+      new Error("Execution broker receipt unavailable"),
+      new DOMException("Recorded run deadline expired", "AbortError"),
+      new DOMException("Attempt deadline expired", "TimeoutError"),
+      Object.assign(
+        new Error("Aborted", { cause: new Error("Backend unavailable") }),
+        { name: "AbortError" },
+      ),
+      "host shutdown",
+      0,
+      null,
+    ])("preserves an explicit abort reason: %s", async (reason) => {
+      const controller = new AbortController();
+      controller.abort(reason);
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        abortSignal: controller.signal,
+      });
+      await expect(agent.consume()).rejects.toBe(reason);
+    });
+
+    it("uses the originating reason when the SDK echoes a generic abort", async () => {
+      const controller = new AbortController();
+      const cause = new Error("Execution outcome could not be confirmed");
+      controller.abort(cause);
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [],
+          new DOMException("Aborted", "AbortError"),
+        ),
+        abortSignal: controller.signal,
+      });
+      await expect(agent.consume()).rejects.toBe(cause);
+    });
+
+    it("preserves the runtime's AbortSignal.timeout reason", async () => {
+      const signal = AbortSignal.timeout(1);
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      expect(signal.aborted).toBe(true);
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([]),
+        abortSignal: signal,
+      });
+      await expect(agent.consume()).rejects.toBe(signal.reason);
+      expect(signal.reason.name).toBe("TimeoutError");
+    });
+
+    it("keeps a generic stream abort when the caller signal was not aborted", async () => {
+      const cause = new DOMException("Aborted", "AbortError");
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([], cause),
+        abortSignal: new AbortController().signal,
+      });
+      await expect(agent.consume()).rejects.toBe(cause);
+    });
+
+    it("preserves a stream abort carrying its own cause even after a user abort", async () => {
+      const cause = Object.assign(
+        new Error("Aborted", { cause: new Error("Backend unavailable") }),
+        { name: "AbortError" },
+      );
+      const controller = new AbortController();
+      controller.abort();
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([], cause),
+        abortSignal: controller.signal,
+      });
+      await expect(agent.consume()).rejects.toBe(cause);
+    });
+
+    it("keeps user-abort wording for a generic SDK echo", async () => {
+      const controller = new AbortController();
+      controller.abort();
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [],
+          new DOMException("Aborted", "AbortError"),
+        ),
+        abortSignal: controller.signal,
+      });
+      await expect(agent.consume()).rejects.toMatchObject({
+        name: "AbortError",
+        message: "Agent aborted by user",
+      });
+    });
+
+    it("keeps a prior abort cause when later cleanup fails", async () => {
+      const controller = new AbortController();
+      const cause = new Error("Target session disconnected");
+      controller.abort(cause);
+      const dispose = vi.fn().mockRejectedValue(new Error("Cleanup failed"));
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        abortSignal: controller.signal,
+        commandShell: { dispose },
+      });
+      await expect(agent.consume()).rejects.toBe(cause);
+      expect(dispose).toHaveBeenCalledOnce();
+    });
+
+    it("waits for owned cleanup before rejecting with the abort cause", async () => {
+      const controller = new AbortController();
+      const cause = new Error("Execution infrastructure failed");
+      controller.abort(cause);
+      let release!: () => void;
+      const disposal = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      const dispose = vi.fn(() => disposal);
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        abortSignal: controller.signal,
+        commandShell: { dispose },
+      });
+      let settled = false;
+      const result = agent.consume().catch((error) => {
+        settled = true;
+        return error;
+      });
+      try {
+        await vi.waitFor(() => expect(dispose).toHaveBeenCalledOnce());
+        expect(settled).toBe(false);
+      } finally {
+        release();
+      }
+      expect(await result).toBe(cause);
+    });
+
+    it.each([
+      "abort",
+      "provider",
+      "cleanup",
+    ])("saves the primary cause in interrupted tool evidence (%s)", async (source) => {
+      const directory = mkdtempSync(join(tmpdir(), "apex-abort-cause-"));
+      const controller = new AbortController();
+      const infrastructure = new Error("Execution infrastructure failed");
+      const provider = new Error("Provider stream failed first");
+      const cause = source === "provider" ? provider : infrastructure;
+      async function* stream() {
+        yield {
+          type: "tool-call",
+          toolCallId: "pending",
+          toolName: "run_command",
+          input: { command: "fixture" },
+        };
+        if (source === "provider") throw provider;
+        if (source === "abort") controller.abort(infrastructure);
+      }
+      const agent = buildStubAgent({
+        fullStream: stream(),
+        abortSignal: controller.signal,
+        commandShell: {
+          dispose: async () => {
+            controller.abort(infrastructure);
+          },
+        },
+        messagesPath: join(directory, "messages.json"),
+        latestMessages: [{ role: "user", content: "fixture" }],
+      });
+      const results: unknown[] = [];
+      agent.eventBus.on("tool-result", (event) => results.push(event.result));
+      try {
+        await expect(agent.consume()).rejects.toBe(cause);
+        expect(results).toContainEqual({
+          type: "error-text",
+          value: expect.stringContaining(cause.message),
+        });
+        const saved = readFileSync(join(directory, "messages.json"), "utf8");
+        expect(saved).toContain(cause.message);
+        expect(saved).not.toContain("Agent aborted by user");
+        if (source === "provider")
+          expect(saved).not.toContain(infrastructure.message);
+      } finally {
+        rmSync(directory, { recursive: true, force: true });
+      }
+    });
+
+    it("disposes shell even when abort signal causes throw", async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const dispose = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        commandShell: { dispose },
+        abortSignal: controller.signal,
+      });
+
+      await expect(agent.consume()).rejects.toThrow("Agent aborted by user");
+      expect(dispose).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe("synthetic tool-result on stream abort/error", () => {
+    const toolCallChunk = {
+      type: "tool-call",
+      toolCallId: "tc1",
+      toolName: "execute_command",
+    };
+    const otherToolCallChunk = {
+      type: "tool-call",
+      toolCallId: "tc2",
+      toolName: "read_file",
+    };
+    const toolResultChunk = {
+      type: "tool-result",
+      toolCallId: "tc1",
+      result: { type: "text", value: "done" },
+    };
+
+    it("emits synthetic tool-result for an in-flight tool when stream throws", async () => {
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [toolCallChunk],
+          new Error("connection reset"),
+        ),
+      });
+
+      const emittedResults: Array<{
+        toolCallId: string;
+        result: unknown;
+      }> = [];
+      agent.eventBus.on("tool-result", (e) => {
+        emittedResults.push({ toolCallId: e.toolCallId, result: e.result });
+      });
+
+      await expect(agent.consume()).rejects.toThrow("connection reset");
+
+      expect(emittedResults).toHaveLength(1);
+      expect(emittedResults[0].toolCallId).toBe("tc1");
+      expect(emittedResults[0].result).toMatchObject({
+        type: "error-text",
+        value: expect.stringContaining("connection reset"),
+      });
+    });
+
+    it("does not emit a synthetic result when the matching tool-result already streamed", async () => {
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([toolCallChunk, toolResultChunk]),
+      });
+
+      const emittedResults: unknown[] = [];
+      agent.eventBus.on("tool-result", (e) => emittedResults.push(e));
+
+      await agent.consume();
+
+      expect(emittedResults).toHaveLength(0);
+    });
+
+    it("closes a truncated tool-call (started, args never completed) at finish-step", async () => {
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([
+          { type: "tool-input-start", id: "tc1", toolName: "response" },
+          { type: "finish-step" },
+        ]),
+      });
+
+      const emittedResults: Array<{ toolCallId: string; result: unknown }> = [];
+      agent.eventBus.on("tool-result", (e) => {
+        emittedResults.push({ toolCallId: e.toolCallId, result: e.result });
+      });
+
+      await agent.consume();
+
+      expect(emittedResults).toHaveLength(1);
+      expect(emittedResults[0].toolCallId).toBe("tc1");
+      expect(emittedResults[0].result).toMatchObject({ type: "error-text" });
+    });
+
+    it("emits one synthetic per in-flight tool when multiple are open at abort", async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [toolCallChunk, otherToolCallChunk],
+          new DOMException("Aborted", "AbortError"),
+        ),
+        abortSignal: controller.signal,
+      });
+
+      const emittedResults: Array<{ toolCallId: string; result: unknown }> = [];
+      agent.eventBus.on("tool-result", (e) => {
+        emittedResults.push({ toolCallId: e.toolCallId, result: e.result });
+      });
+
+      await expect(agent.consume()).rejects.toBeInstanceOf(DOMException);
+
+      expect(emittedResults).toHaveLength(2);
+      const ids = emittedResults.map((r) => r.toolCallId).sort();
+      expect(ids).toEqual(["tc1", "tc2"]);
+      for (const r of emittedResults) {
+        expect(r.result).toMatchObject({
+          type: "error-text",
+          value: expect.stringContaining("aborted"),
+        });
+      }
+    });
+
+    it("uses 'Agent aborted by user' as reason when abortSignal is set", async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [toolCallChunk],
+          new DOMException("Aborted", "AbortError"),
+        ),
+        abortSignal: controller.signal,
+      });
+
+      const emittedResults: Array<{ result: unknown }> = [];
+      agent.eventBus.on("tool-result", (e) =>
+        emittedResults.push({ result: e.result }),
+      );
+
+      await expect(agent.consume()).rejects.toBeInstanceOf(DOMException);
+
+      expect(emittedResults[0].result).toMatchObject({
+        type: "error-text",
+        value: expect.stringContaining("aborted by user"),
+      });
+    });
+
+    it("flushes a tool-error into the snapshot when the stream aborts before finish-step", async () => {
+      // finally must flush deferred toolErrors even if the stream throws first.
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [
+            toolCallChunk,
+            {
+              type: "tool-error",
+              toolCallId: "tc1",
+              toolName: "execute_command",
+              error: new Error("Zod: expected string"),
+            },
+          ],
+          new Error("connection reset"),
+        ),
+      });
+
+      const emittedResults: Array<{ toolCallId: string; result: unknown }> = [];
+      agent.eventBus.on("tool-result", (e) => {
+        emittedResults.push({ toolCallId: e.toolCallId, result: e.result });
+      });
+
+      await expect(agent.consume()).rejects.toThrow("connection reset");
+
+      expect(emittedResults).toHaveLength(1);
+      expect(emittedResults[0].toolCallId).toBe("tc1");
+      expect(emittedResults[0].result).toMatchObject({
+        type: "error-text",
+        value: expect.stringContaining("Zod: expected string"),
+      });
+    });
+  });
+
+  describe("resolveResult", () => {
+    it("returns resolved value when resolveResult is provided", async () => {
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+        resolveResult: () => 42,
+      });
+
+      const result = await agent.consume();
+      expect(result).toBe(42);
+    });
+
+    it("returns undefined when resolveResult is absent", async () => {
+      const agent = buildStubAgent({
+        fullStream: yieldChunks([textDelta]),
+      });
+
+      const result = await agent.consume();
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("result/drain decoupling", () => {
+    it("returns the captured result without waiting for the stream to drain", async () => {
+      // Wedged stream: consume() must settle from responseCaptured, not the drain.
+      const neverDrains = (async function* () {
+        await new Promise(() => {});
+      })();
+      const agent = buildStubAgent({
+        fullStream: neverDrains,
+        responseCaptured: Promise.resolve("captured"),
+        resolveResult: () => "from-drain",
+      });
+
+      await expect(agent.consume()).resolves.toBe("captured");
+    });
+  });
+
+  describe("callback listener finalization (owned-resource drain)", () => {
+    it("consume() drains listeners; one failed stop never blocks another, and abortAndDrain retries", async () => {
+      const registry = new CallbackListenerRegistry();
+      const stopped: string[] = [];
+      registry.register({
+        jobId: "wjob_77777_fail01",
+        nonce: "a".repeat(32),
+        scriptPath: "/a.cjs",
+        bindAddress: "0.0.0.0",
+        port: 1,
+        selfTestConfirmed: false,
+        stop: async () => {
+          throw new Error("stop a failed");
+        },
+      });
+      registry.register({
+        jobId: "wjob_77777_pass01",
+        nonce: "b".repeat(32),
+        scriptPath: "/b.cjs",
+        bindAddress: "0.0.0.0",
+        port: 2,
+        selfTestConfirmed: false,
+        stop: async () => {
+          stopped.push("b");
+          return undefined;
+        },
+      });
+
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([], new Error("stream boom")),
+        messagesPath: null,
+        callbackListeners: registry,
+      });
+
+      // The stream error stays primary; listener cleanup still ran.
+      await expect(agent.consume()).rejects.toThrow("stream boom");
+      expect(stopped).toEqual(["b"]);
+      expect(registry.get("wjob_77777_fail01")).toBeDefined();
+      expect(registry.get("wjob_77777_pass01")).toBeUndefined();
+
+      // Host teardown path: best-effort retry, never throws, keeps the
+      // failed owner registered for a later cleanup path.
+      await expect(agent.abortAndDrain()).resolves.toBeUndefined();
+      expect(stopped).toEqual(["b"]);
+      expect(registry.get("wjob_77777_fail01")).toBeDefined();
+    });
+  });
+
+  describe("synthetic tool-result: persist timer fallback (bugbot fix)", () => {
+    const toolCallChunk = {
+      type: "tool-call",
+      toolCallId: "tc1",
+      toolName: "execute_command",
+    };
+
+    it("reads persisted messages from disk when latestMessages is null", async () => {
+      const tmpDir = join("/tmp", `pensar-test-${Date.now()}-fallback`);
+      mkdirSync(tmpDir, { recursive: true });
+      const messagesPath = join(tmpDir, "messages.json");
+
+      const existingMessages = [
+        { role: "user", content: [{ type: "text", text: "run nmap" }] },
+        { role: "assistant", content: [{ type: "text", text: "Running..." }] },
+      ];
+      writeFileSync(messagesPath, JSON.stringify(existingMessages));
+
+      // latestMessages is null — simulates persist timer having flushed
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([toolCallChunk], new Error("timeout")),
+        messagesPath,
+        latestMessages: null,
+      });
+
+      try {
+        await agent.consume();
+      } catch {}
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      const written = JSON.parse(readFileSync(messagesPath, "utf-8"));
+      // original 2 + assistant (tool-call) + tool (synthetic result)
+      expect(written).toHaveLength(4);
+      expect(written[0].role).toBe("user");
+      expect(written[1].role).toBe("assistant");
+      expect(written[2].role).toBe("assistant");
+      expect(written[2].content[0].type).toBe("tool-call");
+      expect(written[2].content[0].toolCallId).toBe("tc1");
+      expect(written[3].role).toBe("tool");
+      expect(written[3].content[0].toolCallId).toBe("tc1");
+      expect(written[3].content[0].output.type).toBe("error-text");
+
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it("does not lose history when persist timer nulled latestMessages", async () => {
+      const tmpDir = join("/tmp", `pensar-test-${Date.now()}-noloss`);
+      mkdirSync(tmpDir, { recursive: true });
+      const messagesPath = join(tmpDir, "messages.json");
+
+      const existingMessages = [
+        { role: "user", content: [{ type: "text", text: "scan target" }] },
+      ];
+      writeFileSync(messagesPath, JSON.stringify(existingMessages));
+
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([toolCallChunk], new Error("network")),
+        messagesPath,
+        latestMessages: null,
+      });
+
+      try {
+        await agent.consume();
+      } catch {}
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      const written = JSON.parse(readFileSync(messagesPath, "utf-8"));
+      // Must NOT be just [{ role: "tool" ... }] — must include original messages
+      expect(written.length).toBeGreaterThan(1);
+      expect(written[0].role).toBe("user");
+
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it("waits for an in-flight persist before writing the abort snapshot", async () => {
+      const tmpDir = join("/tmp", `pensar-test-${Date.now()}-persist-race`);
+      mkdirSync(tmpDir, { recursive: true });
+      const messagesPath = join(tmpDir, "messages.json");
+
+      const staleMessages = [
+        { role: "user", content: [{ type: "text", text: "scan target" }] },
+      ];
+      const persistedMessages = [
+        ...staleMessages,
+        {
+          role: "assistant",
+          content: [{ type: "text", text: "Starting scan" }],
+        },
+      ];
+      writeFileSync(messagesPath, JSON.stringify(staleMessages));
+
+      // Gate the writer's write sink so an in-flight persist can be held
+      // while the stream throws and the abort snapshot waits its turn.
+      let releasePersist!: () => void;
+      const gate = new Promise<void>((resolve) => {
+        releasePersist = resolve;
+      });
+      const writeImpl = async (path: string, contents: string) => {
+        await gate;
+        writeFileSync(path, contents);
+      };
+
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([toolCallChunk], new Error("timeout")),
+        messagesPath,
+        latestMessages: null,
+        writeImpl,
+      });
+
+      // Start the in-flight persist against the gated sink.
+      const writer = (agent as unknown as { writer: AgentMessageWriter })
+        .writer;
+      const inFlight = writer
+        .enqueueWrite(persistedMessages as never[])
+        .catch(() => {});
+
+      const consume = agent.consume().catch(() => {});
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      // The gated persist is still in flight — the abort snapshot must be
+      // queued behind it, not interleaved.
+      releasePersist();
+      await inFlight;
+      await consume;
+
+      const written = JSON.parse(readFileSync(messagesPath, "utf-8"));
+      expect(written.slice(0, persistedMessages.length)).toEqual(
+        persistedMessages,
+      );
+      expect(written.at(-2)).toMatchObject({
+        role: "assistant",
+        content: [{ type: "tool-call", toolCallId: "tc1" }],
+      });
+      expect(written.at(-1)).toMatchObject({
+        role: "tool",
+        content: [{ type: "tool-result", toolCallId: "tc1" }],
+      });
+
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it("does not add assistant tool-call msg when base already contains them", async () => {
+      const tmpDir = join("/tmp", `pensar-test-${Date.now()}-nodup`);
+      mkdirSync(tmpDir, { recursive: true });
+      const messagesPath = join(tmpDir, "messages.json");
+
+      // Simulate onStepFinish having already persisted the assistant tool-call
+      const existingMessages = [
+        { role: "user", content: [{ type: "text", text: "scan" }] },
+        {
+          role: "assistant",
+          content: [
+            {
+              type: "tool-call",
+              toolCallId: "tc1",
+              toolName: "execute_command",
+              input: {},
+            },
+          ],
+        },
+      ];
+      writeFileSync(messagesPath, JSON.stringify(existingMessages));
+
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([toolCallChunk], new Error("abort")),
+        messagesPath,
+        latestMessages: null,
+      });
+
+      try {
+        await agent.consume();
+      } catch {}
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      const written = JSON.parse(readFileSync(messagesPath, "utf-8"));
+      // Should NOT duplicate the assistant message — just user + assistant + tool
+      expect(written).toHaveLength(3);
+      expect(written[0].role).toBe("user");
+      expect(written[1].role).toBe("assistant");
+      expect(written[2].role).toBe("tool");
+      expect(written[2].content[0].output.type).toBe("error-text");
+
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+  });
+
+  describe("parallel tool abort persists completed tools (bugbot fix)", () => {
+    it("includes completed tool results alongside synthetics on abort", async () => {
+      const tmpDir = join("/tmp", `pensar-test-${Date.now()}-parallel`);
+      mkdirSync(tmpDir, { recursive: true });
+      const messagesPath = join(tmpDir, "messages.json");
+
+      const existingMessages = [
+        { role: "user", content: [{ type: "text", text: "scan" }] },
+      ];
+      writeFileSync(messagesPath, JSON.stringify(existingMessages));
+
+      // Two tools called; tool A completes, tool B is still in-flight on abort.
+      const toolCallA = {
+        type: "tool-call",
+        toolCallId: "tcA",
+        toolName: "read_file",
+      };
+      const toolCallB = {
+        type: "tool-call",
+        toolCallId: "tcB",
+        toolName: "execute_command",
+      };
+      const toolResultA = {
+        type: "tool-result",
+        toolCallId: "tcA",
+        toolName: "read_file",
+        result: { type: "text", value: "file contents" },
+      };
+
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [toolCallA, toolCallB, toolResultA],
+          new Error("connection lost"),
+        ),
+        messagesPath,
+        latestMessages: null,
+      });
+
+      try {
+        await agent.consume();
+      } catch {}
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      const written = JSON.parse(readFileSync(messagesPath, "utf-8"));
+      // user + assistant (with both tool-calls) + tool (with both results)
+      expect(written).toHaveLength(3);
+      expect(written[0].role).toBe("user");
+      expect(written[1].role).toBe("assistant");
+      expect(written[1].content).toHaveLength(2);
+      const assistantToolIds = written[1].content.map(
+        (c: { toolCallId: string }) => c.toolCallId,
+      );
+      expect(assistantToolIds.sort()).toEqual(["tcA", "tcB"]);
+
+      expect(written[2].role).toBe("tool");
+      expect(written[2].content).toHaveLength(2);
+      const toolResultIds = written[2].content.map(
+        (c: { toolCallId: string }) => c.toolCallId,
+      );
+      expect(toolResultIds.sort()).toEqual(["tcA", "tcB"]);
+
+      // Tool A has real result, Tool B has synthetic error-text
+      const resultA = written[2].content.find(
+        (c: { toolCallId: string }) => c.toolCallId === "tcA",
+      );
+      const resultB = written[2].content.find(
+        (c: { toolCallId: string }) => c.toolCallId === "tcB",
+      );
+      expect(resultA.output.type).toBe("text");
+      expect(resultB.output.type).toBe("error-text");
+
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+  });
+
+  describe("multi-step abort does not duplicate prior steps (bugbot fix)", () => {
+    it("clears completed results at finish-step so earlier steps aren't re-appended", async () => {
+      const tmpDir = join("/tmp", `pensar-test-${Date.now()}-multistep`);
+      mkdirSync(tmpDir, { recursive: true });
+      const messagesPath = join(tmpDir, "messages.json");
+
+      // Step 1 already persisted by onStepFinish: tool A called and resolved.
+      const persistedAfterStep1 = [
+        { role: "user", content: [{ type: "text", text: "scan" }] },
+        {
+          role: "assistant",
+          content: [
+            { type: "tool-call", toolCallId: "tcA", toolName: "read_file" },
+          ],
+        },
+        {
+          role: "tool",
+          content: [
+            {
+              type: "tool-result",
+              toolCallId: "tcA",
+              toolName: "read_file",
+              output: { type: "text", value: "file contents" },
+            },
+          ],
+        },
+      ];
+      writeFileSync(messagesPath, JSON.stringify(persistedAfterStep1));
+
+      // Replays step 1's chunks, finishes the step, then opens tool B in step 2 before erroring.
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [
+            { type: "tool-call", toolCallId: "tcA", toolName: "read_file" },
+            {
+              type: "tool-result",
+              toolCallId: "tcA",
+              toolName: "read_file",
+              result: { type: "text", value: "file contents" },
+            },
+            { type: "finish-step" },
+            {
+              type: "tool-call",
+              toolCallId: "tcB",
+              toolName: "execute_command",
+            },
+          ],
+          new Error("connection lost"),
+        ),
+        messagesPath,
+        latestMessages: persistedAfterStep1,
+      });
+
+      try {
+        await agent.consume();
+      } catch {}
+      await new Promise((r) => setTimeout(r, 50));
+
+      const written = JSON.parse(readFileSync(messagesPath, "utf-8"));
+      const toolCallIds = written
+        .filter((m: { role: string }) => m.role === "assistant")
+        .flatMap((m: { content: { toolCallId?: string }[] }) =>
+          m.content.map((c) => c.toolCallId),
+        );
+      // tcA must appear exactly once — the abort snapshot must not re-append it.
+      expect(toolCallIds.filter((id: string) => id === "tcA")).toHaveLength(1);
+      expect(toolCallIds.filter((id: string) => id === "tcB")).toHaveLength(1);
+
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+  });
+
+  describe("failed abort write leaves flag unset (bugbot fix)", () => {
+    const toolCallChunk = {
+      type: "tool-call",
+      toolCallId: "tc1",
+      toolName: "execute_command",
+    };
+
+    it("does not mark synthetics persisted when the write fails", async () => {
+      // A path inside a non-existent directory makes writeFile reject.
+      const messagesPath = join(
+        "/tmp",
+        `pensar-test-${Date.now()}-missing`,
+        "nope",
+        "messages.json",
+      );
+
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([toolCallChunk], new Error("stream broke")),
+        messagesPath,
+        latestMessages: [
+          { role: "user", content: [{ type: "text", text: "scan" }] },
+        ],
+      });
+
+      try {
+        await agent.consume();
+      } catch {}
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(
+        (
+          agent as unknown as {
+            writer: { syntheticsPersisted: boolean };
+          }
+        ).writer.syntheticsPersisted,
+      ).toBeFalsy();
+    });
+  });
+
+  describe("emitSyntheticToolResults error does not mask stream error (bugbot fix)", () => {
+    const toolCallChunk = {
+      type: "tool-call",
+      toolCallId: "tc1",
+      toolName: "execute_command",
+    };
+
+    it("propagates original stream error when event listener throws", async () => {
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [toolCallChunk],
+          new Error("original stream error"),
+        ),
+      });
+
+      agent.eventBus.on("tool-result", () => {
+        throw new Error("listener explosion");
+      });
+
+      // The original stream error must propagate, not the listener error
+      await expect(agent.consume()).rejects.toThrow("original stream error");
+    });
+
+    it("still disposes shell when emitSyntheticToolResults throws", async () => {
+      const dispose = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow([toolCallChunk], new Error("stream broke")),
+        commandShell: { dispose },
+      });
+
+      agent.eventBus.on("tool-result", () => {
+        throw new Error("listener crash");
+      });
+
+      await expect(agent.consume()).rejects.toThrow("stream broke");
+      expect(dispose).toHaveBeenCalledOnce();
+    });
+
+    it("preserves the stream error and disposes resources when deferred emission throws", async () => {
+      const tmpDir = join("/tmp", `pensar-test-${Date.now()}-listener-error`);
+      mkdirSync(tmpDir, { recursive: true });
+      const messagesPath = join(tmpDir, "messages.json");
+      const existingMessages = [
+        { role: "user", content: [{ type: "text", text: "scan" }] },
+      ];
+      writeFileSync(messagesPath, JSON.stringify(existingMessages));
+
+      const streamError = new Error("original stream error");
+      const dispose = vi.fn().mockResolvedValue(undefined);
+      const disconnect = vi.fn().mockResolvedValue(undefined);
+      const agent = buildStubAgent({
+        fullStream: yieldThenThrow(
+          [
+            {
+              type: "tool-error",
+              toolCallId: "tc1",
+              toolName: "execute_command",
+              error: new Error("tool validation failed"),
+            },
+          ],
+          streamError,
+        ),
+        commandShell: { dispose },
+        browserSession: { disconnect },
+        ownsBrowserSession: true,
+        messagesPath,
+        latestMessages: existingMessages,
+      });
+
+      agent.eventBus.on("tool-result", () => {
+        throw new Error("listener explosion");
+      });
+
+      await expect(agent.consume()).rejects.toBe(streamError);
+      expect(dispose).toHaveBeenCalledOnce();
+      expect(disconnect).toHaveBeenCalledOnce();
+
+      const written = JSON.parse(readFileSync(messagesPath, "utf-8"));
+      expect(written.at(-2)).toMatchObject({
+        role: "assistant",
+        content: [{ type: "tool-call", toolCallId: "tc1" }],
+      });
+      expect(written.at(-1)).toMatchObject({
+        role: "tool",
+        content: [{ type: "tool-result", toolCallId: "tc1" }],
+      });
+
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Owned-resource disposal — explicit idempotent operations (A6)
+// ---------------------------------------------------------------------------
+
+describe("owned-resource disposal", () => {
+  const toolCallChunk = {
+    type: "tool-call",
+    toolCallId: "tc1",
+    toolName: "execute_command",
+  };
+
+  it("disposeOwnedShell is idempotent and returns the same cached barrier", async () => {
+    const dispose = vi.fn().mockResolvedValue(undefined);
+    const agent = buildStubAgent({
+      fullStream: yieldChunks([]),
+      commandShell: { dispose },
+    });
+
+    const first = agent.disposeOwnedShell();
+    const second = agent.disposeOwnedShell();
+    const third = agent.disposeOwnedShell();
+    expect(second).toBe(first);
+    expect(third).toBe(first);
+
+    await first;
+    expect(dispose).toHaveBeenCalledOnce();
+  });
+
+  it("disposeOwnedShell is a no-op with no shell (construction without one)", () => {
+    const agent = buildStubAgent({ fullStream: yieldChunks([]) });
+    expect(() => agent.disposeOwnedShell()).not.toThrow();
+  });
+
+  it("browser disconnect is idempotent across consume finalization and later teardown", async () => {
+    const disconnect = vi.fn().mockResolvedValue(undefined);
+    const agent = buildStubAgent({
+      fullStream: yieldThenThrow([toolCallChunk], new Error("stream broke")),
+      browserSession: { disconnect },
+      ownsBrowserSession: true,
+    });
+
+    // consume()'s finalization disconnects; later host teardown must not repeat it.
+    try {
+      await agent.consume();
+    } catch {}
+    await agent.abortAndDrain();
+    await agent.abortAndDrain();
+
+    expect(disconnect).toHaveBeenCalledOnce();
+  });
+
+  it("abortAndDrain disconnects the browser exactly once", async () => {
+    const disconnect = vi.fn().mockResolvedValue(undefined);
+    const agent = buildStubAgent({
+      fullStream: yieldThenThrow([toolCallChunk], new Error("aborted")),
+      browserSession: { disconnect },
+      ownsBrowserSession: true,
+    });
+
+    const consume = agent.consume().catch(() => {});
+    await agent.abortAndDrain();
+    await agent.abortAndDrain();
+    await consume;
+
+    expect(disconnect).toHaveBeenCalledOnce();
+  });
+
+  it("browser disconnect failure is swallowed and the run still settles", async () => {
+    const disconnect = vi.fn().mockRejectedValue(new Error("disconnect boom"));
+    const agent = buildStubAgent({
+      fullStream: yieldThenThrow([toolCallChunk], new Error("stream broke")),
+      browserSession: { disconnect },
+      ownsBrowserSession: true,
+    });
+
+    // The stream error propagates; the disconnect failure does not replace it
+    // and does not reject the teardown await.
+    await expect(agent.consume()).rejects.toThrow("stream broke");
+    expect(disconnect).toHaveBeenCalledOnce();
+  });
+
+  it("early result capture disconnects the browser without waiting for the drain", async () => {
+    const disconnect = vi.fn().mockResolvedValue(undefined);
+    // Stream that never ends on its own — only result capture unblocks consume.
+    async function* endless(): AsyncGenerator<unknown, void, undefined> {
+      yield toolCallChunk;
+      await new Promise(() => {});
+    }
+    const agent = buildStubAgent({
+      fullStream: endless(),
+      browserSession: { disconnect },
+      ownsBrowserSession: true,
+      responseCaptured: Promise.resolve("captured"),
+    });
+    Object.defineProperty(agent, "resolveResult", {
+      value: undefined,
+    });
+
+    const result = await Promise.race([
+      agent.consume(),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error("capture path stalled")), 1000),
+      ),
+    ]);
+
+    expect(result).toBe("captured");
+    expect(disconnect).toHaveBeenCalledOnce();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// O3: root agent-run spans — every consume() execution runs inside an
+// invoke_agent span with full run attribution.
+// ---------------------------------------------------------------------------
+
+describe("root agent-run spans", () => {
+  const textChunk = { type: "text-delta", id: "t1", delta: "hi" };
+
+  async function* singleStepStream(): AsyncGenerator<unknown, void, undefined> {
+    yield textChunk;
+  }
+
+  function setupOtel() {
+    // Local in-memory harness (mirrors observability/testkit, inlined per
+    // this file's "helpers must be inlined" rule).
+    const { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } =
+      require("@opentelemetry/sdk-trace-base") as typeof import("@opentelemetry/sdk-trace-base");
+    const { AsyncLocalStorageContextManager } =
+      require("@opentelemetry/context-async-hooks") as typeof import("@opentelemetry/context-async-hooks");
+    const api =
+      require("@opentelemetry/api") as typeof import("@opentelemetry/api");
+    const exporter = new InMemorySpanExporter();
+    const provider = new BasicTracerProvider({
+      spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+    const contextManager = new AsyncLocalStorageContextManager();
+    contextManager.enable();
+    api.trace.setGlobalTracerProvider(provider);
+    api.context.setGlobalContextManager(contextManager);
+    return {
+      exporter,
+      spans: () => exporter.getFinishedSpans(),
+      async teardown() {
+        await provider.shutdown();
+        contextManager.disable();
+        api.trace.disable();
+        api.context.disable();
+      },
+    };
+  }
+
+  it("one root span per top-level run, with canonical identity", async () => {
+    const otel = setupOtel();
+    try {
+      const agent = buildStubAgent({ fullStream: singleStepStream() });
+      await agent.consume();
+
+      const spans = otel.spans();
+      const invokeSpans = spans.filter(
+        (s) => s.name === "invoke_agent default",
+      );
+      expect(invokeSpans).toHaveLength(1);
+      const attrs = invokeSpans[0]?.attributes as Record<string, string>;
+      expect(attrs["gen_ai.operation.name"]).toBe("invoke_agent");
+      expect(attrs["gen_ai.agent.id"]).toBe("ses_stub");
+      expect(attrs["gen_ai.agent.name"]).toBe("default");
+      expect(attrs["gen_ai.conversation.id"]).toBe("ses_stub");
+      expect(attrs["session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.root_session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.agent.mode"]).toBe("default");
+      expect(attrs["pensar.run.id"]).toBeUndefined();
+      expect(attrs["pensar.agent.execution.id"]).toBeUndefined();
+    } finally {
+      await otel.teardown();
+    }
+  });
+
+  it("successful runs leave status unset", async () => {
+    const otel = setupOtel();
+    try {
+      const agent = buildStubAgent({ fullStream: singleStepStream() });
+      await agent.consume();
+
+      const span = otel.spans().find((s) => s.name === "invoke_agent default");
+      expect(span).toBeDefined();
+      expect(span?.status.code).not.toBe(2); // SpanStatusCode.ERROR
+      expect(span?.ended).toBe(true);
+    } finally {
+      await otel.teardown();
+    }
+  });
+
+  it("failed runs use error status with exception and low-cardinality error.type", async () => {
+    const otel = setupOtel();
+    try {
+      async function* failingStream(): AsyncGenerator<
+        unknown,
+        void,
+        undefined
+      > {
+        yield textChunk;
+        throw new Error("provider exploded");
+      }
+      const agent = buildStubAgent({ fullStream: failingStream() });
+      await expect(agent.consume()).rejects.toThrow("provider exploded");
+
+      const span = otel.spans().find((s) => s.name === "invoke_agent default");
+      expect(span).toBeDefined();
+      expect(span?.status.code).toBe(2);
+      expect(
+        span?.events.some(
+          (e) =>
+            e.name === "exception" &&
+            (e.attributes?.["exception.message"] as string) ===
+              "provider exploded",
+        ),
+      ).toBe(true);
+      expect(span?.attributes["error.type"]).toBe("Error");
+      expect(span?.ended).toBe(true);
+    } finally {
+      await otel.teardown();
+    }
+  });
+
+  it("records the originating infrastructure cause on the root span", async () => {
+    const otel = setupOtel();
+    const controller = new AbortController();
+    const cause = new Error("Execution receipt unavailable");
+    cause.name = "ExecutionInfrastructureError";
+    controller.abort(cause);
+    try {
+      const agent = buildStubAgent({
+        fullStream: singleStepStream(),
+        abortSignal: controller.signal,
+      });
+      await expect(agent.consume()).rejects.toBe(cause);
+      const span = otel
+        .spans()
+        .find((entry) => entry.name === "invoke_agent default");
+      expect(span?.status.code).toBe(2);
+      expect(span?.attributes["error.type"]).toBe(cause.name);
+      expect(
+        span?.events.some(
+          (event) =>
+            event.name === "exception" &&
+            event.attributes?.["exception.message"] === cause.message,
+        ),
+      ).toBe(true);
+      expect(span?.ended).toBe(true);
+    } finally {
+      await otel.teardown();
+    }
+  });
+
+  it("aborted runs end every span", async () => {
+    const otel = setupOtel();
+    try {
+      const controller = new AbortController();
+      async function* abortingStream(): AsyncGenerator<
+        unknown,
+        void,
+        undefined
+      > {
+        yield textChunk;
+        controller.abort();
+        throw new DOMException("Agent aborted by user", "AbortError");
+      }
+      const agent = buildStubAgent({
+        fullStream: abortingStream(),
+        abortSignal: controller.signal,
+      });
+      await expect(agent.consume()).rejects.toThrow();
+
+      const spans = otel.spans();
+      const invokeSpan = spans.find((s) => s.name === "invoke_agent default");
+      expect(invokeSpan?.ended).toBe(true);
+      expect(invokeSpan?.attributes["error.type"]).toBe("AbortError");
+    } finally {
+      await otel.teardown();
+    }
+  });
+
+  it("persistence and disposal finish before the root span ends", async () => {
+    const otel = setupOtel();
+    try {
+      // Finalization ordering: the stub's shell disposal runs inside
+      // runConsume's finally; the span ends only after that settles. Since
+      // export happens exclusively on span.end(), observing the exported
+      // span proves the span ended — and consume() resolving proves disposal
+      // completed first (both are awaited in order inside runInSpan).
+      const ordering: string[] = [];
+      const dispose = vi.fn(() => {
+        ordering.push("shell-disposed");
+        return Promise.resolve();
+      });
+      const agent = buildStubAgent({
+        fullStream: singleStepStream(),
+        commandShell: { dispose },
+      });
+      await agent.consume();
+
+      // Consume resolved: disposal ran during finalization; the span ended
+      // after (finally order in runInSpan). The exporter saw the span after
+      // disposal because export only happens on span.end().
+      expect(dispose).toHaveBeenCalledOnce();
+      const span = otel.spans().find((s) => s.name === "invoke_agent default");
+      expect(span?.ended).toBe(true);
+      // Direct ordering proof: a span-end observer sees disposal already done.
+      expect(ordering).toEqual(["shell-disposed"]);
+    } finally {
+      await otel.teardown();
+    }
+  });
+
+  it("subagent runs keep current and root identity distinct", async () => {
+    const otel = setupOtel();
+    try {
+      const agent = buildStubAgent({
+        fullStream: singleStepStream(),
+        subagentId: "ses_sub_1",
+        subagentName: "recon-sub",
+      });
+      await agent.consume();
+
+      const span = otel
+        .spans()
+        .find((s) => s.name === "invoke_agent recon-sub");
+      expect(span).toBeDefined();
+      const attrs = span?.attributes as Record<string, string>;
+      expect(attrs["gen_ai.agent.id"]).toBe("ses_sub_1");
+      expect(attrs["gen_ai.agent.name"]).toBe("recon-sub");
+      expect(attrs["gen_ai.conversation.id"]).toBe("ses_stub");
+      expect(attrs["session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.session.id"]).toBe("ses_sub_1");
+      expect(attrs["pensar.root_session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.agent.execution.id"]).toBeUndefined();
+      expect(attrs["pensar.run.id"]).toBeUndefined();
+      expect(attrs["pensar.agent.mode"]).toBeUndefined();
+    } finally {
+      await otel.teardown();
+    }
+  });
+});
+
+describe("OffensiveSecurityAgent.consume() streamIdFactory", () => {
+  const startStep = { type: "start-step" };
+  const textStart = { type: "text-start", id: "t0" };
+  const textDelta = { type: "text-delta", id: "t0", text: "hi" };
+
+  it("mints message and text-part ids from the factory with positional context", async () => {
+    const streamIdFactory = vi.fn((context: unknown) => {
+      const ctx = context as {
+        kind: string;
+        stepIndex?: number;
+        textPartIndex?: number;
+      };
+      if (ctx.kind === "message") return `msg-${ctx.stepIndex}`;
+      if (ctx.kind === "text-part")
+        return `part-${ctx.stepIndex}-${ctx.textPartIndex}`;
+      return "tool";
+    });
+    const agent = buildStubAgent({
+      fullStream: yieldChunks([startStep, textStart, textDelta]),
+      streamIdFactory,
+    });
+    const emitted: Array<{ messageId?: string; textPartId?: string }> = [];
+    vi.spyOn(agent.eventBus, "emitStreamPart").mockImplementation(((
+      _chunk: unknown,
+      ids: { messageId?: string; textPartId?: string },
+    ) => {
+      emitted.push({ messageId: ids.messageId, textPartId: ids.textPartId });
+    }) as unknown as AgentEventBus["emitStreamPart"]);
+
+    await agent.consume();
+
+    expect(streamIdFactory).toHaveBeenCalledWith({
+      kind: "message",
+      stepIndex: 0,
+    });
+    expect(streamIdFactory).toHaveBeenCalledWith({
+      kind: "text-part",
+      stepIndex: 0,
+      textPartIndex: 0,
+    });
+    const deltaEmit = emitted.at(-1);
+    expect(deltaEmit?.messageId).toBe("msg-0");
+    expect(deltaEmit?.textPartId).toBe("part-0-0");
+  });
+
+  it("falls back to random ids when no factory is provided", async () => {
+    const agent = buildStubAgent({
+      fullStream: yieldChunks([startStep, textStart, textDelta]),
+    });
+    const emitted: Array<{ messageId?: string }> = [];
+    vi.spyOn(agent.eventBus, "emitStreamPart").mockImplementation(((
+      _chunk: unknown,
+      ids: { messageId?: string },
+    ) => {
+      emitted.push({ messageId: ids.messageId });
+    }) as unknown as AgentEventBus["emitStreamPart"]);
+
+    await agent.consume();
+
+    const deltaEmit = emitted.at(-1);
+    expect(typeof deltaEmit?.messageId).toBe("string");
+    expect(deltaEmit?.messageId).not.toBe("msg-0");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// O3/PR3: in-stream error parts complete every span (agent + generation)
+// ---------------------------------------------------------------------------
+
+describe("error-part span completion", () => {
+  it("an error-part run exports the agent span with error status", async () => {
+    // Local in-memory harness (inlined per this file's rule).
+    const { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } =
+      require("@opentelemetry/sdk-trace-base") as typeof import("@opentelemetry/sdk-trace-base");
+    const { AsyncLocalStorageContextManager } =
+      require("@opentelemetry/context-async-hooks") as typeof import("@opentelemetry/context-async-hooks");
+    const api =
+      require("@opentelemetry/api") as typeof import("@opentelemetry/api");
+    const exporter = new InMemorySpanExporter();
+    const provider = new BasicTracerProvider({
+      spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+    const contextManager = new AsyncLocalStorageContextManager();
+    contextManager.enable();
+    api.trace.setGlobalTracerProvider(provider);
+    api.context.setGlobalContextManager(contextManager);
+
+    try {
+      // The stream yields a chunk then an error — the raw generator mimics
+      // the AI SDK's error part (consume() sees it as a thrown error after
+      // the drain in the real pipeline).
+      async function* errorPartStream(): AsyncGenerator<
+        unknown,
+        void,
+        undefined
+      > {
+        yield { type: "text-delta", id: "t1", delta: "partial" };
+        throw new Error("model exploded mid-stream");
+      }
+      const agent = buildStubAgent({ fullStream: errorPartStream() });
+      await expect(agent.consume()).rejects.toThrow("model exploded");
+
+      const span = exporter
+        .getFinishedSpans()
+        .find((s) => s.name === "invoke_agent default");
+      expect(span).toBeDefined();
+      expect(span?.status.code).toBe(api.SpanStatusCode.ERROR);
+      expect(span?.attributes["error.type"]).toBe("Error");
+      expect(span?.ended).toBe(true);
+    } finally {
+      await provider.shutdown();
+      contextManager.disable();
+      api.trace.disable();
+      api.context.disable();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// PR4: root IO + consistent trace identity
+// ---------------------------------------------------------------------------
+
+describe("trace identity and root IO", () => {
+  const textChunk = { type: "text-delta", id: "t1", delta: "hi" };
+  async function* oneStep(): AsyncGenerator<unknown, void, undefined> {
+    yield textChunk;
+  }
+
+  function setupOtel() {
+    const { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } =
+      require("@opentelemetry/sdk-trace-base") as typeof import("@opentelemetry/sdk-trace-base");
+    const { AsyncLocalStorageContextManager } =
+      require("@opentelemetry/context-async-hooks") as typeof import("@opentelemetry/context-async-hooks");
+    const api =
+      require("@opentelemetry/api") as typeof import("@opentelemetry/api");
+    const exporter = new InMemorySpanExporter();
+    const provider = new BasicTracerProvider({
+      spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+    const contextManager = new AsyncLocalStorageContextManager();
+    contextManager.enable();
+    api.trace.setGlobalTracerProvider(provider);
+    api.context.setGlobalContextManager(contextManager);
+    return {
+      spans: () => exporter.getFinishedSpans(),
+      async teardown() {
+        await provider.shutdown();
+        contextManager.disable();
+        api.trace.disable();
+        api.context.disable();
+      },
+    };
+  }
+
+  it("root spans carry canonical conversation and agent identity", async () => {
+    const otel = setupOtel();
+    try {
+      const agent = buildStubAgent({ fullStream: oneStep() });
+      await agent.consume();
+
+      const span = otel.spans().find((s) => s.name === "invoke_agent default");
+      const attrs = span?.attributes as Record<string, string>;
+      expect(attrs["gen_ai.agent.id"]).toBe("ses_stub");
+      expect(attrs["gen_ai.conversation.id"]).toBe("ses_stub");
+      expect(attrs["session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.root_session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.run.id"]).toBeUndefined();
+      expect(attrs["pensar.agent.execution.id"]).toBeUndefined();
+    } finally {
+      await otel.teardown();
+    }
+  });
+
+  it("subagent spans separate agent identity from the root conversation", async () => {
+    const otel = setupOtel();
+    try {
+      const agent = buildStubAgent({
+        fullStream: oneStep(),
+        subagentId: "ses_exec_1",
+        subagentName: "recon-sub",
+      });
+      await agent.consume();
+
+      const span = otel
+        .spans()
+        .find((s) => s.name === "invoke_agent recon-sub");
+      const attrs = span?.attributes as Record<string, string>;
+      expect(attrs["gen_ai.agent.id"]).toBe("ses_exec_1");
+      expect(attrs["gen_ai.conversation.id"]).toBe("ses_stub");
+      expect(attrs["session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.session.id"]).toBe("ses_exec_1");
+      expect(attrs["pensar.root_session.id"]).toBe("ses_stub");
+      expect(attrs["pensar.agent.execution.id"]).toBeUndefined();
+      expect(attrs["pensar.run.id"]).toBeUndefined();
+    } finally {
+      await otel.teardown();
+    }
+  });
+
+  it("root span IO appears only under full payload capture", async () => {
+    process.env.AI_TRACE_RECORD_PAYLOADS = "true";
+    const otel = setupOtel();
+    try {
+      const agent = buildStubAgent({ fullStream: oneStep() });
+      Object.defineProperty(agent, "userPrompt", {
+        value: "pentest the acme api",
+      });
+      await agent.consume();
+
+      const span = otel.spans().find((s) => s.name === "invoke_agent default");
+      expect(span?.attributes["gen_ai.prompt"]).toBe("pentest the acme api");
+    } finally {
+      await otel.teardown();
+      process.env.AI_TRACE_RECORD_PAYLOADS = undefined;
+    }
+
+    // Default mode: metadata only — no prompt or result payload.
+    const otel2 = setupOtel();
+    try {
+      const agent = buildStubAgent({ fullStream: oneStep() });
+      Object.defineProperty(agent, "userPrompt", {
+        value: "pentest the acme api",
+      });
+      await agent.consume();
+      const span = otel2.spans().find((s) => s.name === "invoke_agent default");
+      expect(span?.attributes["gen_ai.prompt"]).toBeUndefined();
+      expect(span?.attributes["gen_ai.completion"]).toBeUndefined();
+    } finally {
+      await otel2.teardown();
+    }
+  });
+
+  it("records root IO for the primary Fast Strike run", async () => {
+    process.env.AI_TRACE_RECORD_PAYLOADS = "true";
+    const otel = setupOtel();
+    try {
+      const agent = buildStubAgent({
+        fullStream: oneStep(),
+        resolveResult: () => ({ summary: "strike complete" }),
+        subagentId: "fast-strike",
+        agentMode: "fast-strike",
+      });
+      Object.defineProperty(agent, "userPrompt", {
+        value: "strike the acme api",
+      });
+
+      await agent.consume();
+
+      const span = otel
+        .spans()
+        .find((candidate) => candidate.name === "invoke_agent fast-strike");
+      expect(span?.attributes["gen_ai.prompt"]).toBe("strike the acme api");
+      expect(String(span?.attributes["gen_ai.completion"])).toContain(
+        '"summary":"strike complete"',
+      );
+    } finally {
+      await otel.teardown();
+      process.env.AI_TRACE_RECORD_PAYLOADS = undefined;
+    }
+  });
+
+  it("records the captured response tool result as root output", async () => {
+    process.env.AI_TRACE_RECORD_PAYLOADS = "true";
+    const otel = setupOtel();
+    try {
+      const agent = buildStubAgent({
+        fullStream: oneStep(),
+        responseCaptured: Promise.resolve({ summary: "scan complete" }),
+        responseToolResult: { summary: "scan complete" },
+      });
+      Object.defineProperty(agent, "_responseToolFired", { value: true });
+
+      await agent.consume();
+      await agent.drained;
+
+      const span = otel.spans().find((s) => s.name === "invoke_agent default");
+      expect(String(span?.attributes["gen_ai.completion"])).toContain(
+        '"summary":"scan complete"',
+      );
+    } finally {
+      await otel.teardown();
+      process.env.AI_TRACE_RECORD_PAYLOADS = undefined;
+    }
+  });
+
+  it("does not wait on response resolution before ending a response-tool run", async () => {
+    process.env.AI_TRACE_RECORD_PAYLOADS = "true";
+    const otel = setupOtel();
+    let resolveCaptured!: (value: unknown) => void;
+    const responseCaptured = new Promise<unknown>((resolve) => {
+      resolveCaptured = resolve;
+    });
+    try {
+      const agent = buildStubAgent({
+        fullStream: oneStep(),
+        responseCaptured,
+        responseToolResult: { summary: "submitted" },
+      });
+      Object.defineProperty(agent, "_responseToolFired", { value: true });
+
+      const consume = agent.consume();
+      const drainRejection = Reflect.get(
+        agent,
+        "_drainRejection",
+      ) as Promise<never>;
+      void drainRejection.catch(() => {
+        resolveCaptured({ summary: "resolved" });
+      });
+
+      const result = await Promise.race([
+        consume,
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(new Error("response resolution stalled")),
+            1000,
+          ),
+        ),
+      ]);
+      await agent.drained;
+
+      expect(result).toEqual({ summary: "resolved" });
+      const span = otel.spans().find((s) => s.name === "invoke_agent default");
+      expect(span?.ended).toBe(true);
+      expect(String(span?.attributes["gen_ai.completion"])).toContain(
+        '"summary":"submitted"',
+      );
+    } finally {
+      resolveCaptured(undefined);
+      await otel.teardown();
+      process.env.AI_TRACE_RECORD_PAYLOADS = undefined;
+    }
+  });
+
+  it("preserves captured output when the background drain later fails", async () => {
+    process.env.AI_TRACE_RECORD_PAYLOADS = "true";
+    const otel = setupOtel();
+    const captured = { summary: "scan complete" };
+    try {
+      async function* failingAfterResponse(): AsyncGenerator<
+        unknown,
+        void,
+        undefined
+      > {
+        yield textChunk;
+        throw new Error("late drain failure");
+      }
+      const agent = buildStubAgent({
+        fullStream: failingAfterResponse(),
+        responseCaptured: Promise.resolve(captured),
+        responseToolResult: captured,
+      });
+      Object.defineProperty(agent, "_responseToolFired", { value: true });
+
+      await expect(agent.consume()).resolves.toEqual(captured);
+      await agent.drained;
+
+      const span = otel.spans().find((s) => s.name === "invoke_agent default");
+      expect(String(span?.attributes["gen_ai.completion"])).toContain(
+        '"summary":"scan complete"',
+      );
+      expect(String(span?.attributes["gen_ai.completion"])).not.toContain(
+        "Failure: late drain failure",
+      );
+    } finally {
+      await otel.teardown();
+      process.env.AI_TRACE_RECORD_PAYLOADS = undefined;
+    }
+  });
+
+  it("failed runs record the failure as root output under full capture", async () => {
+    process.env.AI_TRACE_RECORD_PAYLOADS = "true";
+    const otel = setupOtel();
+    try {
+      async function* failing(): AsyncGenerator<unknown, void, undefined> {
+        yield textChunk;
+        throw new Error("final failure");
+      }
+      const agent = buildStubAgent({ fullStream: failing() });
+      await expect(agent.consume()).rejects.toThrow("final failure");
+
+      const span = otel.spans().find((s) => s.name === "invoke_agent default");
+      expect(String(span?.attributes["gen_ai.completion"])).toContain(
+        "Failure: final failure",
+      );
+    } finally {
+      await otel.teardown();
+      process.env.AI_TRACE_RECORD_PAYLOADS = undefined;
+    }
+  });
+});
+
+describe("contextRecorder integration", () => {
+  const streamTextChunk = { type: "text-delta", id: "t1", delta: "hi" };
+  const CANONICAL = [
+    { role: "user", content: "recorded prompt" },
+    { role: "assistant", content: "recorded answer" },
+  ] as never[];
+
+  it("flush failure in finalization fails the run after the stream completed", async () => {
+    // Stream completes normally, but the last step's commit failed and the
+    // recorder latched it — finalizeRun's flush must surface it (the SDK
+    // swallows onStepFinish errors, so nothing else would).
+    const flushError = new Error("latched persistence failure");
+    const recorder: RunContextRecorder = {
+      checkpoint: vi.fn(async () => {}),
+      flush: vi.fn(async () => {
+        throw flushError;
+      }),
+      latest: vi.fn(() => undefined),
+    };
+
+    async function* complete(): AsyncGenerator<unknown, void, undefined> {
+      yield streamTextChunk;
+    }
+    const agent = buildStubAgent({
+      fullStream: complete(),
+      contextRecorder: recorder,
+    });
+
+    await expect(agent.consume()).rejects.toBe(flushError);
+  });
+
+  it("canonical latest drives the projection on steps and finish; no duplicated prefix", async () => {
+    const rootPath = mkdtempSync(join(tmpdir(), "apex-recorder-projection-"));
+    streamResponseCalls.length = 0;
+    const recorder: RunContextRecorder = {
+      checkpoint: vi.fn(async () => {}),
+      flush: vi.fn(async () => {}),
+      latest: vi.fn(() => structuredClone(CANONICAL)),
+    };
+    const inferenceRecorder: InferenceRecorder = {
+      runId: "run_recorder_projection",
+      beforeDispatch: vi.fn(async () => {}),
+      beforeToolCall: vi.fn(async () => {}),
+      settle: vi.fn(),
+      retry: vi.fn(async () => {}),
+      flush: vi.fn(async () => {}),
+    };
+    const agent = new OffensiveSecurityAgent({
+      prompt: "recorded prompt",
+      model: "test-model",
+      session: {
+        id: "ses_recorder_projection",
+        rootPath,
+        scratchpadPath: join(rootPath, "scratchpad"),
+      },
+      activeTools: [],
+      contextRecorder: recorder,
+      inferenceRecorder,
+    } as never);
+    void agent.streamResult; // createStream is lazy — force construction
+
+    const streamOpts = streamResponseCalls[0] as {
+      onStepFinish: (event: unknown) => Promise<void>;
+      onFinish: (event: unknown) => Promise<void>;
+    };
+    expect(
+      (streamResponseCalls[0] as { contextRecorder: unknown }).contextRecorder,
+    ).toBe(recorder);
+    expect(streamResponseCalls[0]?.inferenceRecorder).toBe(inferenceRecorder);
+
+    const stepEvent = {
+      response: { id: "resp_1", messages: CANONICAL.slice(1) },
+      usage: {},
+    };
+    await streamOpts.onStepFinish(stepEvent);
+
+    // Writer snapshot equals canonical latest() exactly — the step's
+    // response.messages are already part of the committed context, so the
+    // projection must not re-prepend a base or duplicate them.
+    const writer = agent["writer" as keyof typeof agent] as unknown as {
+      waitForPendingWrites: () => Promise<void>;
+      latest: unknown[] | null;
+    };
+    await writer.waitForPendingWrites().catch(() => {});
+    const captured = writer.latest;
+
+    // onFinish falls back to canonical latest when the writer has nothing.
+    const finishEvent = { response: { messages: [] } };
+    await streamOpts.onFinish(finishEvent);
+
+    expect(recorder.latest).toHaveBeenCalled();
+    expect((captured as unknown[]).length).toBe(CANONICAL.length);
+  });
+});