@stigmer/runner 3.1.3 → 3.1.4

package/src/activities/execute-deep-agent/__tests__/command-provenance.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Unit tests for the DEEP-AGENT approved-command provenance adapter (DD-28).
+ *
+ * These pin the two things that differ from the Cursor harness: identity turn
+ * scoping (a call whose id is absent from the pre-stream settled snapshot is
+ * this-turn's) and same-row consent (the executed shell row carries its own
+ * server-authored approval_action). The two regressions the plan calls out are
+ * asserted explicitly: a seeded WAITING_APPROVAL -> COMPLETED approved shell IS
+ * counted, and a prior turn's settled call is NOT re-evaluated. The DD-28 rule
+ * itself is covered by shared/filereview/__tests__/command-provenance.test.ts.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create, type MessageInitShape } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import {
+  ApprovalAction,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { deriveTurnCommandProvenance } from "../command-provenance.js";
+
+function toolCall(overrides: MessageInitShape<typeof ToolCallSchema>): ToolCall {
+  return create(ToolCallSchema, {
+    id: "call-1",
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    ...overrides,
+  });
+}
+
+function aiMessage(toolCalls: ToolCall[]): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls });
+}
+
+/** A COMPLETED shell row (the deep-agent shell tool is `execute`). */
+function executedShell(id: string, overrides: MessageInitShape<typeof ToolCallSchema> = {}): ToolCall {
+  return toolCall({ id, name: "execute", args: { command: "seq 1 5 > out.txt" }, ...overrides });
+}
+
+function status(messages: AgentMessage[], subAgents: MessageInitShape<typeof SubAgentExecutionSchema>[] = []) {
+  return create(AgentExecutionStatusSchema, {
+    messages,
+    subAgentExecutions: subAgents.map((sa) => create(SubAgentExecutionSchema, sa)),
+  });
+}
+
+const NO_SETTLED = new Set<string>();
+const NO_SUBAGENTS = new Set<string>();
+
+describe("deep-agent deriveTurnCommandProvenance", () => {
+  it("cites the executed shell's OWN id for a per-command approval (same-row consent)", () => {
+    const shell = executedShell("execute-1", { approvalAction: ApprovalAction.APPROVE });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([shell])]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["execute-1"]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(false);
+  });
+
+  it("cites the executed shell's own id for an APPROVE_ALL on the same row", () => {
+    const shell = executedShell("execute-1", { approvalAction: ApprovalAction.APPROVE_ALL });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([shell])]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    expect(provenance!.consentToolCallIds).toEqual(["execute-1"]);
+  });
+
+  it("cites a prior APPROVE_ALL lease row for a command that ran ungated under the lease", () => {
+    // Prior turn: a gated command the user approved-all (settled before this turn).
+    const leaseRow = executedShell("lease-row", {
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      approvalAction: ApprovalAction.APPROVE_ALL,
+    });
+    // This turn: a fresh command runs ungated under the lease — no approval_action.
+    const leased = executedShell("execute-leased");
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([leaseRow]), aiMessage([leased])]),
+      priorSettledToolCallIds: new Set(["lease-row"]), // the lease row is a prior-turn settled call
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["lease-row"]);
+  });
+
+  it("flags auto_approve_all for an ungated command under the global bypass", () => {
+    const shell = executedShell("execute-1"); // no approval_action, no lease
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([shell])]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: true,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual([]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(true);
+  });
+
+  it("fails closed on a file-tool call this turn (even under auto_approve_all)", () => {
+    const shell = executedShell("execute-1", { approvalAction: ApprovalAction.APPROVE });
+    const write = toolCall({ id: "write-1", name: "write_file", args: { path: "a.txt" } });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([shell, write])]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: true,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on an MCP tool this turn", () => {
+    const shell = executedShell("execute-1", { approvalAction: ApprovalAction.APPROVE });
+    const mcp = toolCall({ id: "mcp-1", name: "apply_resource", mcpServerSlug: "planton" });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([shell, mcp])]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on an unrecognized tool name this turn", () => {
+    const shell = executedShell("execute-1", { approvalAction: ApprovalAction.APPROVE });
+    const unknown = toolCall({ id: "u-1", name: "mystery_tool" });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([shell, unknown])]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed on a top-level sub-agent delegation (task row this turn)", () => {
+    const shell = executedShell("execute-1", { approvalAction: ApprovalAction.APPROVE });
+    const task = toolCall({ id: "task-1", name: "task", args: { prompt: "go" } });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([shell, task])]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("fails closed when a sub-agent produced NEW tool-call rows this turn", () => {
+    const shell = executedShell("execute-1", { approvalAction: ApprovalAction.APPROVE });
+    const subAgentShell = executedShell("sub-execute-1", { approvalAction: ApprovalAction.APPROVE });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([shell])], [
+        { name: "worker", messages: [aiMessage([subAgentShell])] },
+      ]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: NO_SUBAGENTS, // the sub-agent row is new this turn
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  it("does NOT fail closed for a sub-agent whose rows all pre-existed this turn", () => {
+    const shell = executedShell("execute-1", { approvalAction: ApprovalAction.APPROVE });
+    const priorSubShell = executedShell("sub-prior-1", { approvalAction: ApprovalAction.APPROVE });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([shell])], [
+        { name: "worker", messages: [aiMessage([priorSubShell])] },
+      ]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: new Set(["sub-prior-1"]), // seeded from a prior turn
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["execute-1"]);
+  });
+
+  it("returns undefined when no command executed this turn", () => {
+    const pending = executedShell("execute-pending", {
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+    });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([pending])]),
+      priorSettledToolCallIds: NO_SETTLED,
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    expect(provenance).toBeUndefined();
+  });
+
+  // ── Regression: identity scoping (the reason positional scoping can't port) ──
+
+  it("REGRESSION counts a seeded WAITING_APPROVAL -> COMPLETED approved shell (its id was not settled pre-stream)", () => {
+    // The shell was proposed + approved in a prior segment (WAITING_APPROVAL, so
+    // NOT in the pre-stream settled snapshot) and executes in place this segment.
+    const executedThisTurn = executedShell("execute-approved", {
+      approvalAction: ApprovalAction.APPROVE,
+    });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([executedThisTurn])]),
+      priorSettledToolCallIds: NO_SETTLED, // it was WAITING, not settled, before the stream
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["execute-approved"]);
+  });
+
+  it("REGRESSION does NOT re-count a prior turn's already-settled shell", () => {
+    const priorShell = executedShell("execute-prior", { approvalAction: ApprovalAction.APPROVE });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([priorShell])]),
+      priorSettledToolCallIds: new Set(["execute-prior"]), // settled in a prior turn
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    // Nothing executed THIS turn -> nothing to attribute the change set to.
+    expect(provenance).toBeUndefined();
+  });
+
+  it("REGRESSION a prior turn's settled non-shell call never disqualifies this turn", () => {
+    // A prior FAILED edit must be excluded by the settled snapshot — otherwise it
+    // would trip the !== SHELL fail-closed on a clean shell-only turn.
+    const priorEdit = toolCall({
+      id: "edit-prior",
+      name: "edit_file",
+      status: ToolCallStatus.TOOL_CALL_FAILED,
+      args: { path: "a.txt" },
+    });
+    const shellThisTurn = executedShell("execute-1", { approvalAction: ApprovalAction.APPROVE });
+    const provenance = deriveTurnCommandProvenance({
+      status: status([aiMessage([priorEdit]), aiMessage([shellThisTurn])]),
+      priorSettledToolCallIds: new Set(["edit-prior"]),
+      priorSubAgentToolCallIds: NO_SUBAGENTS,
+      globalBypass: false,
+    });
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["execute-1"]);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/status-builder.test.ts

@@ -10,6 +10,8 @@ import {
   ExecutionPhase,
   MessageType,
   ToolCallStatus,
+  ToolKind,
+  TodoStatus,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { StatusBuilder, type StreamEvent, type ApprovalPolicyProvider } from "../status-builder.js";
 import type { MergedToolPolicy } from "../../../shared/approval-policy.js";
@@ -1852,4 +1854,80 @@ describe("StatusBuilder", () => {
       expect(status.phase).not.toBe(ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL);
     });
   });
