@stigmer/runner 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/activities/execute-deep-agent/__tests__/{v3-status-builder.test.ts → translator-through-builder.test.ts}

@@ -1,13 +1,34 @@
+/**
+ * The native translator's integration arms: raw LangGraph v3 protocol events
+ * through `DeepAgentTranslator` and then `TranscriptBuilder`, end to end —
+ * the exact path `turn-stream.ts`'s loop takes — asserting the transcript
+ * that comes out. Every sequence here is the wire's real shape (the fixtures
+ * default to LangGraph's namespaces), so these arms prove that the
+ * translator's reading of the engine and the builder's rules compose into
+ * the goldens' shapes.
+ *
+ * What is NOT here: the builder's own rules, driven with
+ * `TranscriptEvent`s directly, live in
+ * `harness/transcript/__tests__/builder.test.ts`; the translator's own
+ * reading of the wire in `translator.test.ts`. This file began as the
+ * builder's unit suite when the builder was the native adapter's
+ * (`v3-status-builder.test.ts`, #1096) and became what it always was in
+ * truth in #1097.
+ *
+ * In the adapter's folder because the fixtures and the translator are
+ * `activities/` modules the direction fence keeps out of `harness/`.
+ */
+
 import { describe, it, expect, beforeEach } from "vitest";
 import { create } from "@bufbuild/protobuf";