+
+  // ── Todo extraction (write_todos → status.todos) ─────────────────
+  //
+  // v2 parity with V3StatusBuilder: a completed write_todos projects into
+  // status.todos through the same shared mapper; a failed one does not.
+
+  describe("todo extraction", () => {
+    it("projects a completed write_todos into status.todos", () => {
+      const sb = makeBuilder();
+      sb.processEvent(
+        toolStartEvent("run-1", "write_todos", {
+          todos: [
+            { content: "Step one", status: "in_progress" },
+            { content: "Step two", status: "pending" },
+          ],
+        }),
+      );
+      sb.processEvent(toolEndEvent("run-1", "Todos updated"));
+
+      const todos = sb.currentStatus.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"].status).toBe(TodoStatus.TODO_PENDING);
+    });
+
+    it("keeps the write_todos ToolCall in messages stamped ToolKind.TODO", () => {
+      const sb = makeBuilder();
+      sb.processEvent(
+        toolStartEvent("run-1", "write_todos", {
+          todos: [{ content: "A", status: "pending" }],
+        }),
+      );
+      sb.processEvent(toolEndEvent("run-1", "ok"));
+
+      const tc = sb.currentStatus.messages
+        .flatMap((m) => m.toolCalls)
+        .find((t) => t.name === "write_todos");
+      expect(tc).toBeDefined();
+      expect(tc!.toolKind).toBe(ToolKind.TODO);
+    });
+
+    it("does not project on a failed write_todos (Command never ran)", () => {
+      const sb = makeBuilder();
+      sb.processEvent(
+        toolStartEvent("run-1", "write_todos", {
+          todos: [{ content: "A", status: "pending" }],
+        }),
+      );
+      sb.processEvent(toolEndEvent("run-1", { error: "boom" }));
+      expect(Object.keys(sb.currentStatus.todos)).toHaveLength(0);
+    });
+
+    it("full-replaces the map on a subsequent write_todos", () => {
+      const sb = makeBuilder();
+      sb.processEvent(
+        toolStartEvent("run-1", "write_todos", {
+          todos: [
+            { content: "one", status: "completed" },
+            { content: "two", status: "in_progress" },
+          ],
+        }),
+      );
+      sb.processEvent(toolEndEvent("run-1", "ok"));
+      sb.processEvent(
+        toolStartEvent("run-2", "write_todos", {
+          todos: [{ content: "two", status: "completed" }],
+        }),
+      );
+      sb.processEvent(toolEndEvent("run-2", "ok"));
+
+      const todos = sb.currentStatus.todos;
+      expect(Object.keys(todos)).toEqual(["todo-0"]);
+      expect(todos["todo-0"].status).toBe(TodoStatus.TODO_COMPLETED);
+    });
+  });
 });

package/src/activities/execute-deep-agent/__tests__/v3-status-builder.test.ts

@@ -1,7 +1,7 @@
 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 { ExecutionPhase, MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ExecutionPhase, MessageType, ToolCallStatus, ToolKind, TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { V3StatusBuilder } from "../v3-status-builder.js";
 import { normalize } from "../v3-protocol-normalizer.js";
 import type { ApprovalPolicyProvider } from "../status-builder.js";
@@ -504,4 +504,108 @@ describe("V3StatusBuilder", () => {
       expect(sb.currentStatus.messages).toHaveLength(0);
     });
   });
+
+  // ── Todo extraction (write_todos → status.todos) ─────────────────
+  //
+  // The native harness emits write_todos; projecting it into status.todos is
+  // what lights up the client TodoCard at parity with the Cursor harness.
+
+  describe("todo extraction", () => {
+    it("projects a completed write_todos into status.todos", () => {
+      const sb = makeBuilder();
+      feedAll(sb, [
+        makeMessageStart("run-1"),
+        makeTextDelta("run-1", "Planning the build."),
+        makeMessageFinish("run-1", { usage: { input_tokens: 10, output_tokens: 5 } }),
+        makeToolStarted("todo-1", "write_todos", {
+          todos: [
+            { content: "Step one", status: "in_progress" },
+            { content: "Step two", status: "pending" },
+          ],
+        }),
+        makeToolFinished("todo-1", "Todos updated"),
+      ]);
+
+      const todos = sb.currentStatus.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);
+    });
+
+    it("keeps the write_todos ToolCall in messages stamped ToolKind.TODO", () => {
+      const sb = makeBuilder();
+      feedAll(sb, [
+        makeToolStarted("todo-1", "write_todos", {
+          todos: [{ content: "Step one", status: "pending" }],
+        }),
+        makeToolFinished("todo-1", "Todos updated"),
+      ]);
+
+      const toolCalls = sb.currentStatus.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();
+      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);
+
+      feedAll(sb, [makeToolFinished("todo-1", "Todos updated")]);
+      expect(Object.keys(sb.currentStatus.todos)).toHaveLength(1);
+    });
+
+    it("full-replaces the map on a subsequent write_todos", () => {
+      const sb = makeBuilder();
+      feedAll(sb, [
+        makeToolStarted("todo-1", "write_todos", {
+          todos: [
+            { content: "Step one", status: "completed" },
+            { content: "Step two", status: "in_progress" },
+          ],
+        }),
+        makeToolFinished("todo-1", "ok"),
+        makeToolStarted("todo-2", "write_todos", {
+          todos: [{ content: "Step two", status: "completed" }],
+        }),
+        makeToolFinished("todo-2", "ok"),
+      ]);
+
+      const todos = sb.currentStatus.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("does not project a sub-agent's write_todos into parent status.todos", () => {
+      const sb = makeBuilder();
+      const subNs = ["tools:task-1", "tools:sub-todo"];
+      feedAll(sb, [
+        // Register a sub-agent so its namespace routes to the SubAgentTracker.
+        makeToolStarted("task-1", "task", {
+          subagent_type: "worker",
+          description: "delegate",
+        }),
+        // The sub-agent writes todos — must not leak into the parent map.
+        makeToolStarted(
+          "sub-todo",
+          "write_todos",
+          { todos: [{ content: "sub step", status: "pending" }] },
+          { namespace: subNs },
+        ),
+        makeToolFinished("sub-todo", "ok", { namespace: subNs }),
+      ]);
+
+      expect(Object.keys(sb.currentStatus.todos)).toHaveLength(0);
+    });
+  });
 });