-import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import { ApprovalAction, ExecutionPhase, MessageType, ToolCallStatus, ToolKind, TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { type AgentExecutionStatus, AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApprovalAction, ApprovalPolicySource, ExecutionPhase, MessageType, ToolCallStatus, ToolKind, TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import { WorkspaceWriteBackSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
-import { V3StatusBuilder } from "../v3-status-builder.js";
-import { normalize } from "../v3-protocol-normalizer.js";
-import type { ApprovalPolicyProvider } from "../status-builder-shared.js";
+import { TranscriptBuilder } from "../../../harness/transcript/builder.js";
+import { DeepAgentTranslator } from "../translator.js";
+import type { DeepAgentGateState } from "../turn-setup.js";
 import type { MergedToolPolicy } from "../../../shared/approval-policy.js";
 import {
   resetSeq,
@@ -20,69 +41,52 @@ import {
   makeToolError,
   makeToolCallArgDelta,
   makeToolOutputDelta,
-  makeUsageEvent,
 } from "../__test-utils__/v3-event-fixtures.js";
 import type { V3ProtocolEvent } from "../v3-event-recorder.js";
 
 /**
- * What the builder REPORTED through `onUsage`, summed by the test the way an
- * accountant would (the builder itself sums nothing and writes no
- * `streamingUsage`; the runtime does, priced, through the sink).
+ * A builder over an empty status. Usage never reaches the builder:
+ * the loop reads it off the wire through `usageOf` and prices it into the
+ * sink — `turn-stream.test.ts` pins that; `translator.test.ts` pins what
+ * `usageOf` reads. The `usage:` fields the sequences below still
+ * carry are the wire's real shape and are ignored by everything here.
  */
-interface ReportedUsage {
-  inputTokens: number;
-  outputTokens: number;
-  cacheReadTokens: number;
-  cacheWriteTokens: number;
-  turnCount: number;
+/** A builder and the status it builds into: the test writes through `sb` and reads `status`, as production reads `TurnSink.status`. */
+function makeBuilder(): { sb: TranscriptBuilder; status: AgentExecutionStatus } {
+  const status = create(AgentExecutionStatusSchema, {});
+  return { sb: new TranscriptBuilder("exec-test", status), status };
 }
 
-const reportedByBuilder = new WeakMap<V3StatusBuilder, ReportedUsage>();
-
-function makeBuilder(): V3StatusBuilder {
-  const reported: ReportedUsage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, turnCount: 0 };
-  const sb = new V3StatusBuilder("exec-test", create(AgentExecutionStatusSchema, {}), {
-    onUsage: (usage) => {
-      reported.inputTokens += usage.input_tokens ?? 0;
-      reported.outputTokens += usage.output_tokens ?? 0;
-      reported.cacheReadTokens += usage.input_token_details?.cache_read ?? 0;
-      reported.cacheWriteTokens += usage.input_token_details?.cache_creation ?? 0;
-      reported.turnCount += 1;
-    },
-  });
-  reportedByBuilder.set(sb, reported);
-  return sb;
-}
-
-function reportedUsage(sb: V3StatusBuilder): ReportedUsage {
-  return reportedByBuilder.get(sb)!;
-}
-
-function feedAll(sb: V3StatusBuilder, events: V3ProtocolEvent[]): void {
+/**
+ * Feed raw v3 events through the translator (over the given gate posture, or
+ * none) into the builder — the production path, `turn-stream.ts`'s loop.
+ */
+function feedAll(sb: TranscriptBuilder, events: V3ProtocolEvent[], gate: DeepAgentGateState | null = null): void {
+  const translator = new DeepAgentTranslator(gate);
   for (const raw of events) {
-    for (const e of normalize(raw)) {
-      sb.processEvent(e);
+    for (const e of translator.translate(raw)) {
+      sb.apply(e);
     }
   }
 }
 
 beforeEach(() => resetSeq());
 
-describe("V3StatusBuilder", () => {
+describe("the native translator through the builder", () => {
 
   // ── Initialization ───────────────────────────────────────────────
 
   describe("initialization", () => {
-    it("writes neither phase nor startedAt (the turn runtime owns both; S3 M2a, Q-M2a-7)", () => {
-      const sb = makeBuilder();
-      expect(sb.currentStatus.phase).toBe(ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED);
-      expect(sb.currentStatus.startedAt).toBe("");
+    it("writes neither phase nor startedAt (the turn runtime owns both)", () => {
+      const { sb, status } = makeBuilder();
+      expect(status.phase).toBe(ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED);
+      expect(status.startedAt).toBe("");
       expect(sb.awaitingApproval).toBe(false);
     });
 
-    it("starts with forceNextUpdate = false", () => {
-      const sb = makeBuilder();
-      expect(sb.forceNextUpdate).toBe(false);
+    it("starts with dirty = false", () => {
+      const { sb } = makeBuilder();
+      expect(sb.dirty).toBe(false);
     });
   });
 
@@ -90,14 +94,14 @@ describe("V3StatusBuilder", () => {
   // GOLDEN SEQUENCES
   //
   // Same proto assertions as v2 StatusBuilder golden tests, but input
-  // is v3 ProtocolEvent sequences fed through the normalizer.
+  // is v3 ProtocolEvent sequences fed through the translator.
   // ═══════════════════════════════════════════════════════════════════
 
   describe("golden sequences", () => {
 
     describe("plain chat — 2-turn text-only conversation", () => {
-      it("produces 2 AI messages with accumulated usage", () => {
-        const sb = makeBuilder();
+      it("produces 2 AI messages, one per run, each closed by its finish", () => {
+        const { sb, status } = makeBuilder();
         feedAll(sb, [
           makeMessageStart("run-1"),
           makeTextDelta("run-1", "Hello, "),
@@ -114,7 +118,6 @@ describe("V3StatusBuilder", () => {
           }),
         ]);
 
-        const status = sb.currentStatus;
 
         expect(status.messages).toHaveLength(2);
         expect(status.messages[0].type).toBe(MessageType.MESSAGE_AI);
@@ -126,17 +129,13 @@ describe("V3StatusBuilder", () => {
         expect(status.messages[1].content).toBe("Here is more detail.");
         expect(status.messages[1].isStreaming).toBe(false);
 
-        const usage = reportedUsage(sb);
-        expect(usage.inputTokens).toBe(130);
-        expect(usage.outputTokens).toBe(20);
-        expect(usage.turnCount).toBe(2);
-        expect(status.streamingUsage, "the runtime owns streamingUsage; the builder reports").toBeUndefined();
+        expect(status.streamingUsage, "the runtime owns streamingUsage; the builder never touches it").toBeUndefined();
       });
     });
 
     describe("Anthropic thinking + text", () => {
       it("produces THINKING then AI messages with correct turn boundaries", () => {
-        const sb = makeBuilder();
+        const { sb, status } = makeBuilder();
         feedAll(sb, [
           makeMessageStart("run-1"),
           makeReasoningDelta("run-1", "Let me analyze "),
@@ -157,13 +156,14 @@ describe("V3StatusBuilder", () => {
           }),
         ]);
 
-        const status = sb.currentStatus;
 
         expect(status.messages).toHaveLength(3);
 
         expect(status.messages[0].type).toBe(MessageType.MESSAGE_THINKING);
         expect(status.messages[0].content).toBe("Let me analyze this problem carefully.");
-        expect(status.messages[0].isStreaming).toBe(true);
+        // The run's finish closes its thinking with its text (since #1097);
+        // until then the THINKING row spun until finalize.
+        expect(status.messages[0].isStreaming).toBe(false);
 
         expect(status.messages[1].type).toBe(MessageType.MESSAGE_AI);
         expect(status.messages[1].content).toBe("Based on my analysis, here is the answer.");
@@ -172,18 +172,12 @@ describe("V3StatusBuilder", () => {
         expect(status.messages[2].type).toBe(MessageType.MESSAGE_AI);
         expect(status.messages[2].content).toBe("Let me elaborate.");
         expect(status.messages[2].isStreaming).toBe(false);
-
-        const usage = reportedUsage(sb);
-        expect(usage.inputTokens).toBe(500);
-        expect(usage.outputTokens).toBe(120);
-        expect(usage.cacheReadTokens).toBe(50);
-        expect(usage.turnCount).toBe(2);
       });
     });
 
     describe("single tool call — ReAct pattern", () => {
       it("produces AI message with tool call followed by response", () => {
-        const sb = makeBuilder();
+        const { sb, status } = makeBuilder();
         feedAll(sb, [
           makeMessageStart("run-1"),
           makeTextDelta("run-1", "I'll read the file for you."),
@@ -199,7 +193,6 @@ describe("V3StatusBuilder", () => {
           }),
         ]);
 
-        const status = sb.currentStatus;
 
         expect(status.messages).toHaveLength(2);
 
@@ -224,17 +217,12 @@ describe("V3StatusBuilder", () => {
         expect(secondMsg.type).toBe(MessageType.MESSAGE_AI);
         expect(secondMsg.content).toBe("The file contains a main function that logs 'hello'.");
         expect(secondMsg.toolCalls).toHaveLength(0);
-
-        const usage = reportedUsage(sb);
-        expect(usage.inputTokens).toBe(300);
-        expect(usage.outputTokens).toBe(35);
-        expect(usage.turnCount).toBe(2);
       });
     });
 
     describe("tool error — failed tool call", () => {
       it("marks tool as FAILED with error string", () => {
-        const sb = makeBuilder();
+        const { sb, status } = makeBuilder();
         feedAll(sb, [
           makeMessageStart("run-1"),
           makeTextDelta("run-1", "I'll write to the file."),
@@ -250,7 +238,6 @@ describe("V3StatusBuilder", () => {
           }),
         ]);
 
-        const status = sb.currentStatus;
 
         expect(status.messages).toHaveLength(2);
 
@@ -265,7 +252,7 @@ describe("V3StatusBuilder", () => {
 
     describe("multi-tool concurrent", () => {
       it("handles two parallel tools on one message with out-of-order completion", () => {
-        const sb = makeBuilder();
+        const { sb, status } = makeBuilder();
         feedAll(sb, [
           makeMessageStart("run-1"),
           makeTextDelta("run-1", "I'll look up both files."),
@@ -279,7 +266,6 @@ describe("V3StatusBuilder", () => {
           makeToolFinished("toolu_1", "content of a"),
         ]);
 
-        const status = sb.currentStatus;
 
         const msg = status.messages[0];
         expect(msg.toolCalls).toHaveLength(2);
@@ -293,10 +279,16 @@ describe("V3StatusBuilder", () => {
       });
     });
 
-    describe("HITL approval gate", () => {
-      it("sets WAITING_FOR_APPROVAL on tool with approval policy", () => {
-        const sb = makeBuilder();
-        sb.setApprovalProvider({
+    describe("a gated MCP tool that STARTED", () => {
+      // On native a held call never starts: LangGraph's interrupt() runs
+      // before the tool handler, so no tool_started arrives and the gate's
+      // hold reaches the transcript as approval_proposed from the post-stream
+      // seed. A tool_started that does arrive is the engine's word that
+      // the call was authorized, so the row is RUNNING and attributed — never
+      // WAITING at creation, whatever the policy says.
+      it("is RUNNING and attributed to its server; nothing waits", () => {
+        const { sb, status } = makeBuilder();
+        const gate = gateWith({
           policies: new Map([
             ["my-server/dangerous_tool", {
               toolName: "dangerous_tool",
@@ -307,8 +299,7 @@ describe("V3StatusBuilder", () => {
             }],
           ]),
           toolServerMap: new Map([["dangerous_tool", "my-server"]]),
-          globalBypass: false,
-        } as ApprovalPolicyProvider);
+        });
 
         feedAll(sb, [
           makeMessageStart("run-1"),
@@ -318,67 +309,23 @@ describe("V3StatusBuilder", () => {
             usage: { input_tokens: 100, output_tokens: 10 },
           }),
           makeToolStarted("toolu_1", "dangerous_tool", { path: "/etc/shadow" }),
-        ]);
+        ], gate);
 
-        const status = sb.currentStatus;
-        expect(sb.awaitingApproval, "a fact for the caller, never a phase write").toBe(true);
+        expect(sb.awaitingApproval, "no tool_started parks a row").toBe(false);
         expect(status.phase).toBe(ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED);
 
         const tc = status.messages[0].toolCalls[0];
-        expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
-        expect(tc.requiresApproval).toBe(true);
-        expect(tc.approvalMessage).toBe("This tool will modify /etc/shadow");
+        expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+        expect(tc.requiresApproval).toBe(false);
         expect(tc.mcpServerSlug).toBe("my-server");
-        expect(tc.approvalRequestedAt).toBeTruthy();
-        expect(tc.argsPreview).toBeTruthy();
-      });
-    });
-
-    describe("usage accumulation — 3-turn with cache", () => {
-      it("accumulates input/output/cache tokens across turns", () => {
-        const sb = makeBuilder();
-        feedAll(sb, [
-          makeMessageStart("run-1"),
-          makeTextDelta("run-1", "Turn 1"),
-          makeMessageFinish("run-1", {
-            usage: {
-              input_tokens: 100,
-              output_tokens: 20,
-              input_token_details: { cache_creation: 80 },
-            },
-          }),
-          makeMessageStart("run-2"),
-          makeTextDelta("run-2", "Turn 2"),
-          makeMessageFinish("run-2", {
-            usage: {
-              input_tokens: 200,
-              output_tokens: 30,
-              input_token_details: { cache_read: 50 },
-            },
-          }),
-          makeMessageStart("run-3"),
-          makeTextDelta("run-3", "Turn 3"),
-          makeMessageFinish("run-3", {
-            usage: {
-              input_tokens: 300,
-              output_tokens: 10,
-              input_token_details: { cache_read: 100 },
-            },
-          }),
-        ]);
-
-        const usage = reportedUsage(sb);
-        expect(usage.inputTokens).toBe(600);
-        expect(usage.outputTokens).toBe(60);
-        expect(usage.cacheWriteTokens).toBe(80);
-        expect(usage.cacheReadTokens).toBe(150);
-        expect(usage.turnCount).toBe(3);
+        expect(tc.approvalPolicySource, "the policy's layer still attributes the row").toBe(ApprovalPolicySource.CLASSIFIER_DEFAULT);
+        expect(tc.approvalRequestedAt).toBe("");
       });
     });
 
     describe("namespace isolation — parent + subagent", () => {
       it("creates separate message trees per namespace", () => {
-        const sb = makeBuilder();
+        const { sb, status } = makeBuilder();
         const subNs = ["subagent:worker-1"];
 
         feedAll(sb, [
@@ -412,7 +359,6 @@ describe("V3StatusBuilder", () => {
           }),
         ]);
 
-        const status = sb.currentStatus;
 
         expect(status.messages).toHaveLength(4);
 
@@ -432,11 +378,6 @@ describe("V3StatusBuilder", () => {
 
         expect(status.messages[3].type).toBe(MessageType.MESSAGE_AI);
         expect(status.messages[3].content).toBe("The research is complete.");
-
-        const usage = reportedUsage(sb);
-        expect(usage.inputTokens).toBe(650);
-        expect(usage.outputTokens).toBe(50);
-        expect(usage.turnCount).toBe(3);
       });
     });
   });
@@ -445,7 +386,7 @@ describe("V3StatusBuilder", () => {
 
   describe("v3-specific", () => {
     it("keys tool calls by callId, not runId", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       feedAll(sb, [
         makeMessageStart("run-1"),
         makeTextDelta("run-1", "Reading file."),
@@ -454,29 +395,12 @@ describe("V3StatusBuilder", () => {
         makeToolFinished("toolu_abc123", "contents"),
       ]);
 
-      const tc = sb.currentStatus.messages[0].toolCalls[0];
+      const tc = status.messages[0].toolCalls[0];
       expect(tc.id).toBe("toolu_abc123");
     });
 
-    it("does not double-count usage from standalone usage events", () => {
-      const sb = makeBuilder();
-      feedAll(sb, [
-        makeMessageStart("run-1"),
-        makeTextDelta("run-1", "hi"),
-        makeUsageEvent("run-1", { input_tokens: 50, output_tokens: 10 }),
-        makeMessageFinish("run-1", {
-          usage: { input_tokens: 50, output_tokens: 10 },
-        }),
-      ]);
-
-      const usage = reportedUsage(sb);
-      expect(usage.inputTokens).toBe(50);
-      expect(usage.outputTokens).toBe(10);
-      expect(usage.turnCount).toBe(1);
-    });
-
-    it("accumulates tool_call_arg_delta into ToolCall.args", () => {
-      const sb = makeBuilder();
+    it("accumulates tool_arg_delta into ToolCall.args", () => {
+      const { sb, status } = makeBuilder();
       feedAll(sb, [
         makeMessageStart("run-1"),
         makeTextDelta("run-1", "Calling tool."),
@@ -487,12 +411,12 @@ describe("V3StatusBuilder", () => {
         makeToolFinished("toolu_1", "ok"),
       ]);
 
-      const tc = sb.currentStatus.messages[0].toolCalls[0];
+      const tc = status.messages[0].toolCalls[0];
       expect(tc.args).toEqual({ thought: "test" });
     });
 
     it("handles tool_output_delta by accumulating into result", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       feedAll(sb, [
         makeMessageStart("run-1"),
         makeTextDelta("run-1", "Running."),
@@ -503,32 +427,32 @@ describe("V3StatusBuilder", () => {
         makeToolFinished("toolu_1", " final"),
       ]);
 
-      const tc = sb.currentStatus.messages[0].toolCalls[0];
+      const tc = status.messages[0].toolCalls[0];
       expect(tc.result).toBe(" final");
     });
 
-    it("sets forceNextUpdate on tool start and tool finish", () => {
-      const sb = makeBuilder();
+    it("sets dirty on tool start and tool finish", () => {
+      const { sb } = makeBuilder();
 
       feedAll(sb, [
         makeMessageStart("run-1"),
         makeTextDelta("run-1", "x"),
         makeMessageFinish("run-1", { usage: { input_tokens: 1, output_tokens: 1 } }),
       ]);
-      expect(sb.forceNextUpdate).toBe(false);
+      expect(sb.dirty).toBe(false);
 
       feedAll(sb, [makeToolStarted("toolu_1", "read", {})]);
-      expect(sb.forceNextUpdate).toBe(true);
-      sb.clearForceFlag();
+      expect(sb.dirty).toBe(true);
+      sb.markPersisted();
 
       feedAll(sb, [makeToolFinished("toolu_1", "done")]);
-      expect(sb.forceNextUpdate).toBe(true);
+      expect(sb.dirty).toBe(true);
     });
 
     it("ignores tool-finished for unknown callId", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       feedAll(sb, [makeToolFinished("unknown_toolu", "some result")]);
-      expect(sb.currentStatus.messages).toHaveLength(0);
+      expect(status.messages).toHaveLength(0);
     });
   });
 
@@ -539,7 +463,7 @@ describe("V3StatusBuilder", () => {
 
   describe("todo extraction", () => {
     it("projects a completed write_todos into status.todos", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       feedAll(sb, [
         makeMessageStart("run-1"),
         makeTextDelta("run-1", "Planning the build."),
@@ -553,17 +477,17 @@ describe("V3StatusBuilder", () => {
         makeToolFinished("todo-1", "Todos updated"),
       ]);
 
-      const todos = sb.currentStatus.todos;
+      const todos = status.todos;
       expect(Object.keys(todos)).toEqual(["todo-0", "todo-1"]);
       expect(todos["todo-0"].content).toBe("Step one");
       expect(todos["todo-0"].status).toBe(TodoStatus.TODO_IN_PROGRESS);
       expect(todos["todo-1"].content).toBe("Step two");
       expect(todos["todo-1"].status).toBe(TodoStatus.TODO_PENDING);
-      expect(sb.forceNextUpdate).toBe(true);
+      expect(sb.dirty).toBe(true);
     });
 
     it("keeps the write_todos ToolCall in messages stamped ToolKind.TODO", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       feedAll(sb, [
         makeToolStarted("todo-1", "write_todos", {
           todos: [{ content: "Step one", status: "pending" }],
@@ -571,28 +495,28 @@ describe("V3StatusBuilder", () => {
         makeToolFinished("todo-1", "Todos updated"),
       ]);
 
-      const toolCalls = sb.currentStatus.messages.flatMap((m) => m.toolCalls);
+      const toolCalls = status.messages.flatMap((m) => m.toolCalls);
       const tc = toolCalls.find((t) => t.name === "write_todos");
       expect(tc).toBeDefined();
       expect(tc!.toolKind).toBe(ToolKind.TODO);
     });
 
     it("does not project until the call completes", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       feedAll(sb, [
         makeToolStarted("todo-1", "write_todos", {
           todos: [{ content: "Step one", status: "pending" }],
         }),
       ]);
       // Tool started but not finished — the state Command has not run yet.
-      expect(Object.keys(sb.currentStatus.todos)).toHaveLength(0);
+      expect(Object.keys(status.todos)).toHaveLength(0);
 
       feedAll(sb, [makeToolFinished("todo-1", "Todos updated")]);
-      expect(Object.keys(sb.currentStatus.todos)).toHaveLength(1);
+      expect(Object.keys(status.todos)).toHaveLength(1);
     });
 
     it("full-replaces the map on a subsequent write_todos", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       feedAll(sb, [
         makeToolStarted("todo-1", "write_todos", {
           todos: [
@@ -607,37 +531,33 @@ describe("V3StatusBuilder", () => {
         makeToolFinished("todo-2", "ok"),
       ]);
 
-      const todos = sb.currentStatus.todos;
+      const todos = status.todos;
       expect(Object.keys(todos)).toEqual(["todo-0"]);
       expect(todos["todo-0"].content).toBe("Step two");
       expect(todos["todo-0"].status).toBe(TodoStatus.TODO_COMPLETED);
     });
 
-    it("reports a sub-agent's usage through the same hook as the parent's (S3 M2b, Q-M2b-1)", () => {
-      const sb = makeBuilder();
+    it("routes a sub-agent's message to its own row, never the parent's", () => {
+      const { sb, status } = makeBuilder();
       const subNs = ["tools:task-1", "model_request:sub-run"];
       feedAll(sb, [
-        ...[makeMessageStart("parent-1"), makeTextDelta("parent-1", "Delegating."), makeMessageFinish("parent-1", { usage: { input_tokens: 1_000, output_tokens: 10 } })],
+        ...[makeMessageStart("parent-1"), makeTextDelta("parent-1", "Delegating."), makeMessageFinish("parent-1")],
         makeToolStarted("task-1", "task", { subagent_type: "worker", description: "delegate" }),
         makeMessageStart("sub-run", { namespace: subNs }),
         makeTextDelta("sub-run", "Working on it.", { namespace: subNs }),
-        makeMessageFinish("sub-run", { namespace: subNs, usage: { input_tokens: 600, output_tokens: 12 } }),
+        makeMessageFinish("sub-run", { namespace: subNs }),
       ]);
 
-      const usage = reportedUsage(sb);
-      expect(usage.inputTokens, "the parent's 1,000 and the sub-agent's 600").toBe(1_600);
-      expect(usage.outputTokens).toBe(22);
-      expect(usage.turnCount).toBe(2);
-      // The transcript still routes the sub-agent's message to its own row, never the parent's.
-      expect(sb.currentStatus.messages.map((m) => m.content)).toEqual(["Delegating."]);
-      expect(sb.currentStatus.subAgentExecutions).toHaveLength(1);
+      expect(status.messages.map((m) => m.content)).toEqual(["Delegating."]);
+      expect(status.subAgentExecutions).toHaveLength(1);
+      expect(status.subAgentExecutions[0].messages.map((m) => m.content)).toEqual(["Working on it."]);
     });
 
     it("does not project a sub-agent's write_todos into parent status.todos", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       const subNs = ["tools:task-1", "tools:sub-todo"];
       feedAll(sb, [
-        // Register a sub-agent so its namespace routes to the SubAgentTracker.
+        // Open a sub-agent so its namespace routes to the sub-agent's own transcript scope.
         makeToolStarted("task-1", "task", {
           subagent_type: "worker",
           description: "delegate",
@@ -652,20 +572,29 @@ describe("V3StatusBuilder", () => {
         makeToolFinished("sub-todo", "ok", { namespace: subNs }),
       ]);
 
-      expect(Object.keys(sb.currentStatus.todos)).toHaveLength(0);
+      expect(Object.keys(status.todos)).toHaveLength(0);
     });
   });
   // ═══════════════════════════════════════════════════════════════════
   // Carried from the v2 StatusBuilder's suite when that builder retired
-  // with the v2 stream (S3 M2b, Q-S3-1 / Q-M2b-5): every rule below is the
+  // with the v2 stream (#1096): every rule below is the
   // builder's own — how a policy decides a row's status, what the row
   // carries, how a seeded row is resolved, how artifacts and write-backs
   // are upserted — and had no v3 twin. The sanitizer's own rules
   // (redaction, truncation) are `shared/__tests__/args-preview.test.ts`'s.
   // ═══════════════════════════════════════════════════════════════════
 
-  function providerWith(overrides: Partial<ApprovalPolicyProvider> = {}): ApprovalPolicyProvider {
-    return { policies: new Map(), toolServerMap: new Map(), globalBypass: false, ...overrides };
+  /** A gate posture for the translator: no policies, no leases, attended, not bypassed — unless overridden. */
+  function gateWith(overrides: Partial<DeepAgentGateState> = {}): DeepAgentGateState {
+    return {
+      policies: new Map(),
+      toolServerMap: new Map(),
+      leasedCategories: new Set(),
+      globalBypass: false,
+      unattended: false,
+      unattendedSkips: new Set(),
+      ...overrides,
+    };
   }
 
   function policyFor(serverSlug: string, toolName: string, message = "Approve?"): [string, MergedToolPolicy] {
@@ -675,119 +604,104 @@ describe("V3StatusBuilder", () => {
     ];
   }
 
-  /** A text turn, then one tool start, on a builder with the given provider. */
-  function firstToolCallUnder(provider: ApprovalPolicyProvider, toolName: string, input: Record<string, unknown> = {}) {
-    const sb = makeBuilder();
-    sb.setApprovalProvider(provider);
+  /** A text turn, then one tool start, through a translator over the given gate posture. */
+  function firstToolCallUnder(gate: DeepAgentGateState, toolName: string, input: Record<string, unknown> = {}) {
+    const { sb, status } = makeBuilder();
     feedAll(sb, [
       makeMessageStart("run-1"),
       makeTextDelta("run-1", "Working."),
       makeMessageFinish("run-1", { usage: { input_tokens: 10, output_tokens: 5 } }),
       makeToolStarted("toolu_1", toolName, input),
-    ]);
-    return { sb, tc: sb.currentStatus.messages[0].toolCalls[0] };
+    ], gate);
+    return { sb, tc: status.messages[0].toolCalls[0] };
   }
 
-  describe("approval provider: what decides a row's status", () => {
-    it("a policy that requires approval leaves the row WAITING_APPROVAL with its message and server", () => {
+  describe("attribution and provenance on tool_started", () => {
+    // The translator answers WHICH server a tool belongs to and WHICH policy
+    // layer governs it; it never answers whether the gate holds the call —
+    // on native a held call never starts (the interrupt precedes the
+    // handler), so every started call is RUNNING and nothing here waits.
+    // The decision itself, `resolveToolApproval`, has its own arms in
+    // `shared/__tests__/approval-policy.test.ts`; the gate's use of it in
+    // `middleware/__tests__/approval-gate.test.ts`.
+
+    it("an MCP tool with a gating policy STILL runs when it started, attributed to its server and the policy's layer", () => {
       const [key, policy] = policyFor("github", "create_issue");
       const { sb, tc } = firstToolCallUnder(
-        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["create_issue", "github"]]) }),
+        gateWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["create_issue", "github"]]) }),
         "create_issue",
         { title: "Bug fix" },
       );
-      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
-      expect(tc.requiresApproval).toBe(true);
-      expect(tc.approvalMessage).toBe("Approve?");
-      expect(tc.mcpServerSlug).toBe("github");
-      expect(tc.approvalRequestedAt, "stamped when approval is required").toContain("T");
-      expect(sb.awaitingApproval).toBe(true);
-    });
-
-    it("the global bypass (spec.auto_approve_all) runs a gated tool without approval", () => {
-      const [key, policy] = policyFor("github", "delete_repo");
-      const { sb, tc } = firstToolCallUnder(
-        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["delete_repo", "github"]]), globalBypass: true }),
-        "delete_repo",
-      );
       expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
       expect(tc.requiresApproval).toBe(false);
+      expect(tc.mcpServerSlug).toBe("github");
+      expect(tc.approvalPolicySource).toBe(ApprovalPolicySource.CLASSIFIER_DEFAULT);
+      expect(tc.policyEngineVersion).toBe("phase-7");
       expect(sb.awaitingApproval).toBe(false);
     });
 
-    it("the global bypass still attributes the row to its MCP server", () => {
+    it("the global bypass (spec.auto_approve_all) attributes every row to it", () => {
+      const [key, policy] = policyFor("github", "delete_repo");
       const { tc } = firstToolCallUnder(
-        providerWith({ toolServerMap: new Map([["echo", "test-mcp-server"]]), globalBypass: true }),
-        "echo",
-        { input: "hello" },
+        gateWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["delete_repo", "github"]]), globalBypass: true }),
+        "delete_repo",
       );
       expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
-      expect(tc.mcpServerSlug).toBe("test-mcp-server");
+      expect(tc.mcpServerSlug, "the bypass still attributes the row to its MCP server").toBe("github");
+      expect(tc.approvalPolicySource).toBe(ApprovalPolicySource.AUTO_APPROVE_ALL);
     });
 
-    it("a tool with no policy runs, attributed to its server", () => {
-      const { tc } = firstToolCallUnder(providerWith({ toolServerMap: new Map([["read", "filesystem"]]) }), "read");
-      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+    it("an MCP tool with no policy is attributed to its server, classifier_default", () => {
+      const { tc } = firstToolCallUnder(gateWith({ toolServerMap: new Map([["read", "filesystem"]]) }), "read");
       expect(tc.mcpServerSlug).toBe("filesystem");
+      expect(tc.approvalPolicySource).toBe(ApprovalPolicySource.CLASSIFIER_DEFAULT);
     });
 
-    it("a policy whose tool is not in the server map does not gate (the policy key needs the server)", () => {
+    it("a tool the server map does not know carries no server (the policy key needs the server)", () => {
       const [key, policy] = policyFor("github", "create_pr");
-      const { tc } = firstToolCallUnder(providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map() }), "create_pr");
-      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+      const { tc } = firstToolCallUnder(gateWith({ policies: new Map([[key, policy]]), toolServerMap: new Map() }), "create_pr");
+      expect(tc.mcpServerSlug).toBe("");
+      expect(tc.approvalPolicySource, "an unknown built-in is governed by no layer").toBe(ApprovalPolicySource.UNSPECIFIED);
+      expect(tc.policyEngineVersion).toBe("");
     });
 
-    it("resolves {{args.field}} placeholders in the approval message", () => {
-      const [key, policy] = policyFor("github", "create_issue", "Create issue '{{args.title}}' in {{args.repo}}?");
-      const { tc } = firstToolCallUnder(
-        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["create_issue", "github"]]) }),
-        "create_issue",
-        { title: "Fix crash", repo: "stigmer/stigmer" },
-      );
-      expect(tc.approvalMessage).toBe("Create issue 'Fix crash' in stigmer/stigmer?");
+    it("a mutating built-in that started is attributed builtin_category — the gate let it flow (capture mode, or a resume)", () => {
+      const { sb, tc } = firstToolCallUnder(gateWith(), "execute", { command: "rm -rf build" });
+      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+      expect(tc.approvalPolicySource).toBe(ApprovalPolicySource.BUILTIN_CATEGORY);
+      expect(sb.awaitingApproval).toBe(false);
     });
-  });
 
-  describe("args preview: when the builder writes one", () => {
-    it("a gated row carries a sanitized preview; an ungated row carries none", () => {
-      const [key, policy] = policyFor("db", "connect");
-      const gated = firstToolCallUnder(
-        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["connect", "db"]]) }),
-        "connect",
-        { host: "localhost", password: "super-secret" },
-      );
-      const preview = JSON.parse(gated.tc.argsPreview) as Record<string, string>;
-      expect(preview.host).toBe("localhost");
-      expect(preview.password, "the shared sanitizer redacts secret keys").toBe("[REDACTED]");
+    it("a leased built-in category is attributed to its lease", () => {
+      const { tc } = firstToolCallUnder(gateWith({ leasedCategories: new Set(["shell"]) }), "execute", { command: "ls" });
+      expect(tc.approvalPolicySource).toBe(ApprovalPolicySource.APPROVAL_LEASE);
+    });
 
-      const ungated = firstToolCallUnder(providerWith(), "read", { path: "/foo" });
-      expect(ungated.tc.argsPreview).toBe("");
+    it("a read-only built-in is governed by no layer: UNSPECIFIED, no engine version", () => {
+      const { tc } = firstToolCallUnder(gateWith(), "read_file", { path: "/x" });
+      expect(tc.approvalPolicySource).toBe(ApprovalPolicySource.UNSPECIFIED);
+      expect(tc.policyEngineVersion).toBe("");
     });
 
-    it("an unserializable input leaves the preview empty instead of failing the row", () => {
-      const [key, policy] = policyFor("api", "call");
-      const circular: Record<string, unknown> = {};
-      circular.self = circular;
-      const { tc } = firstToolCallUnder(
-        providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["call", "api"]]) }),
-        "call",
-        circular,
-      );
-      expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
-      expect(tc.argsPreview).toBe("");
+    it("with no gate posture at all (a turn the unit arms drive bare) nothing is attributed", () => {
+      const { sb, status } = makeBuilder();
+      feedAll(sb, [makeToolStarted("toolu_1", "execute", { command: "ls" })]);
+      const tc = status.messages[0].toolCalls[0];
+      expect(tc.mcpServerSlug).toBe("");
+      expect(tc.approvalPolicySource).toBe(ApprovalPolicySource.UNSPECIFIED);
     });
   });
 
   describe("tool rows without a preceding text turn, and interleaving", () => {
     it("a tool start with no prior text creates the AI message that carries it", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       feedAll(sb, [makeToolStarted("orphan", "read", {})]);
-      expect(sb.currentStatus.messages).toHaveLength(1);
-      expect(sb.currentStatus.messages[0].toolCalls[0].name).toBe("read");
+      expect(status.messages).toHaveLength(1);
+      expect(status.messages[0].toolCalls[0].name).toBe("read");
     });
 
     it("interleaved start/finish pairs settle each row independently", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       feedAll(sb, [
         makeMessageStart("run-1"),
         makeTextDelta("run-1", "working"),
@@ -797,29 +711,29 @@ describe("V3StatusBuilder", () => {
         makeToolStarted("toolu_b", "write", {}),
         makeToolFinished("toolu_b", "done"),
       ]);
-      const rows = sb.currentStatus.messages.flatMap((m) => m.toolCalls);
+      const rows = status.messages.flatMap((m) => m.toolCalls);
       expect(rows.map((r) => r.status)).toEqual([ToolCallStatus.TOOL_CALL_COMPLETED, ToolCallStatus.TOOL_CALL_COMPLETED]);
     });
   });
 
   describe("a handler that throws", () => {
-    it("is logged with the execution, the event kind and its seq, and never escapes processEvent", () => {
-      const sb = makeBuilder();
+    it("is logged with the execution and the event kind, and never escapes apply", () => {
+      const { sb } = makeBuilder();
       const errors: string[] = [];
       const original = console.error;
       console.error = (msg: unknown) => { errors.push(String(msg)); };
       try {
-        const poisoned = normalize(makeToolFinished("toolu_x", "ok"))[0]!;
-        // A getter that throws where the handler reads the output.
-        const event = { ...poisoned, get output(): unknown { throw new Error("property access failed"); } };
-        expect(() => sb.processEvent(event as typeof poisoned)).not.toThrow();
+        const poisoned = new DeepAgentTranslator(null).translate(makeToolFinished("toolu_x", "ok"))[0]!;
+        // A getter that throws where the handler reads the result.
+        const event = { ...poisoned, get result(): string { throw new Error("property access failed"); } };
+        expect(() => sb.apply(event as typeof poisoned)).not.toThrow();
       } finally {
         console.error = original;
       }
       expect(errors).toHaveLength(1);
       expect(errors[0]).toContain("exec-test");
       expect(errors[0]).toContain("kind=tool_finished");
-      expect(errors[0]).toMatch(/seq=\d+/);
+      expect(errors[0]).toContain("property access failed");
     });
   });
 
@@ -846,9 +760,9 @@ describe("V3StatusBuilder", () => {
           }),
         ],
       });
-      const sb = new V3StatusBuilder("exec-resume", status);
+      const sb = new TranscriptBuilder("exec-resume", status);
       const [key, policy] = policyFor("my-server", "dangerous_tool", "Execute dangerous_tool");
-      sb.setApprovalProvider(providerWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["dangerous_tool", "my-server"]]) }));
+      const gate = gateWith({ policies: new Map([[key, policy]]), toolServerMap: new Map([["dangerous_tool", "my-server"]]) });
 
       // The durable checkpoint re-emits the SAME tool_call_id now that approval is granted.
       feedAll(sb, [
@@ -857,60 +771,60 @@ describe("V3StatusBuilder", () => {
         makeMessageStart("llm-after"),
         makeTextDelta("llm-after", "All done."),
         makeMessageFinish("llm-after", { usage: { input_tokens: 1, output_tokens: 1 } }),
-      ]);
+      ], gate);
 
-      const gated = sb.currentStatus.messages.flatMap((m) => m.toolCalls).filter((tc) => tc.id === GATED_ID);
+      const gated = status.messages.flatMap((m) => m.toolCalls).filter((tc) => tc.id === GATED_ID);
       expect(gated).toHaveLength(1);
       expect(gated[0].status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
       expect(gated[0].result).toContain("tool executed ok");
       expect(gated[0].args, "the resumed start fills the args the seed lacked").toEqual({ target: "prod" });
-      const allText = sb.currentStatus.messages.map((m) => m.content).join("\n");
+      const allText = status.messages.map((m) => m.content).join("\n");
       expect(allText).toContain("I'll call the gated tool.");
       expect(allText).toContain("All done.");
       expect(sb.awaitingApproval, "a resumed tool never re-gates").toBe(false);
     });
   });
 
-  describe("artifacts and write-backs (the ExecutionStatusWriter face)", () => {
+  describe("artifacts and write-backs", () => {
     const artifact = (sandboxPath: string, contentHash: string) =>
       create(ExecutionArtifactSchema, { sandboxPath, contentHash, storageKey: `k/${contentHash}` });
 
     it("appends a new artifact and forces the next persist", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       sb.addArtifact(artifact("out/a.txt", "h1"));
-      expect(sb.currentStatus.artifacts).toHaveLength(1);
-      expect(sb.forceNextUpdate).toBe(true);
+      expect(status.artifacts).toHaveLength(1);
+      expect(sb.dirty).toBe(true);
     });
 
     it("deduplicates by sandboxPath: the same contentHash is a no-op that does not force a persist", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       sb.addArtifact(artifact("out/a.txt", "h1"));
-      sb.clearForceFlag();
+      sb.markPersisted();
       sb.addArtifact(artifact("out/a.txt", "h1"));
-      expect(sb.currentStatus.artifacts).toHaveLength(1);
-      expect(sb.forceNextUpdate).toBe(false);
+      expect(status.artifacts).toHaveLength(1);
+      expect(sb.dirty).toBe(false);
     });
 
     it("replaces the artifact in place when its contentHash changes", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       sb.addArtifact(artifact("out/a.txt", "h1"));
-      sb.clearForceFlag();
+      sb.markPersisted();
       sb.addArtifact(artifact("out/a.txt", "h2"));
-      expect(sb.currentStatus.artifacts).toHaveLength(1);
-      expect(sb.currentStatus.artifacts[0].contentHash).toBe("h2");
-      expect(sb.forceNextUpdate).toBe(true);
+      expect(status.artifacts).toHaveLength(1);
+      expect(status.artifacts[0].contentHash).toBe("h2");
+      expect(sb.dirty).toBe(true);
     });
 
     it("upserts write-backs by workspaceEntryName, tracking entries independently", () => {
-      const sb = makeBuilder();
+      const { sb, status } = makeBuilder();
       sb.addWriteBack(create(WorkspaceWriteBackSchema, { workspaceEntryName: "repo-a", branchName: "stigmer/s1" }));
       sb.addWriteBack(create(WorkspaceWriteBackSchema, { workspaceEntryName: "repo-b", branchName: "stigmer/s1" }));
-      sb.clearForceFlag();
+      sb.markPersisted();
       sb.addWriteBack(create(WorkspaceWriteBackSchema, { workspaceEntryName: "repo-a", branchName: "stigmer/s1", pullRequestUrl: "https://example/pr/1" }));
-      const backs = sb.currentStatus.workspaceWriteBacks;
+      const backs = status.workspaceWriteBacks;
       expect(backs.map((b) => b.workspaceEntryName)).toEqual(["repo-a", "repo-b"]);
       expect(backs[0].pullRequestUrl).toBe("https://example/pr/1");
-      expect(sb.forceNextUpdate).toBe(true);
+      expect(sb.dirty).toBe(true);
     });
   });
 });