package/src/activities/execute-deep-agent/command-provenance.ts

@@ -0,0 +1,102 @@
+/**
+ * Approved-command turn provenance (DD-28) — the DEEP-AGENT (native) harness
+ * adapter over the shared qualification rule ({@link qualifyTurnCommandProvenance}).
+ *
+ * The deep-agent's consent model differs from Cursor's in exactly two ways, and
+ * this adapter is precisely those two differences:
+ *
+ * 1. IDENTITY turn scoping (not positional). Cursor scopes a turn by the message
+ *    index its stream started at. The deep-agent cannot: an approved command
+ *    executes IN PLACE at its seeded transcript position (it was proposed in a
+ *    prior segment, seeded into this segment, and updated to COMPLETED by
+ *    `StatusBuilder.findResumableSeededToolCall`). So "this turn's calls" are
+ *    those whose id is absent from a pre-stream {@link collectSettledToolCallIds}
+ *    snapshot, and "executed" is a COMPLETED status.
+ *
+ * 2. SAME-ROW direct consent (not a grant token). A gated deep-agent tool pauses
+ *    on a LangGraph interrupt; SubmitApproval writes `approval_action` onto that
+ *    same row, and the row keeps its id + `approval_action` when it executes on
+ *    resume. So the executed command IS its own consent row — cite its own id.
+ *    (The server's PreserveApprovalFields keeps that `approval_action` on the row
+ *    across the status write regardless of its new status, so the backend's
+ *    verification finds it.)
+ *
+ * A turn that delegated ANY sub-agent fails closed (DD-28 D1: "delegated zero
+ * sub-agents"). A sub-agent's writes fold into the parent turn's change set
+ * (DD-19) but are not attributable to a consented top-level command. The
+ * top-level `task` call (a SUBAGENT kind) already trips the shared rule's
+ * `!== SHELL` fail-closed; the explicit sub-agent-novelty guard below also covers
+ * the (currently-impossible under the replace-per-turn model) case of a sub-agent
+ * that mutates across a turn boundary without a fresh top-level `task` row.
+ *
+ * (Trust boundary + fail-closed contract: see the shared module.)
+ */
+
+import {
+  ApprovalAction,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { qualifyTurnCommandProvenance } from "../../shared/filereview/command-provenance.js";
+import { collectSubAgentToolCallIds } from "../../shared/tool-row.js";
+
+export interface DeepAgentCommandProvenanceInputs {
+  /** The status at capture time — top-level messages + sub-agent executions. */
+  readonly status: AgentExecutionStatus;
+  /**
+   * The top-level tool-call ids that had already SETTLED before this turn's
+   * stream (from {@link collectSettledToolCallIds}). A top-level call whose id is
+   * absent is this-turn's; the shared rule then keeps only the COMPLETED ones.
+   */
+  readonly priorSettledToolCallIds: ReadonlySet<string>;
+  /**
+   * The sub-agent tool-call ids that existed before this turn's stream (from
+   * {@link collectSubAgentToolCallIds}). Any growth means a sub-agent acted this
+   * turn → fail closed.
+   */
+  readonly priorSubAgentToolCallIds: ReadonlySet<string>;
+  /** True when the pre-armed spec.auto_approve_all bypassed the gate. */
+  readonly globalBypass: boolean;
+}
+
+/**
+ * Derive the {@link TurnCommandProvenance} for a deep-agent turn, or undefined
+ * when it does not qualify. Scopes this turn's top-level calls by id-novelty,
+ * resolves consent from the row's own server-authored `approval_action`, fails
+ * closed on any sub-agent activity, and delegates the DD-28 rule to
+ * {@link qualifyTurnCommandProvenance}.
+ */
+export function deriveTurnCommandProvenance(
+  inputs: DeepAgentCommandProvenanceInputs,
+): TurnCommandProvenance | undefined {
+  const { status, priorSettledToolCallIds, priorSubAgentToolCallIds, globalBypass } = inputs;
+
+  // DD-28 D1 cond 2: any sub-agent activity this turn disqualifies. A sub-agent
+  // that ran this turn contributes at least one tool-call id absent from the
+  // pre-stream snapshot.
+  for (const id of collectSubAgentToolCallIds(status.subAgentExecutions)) {
+    if (!priorSubAgentToolCallIds.has(id)) return undefined;
+  }
+
+  const messages = status.messages;
+  // This turn's top-level calls: those not already settled before the stream.
+  const turnToolCalls = messages
+    .flatMap((m) => m.toolCalls)
+    .filter((tc) => !priorSettledToolCallIds.has(tc.id));
+
+  return qualifyTurnCommandProvenance({
+    turnToolCalls,
+    messages,
+    // A deep-agent command executed iff its row reached COMPLETED this turn.
+    isExecutedCommand: (tc) => tc.status === ToolCallStatus.TOOL_CALL_COMPLETED,
+    // The gated command carries its own server-authored approval_action, written
+    // in place by SubmitApproval and preserved when the row executes on resume.
+    resolveDirectConsent: (tc) =>
+      tc.approvalAction === ApprovalAction.APPROVE ||
+      tc.approvalAction === ApprovalAction.APPROVE_ALL
+        ? tc.id
+        : undefined,
+    globalBypass,
+  });
+}