@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/src/activities/execute-deep-agent/subagent-tracker.ts

@@ -10,8 +10,26 @@
  *     their first segment (e.g. "tools:<pregelUuid>|model_request:<innerUuid>")
  *   - First segment match (before "|") correlates child events to sub-agent
  *
- * The tracker owns the SubAgentExecution proto instances. V3StatusBuilder
- * delegates sub-agent-scoped events here instead of the parent message list.
+ * The tracker builds INTO the status's own `subAgentExecutions` array, by
+ * reference: it pushes new rows and mutates existing ones, never replaces the
+ * array, so the caller that seeded the array from the persisted transcript
+ * (the turn runtime's `seedFromPersistedStatus`) keeps every prior turn's
+ * row and every wrapper of the status sees the same rows. Seeded rows are
+ * indexed by id on construction; a re-emitted `task` tool start for a known
+ * id binds its routing prefix to the existing row instead of pushing a twin
+ * (the memory-checkpointer replay re-drives the whole graph), exactly as the
+ * parent builder reconciles re-emitted tool calls through its rebuilt index.
+ * Until S3 M2a the tracker owned a private array that `syncSubAgentExecutions`
+ * assigned onto the status wholesale, which a resumed turn's first delegation
+ * would have used to drop turn 1's rows (S3 M1 deferred debt).
+ *
+ * V3StatusBuilder delegates sub-agent-scoped events here instead of the
+ * parent message list. Marking rows CANCELLED when a turn stops is NOT the
+ * tracker's: `shared/subagent-rows.ts` `cancelInProgressSubAgentProtos` is
+ * the one home of that transition for every harness (the runtime's thrown
+ * arms and both adapters' stops call it); the tracker only clears the
+ * streaming flags those rows' messages still carry
+ * ({@link SubAgentTracker.finalizeAllStreaming}).
  */
 
 import { create, type JsonObject } from "@bufbuild/protobuf";
@@ -30,7 +48,7 @@ import {
 import { utcTimestamp } from "../../shared/status.js";
 import { classifyTool } from "../../shared/tool-kind.js";
 import { extractToolResultV3 } from "./status-builder-shared.js";
-import type { StigmerRunEvent, V3UsagePayload } from "./v3-events.js";
+import type { StigmerRunEvent } from "./v3-events.js";
 
 // ── Per-SubAgent State ───────────────────────────────────────────────────────
 
@@ -51,16 +69,50 @@ interface SubAgentState {
   toolArgBuffers: Map<string, string>;
 }
 
+/** Fresh routing state over a row; `namespacePrefix` is `""` for a seeded row until its `task` start re-announces it. */
+function newSubAgentState(proto: SubAgentExecution, callId: string, namespacePrefix: string): SubAgentState {
+  return {
+    proto,
+    callId,
+    namespacePrefix,
+    messagesByRun: new Map(),
+    currentAiMessage: new Map(),
+    lastLlmRunId: new Map(),
+    toolCalls: new Map(),
+    toolArgBuffers: new Map(),
+  };
+}
+
 // ── SubAgentTracker ──────────────────────────────────────────────────────────
 
 export class SubAgentTracker {
-  private readonly executions: SubAgentExecution[] = [];
   private readonly stateByCallId = new Map<string, SubAgentState>();
   private readonly stateByPrefix = new Map<string, SubAgentState>();
 
+  /**
+   * @param executions - The status's own `subAgentExecutions` array, built
+   *   into by reference. Rows already on it (the runtime's seed on a
+   *   reinvocation) are indexed by id, with their tool calls, so a re-driven
+   *   event reconciles onto them; their routing prefix is unknown until a
+   *   `task` tool start re-announces it.
+   */
+  constructor(private readonly executions: SubAgentExecution[]) {
+    for (const proto of executions) {
+      const state = newSubAgentState(proto, proto.id, "");
+      for (const message of proto.messages) {
+        for (const tc of message.toolCalls) {
+          if (tc.id) state.toolCalls.set(tc.id, tc);
+        }
+      }
+      this.stateByCallId.set(proto.id, state);
+    }
+  }
+
   /**
    * Called when a "task" tool_started event is observed at depth 0 or 1.
-   * Creates a new SubAgentExecution and begins tracking.
+   * Creates a new SubAgentExecution and begins tracking — or, for a seeded
+   * row re-announced by a replayed graph, binds the routing prefix to the
+   * row that already exists.
    *
    * @param callId - Provider tool call ID (e.g. "toolu_01HW...")
    * @param args - Tool input arguments (subagent_type, description)
@@ -70,7 +122,15 @@ export class SubAgentTracker {
    *   caller provides a synthetic prefix like "tools:<callId>".
    */
   onTaskToolStarted(callId: string, args: Record<string, unknown>, routingPrefix: string): void {
-    if (this.stateByCallId.has(callId)) return;
+    const existing = this.stateByCallId.get(callId);
+    if (existing) {
+      if (existing.namespacePrefix === "") {
+        const bound = { ...existing, namespacePrefix: routingPrefix };
+        this.stateByCallId.set(callId, bound);
+        this.stateByPrefix.set(routingPrefix, bound);
+      }
+      return;
+    }
 
     const name = safeString(args, "subagent_type") || "task";
     const description = safeString(args, "description") || "";
@@ -84,16 +144,7 @@ export class SubAgentTracker {
       startedAt: utcTimestamp(),
     });
 
-    const state: SubAgentState = {
-      proto,
-      callId,
-      namespacePrefix: routingPrefix,
-      messagesByRun: new Map(),
-      currentAiMessage: new Map(),
-      lastLlmRunId: new Map(),
-      toolCalls: new Map(),
-      toolArgBuffers: new Map(),
-    };
+    const state = newSubAgentState(proto, callId, routingPrefix);
 
     this.executions.push(proto);
     this.stateByCallId.set(callId, state);
@@ -129,16 +180,14 @@ export class SubAgentTracker {
   }
 
   /**
-   * Mark all active sub-agents as cancelled (parent execution cancelled).
+   * Clear the streaming flag on every tracked sub-agent's in-flight
+   * messages. Called when the turn stops before the sub-agents finished;
+   * the rows' own CANCELLED transition is the caller's, through the shared
+   * `cancelInProgressSubAgentProtos` (see the header).
    */
-  cancelAll(): void {
+  finalizeAllStreaming(): void {
     for (const state of this.stateByCallId.values()) {
-      if (state.proto.status === SubAgentStatus.SUB_AGENT_IN_PROGRESS) {
-        state.proto.status = SubAgentStatus.SUB_AGENT_CANCELLED;
-        state.proto.completedAt = utcTimestamp();
-        state.proto.error = "Cancelled: parent execution was cancelled";
-        this.finalizeStreamingMessages(state);
-      }
+      this.finalizeStreamingMessages(state);
     }
   }
 
@@ -186,7 +235,7 @@ export class SubAgentTracker {
         this.handleToolCallArgDelta(state, event.callId, event.argsChunk);
         break;
       case "message_finish":
-        this.handleMessageFinish(state, event.runId, event.usage);
+        this.handleMessageFinish(state, event.runId);
         break;
       case "tool_started":
         this.handleToolStarted(state, event.callId, event.name, event.input, localNs);
@@ -207,20 +256,6 @@ export class SubAgentTracker {
     }
   }
 
-  /**
-   * Returns the current list of SubAgentExecution protos for persist.
-   */
-  getExecutions(): SubAgentExecution[] {
-    return this.executions;
-  }
-
-  /**
-   * Returns true if any sub-agents are being tracked.
-   */
-  hasExecutions(): boolean {
-    return this.executions.length > 0;
-  }
-
   // ── Message Handlers ─────────────────────────────────────────────────────
 
   private handleMessageStart(state: SubAgentState, runId: string, localNs: string): void {
@@ -258,11 +293,11 @@ export class SubAgentTracker {
     state.messagesByRun.set(thinkingKey, msg);
   }
 
-  private handleMessageFinish(state: SubAgentState, runId: string, usage?: V3UsagePayload): void {
+  private handleMessageFinish(state: SubAgentState, runId: string): void {
     const msg = state.messagesByRun.get(runId);
     if (msg) msg.isStreaming = false;
-    // Usage is tracked at parent level via V3StatusBuilder — not duplicated per sub-agent
-    void usage;
+    // The usage on this event was reported by `V3StatusBuilder.processEvent`
+    // before it routed here (Q-M2b-1); the tracker owns the transcript only.
   }
 
   // ── Tool Handlers ──────────────────────────────────────────────────────

package/src/activities/execute-deep-agent/subagent-transformer.ts

@@ -14,7 +14,7 @@
  * - Built-in general-purpose replaces deepagents' auto-injected one (which carries
  *   no approval gate — see deepagents-profiles.ts for the suppression half)
  * - Sub-agent backends are shell-capable outside plan mode (issue #248), mirroring
- *   the parent's backend selection in setup.ts
+ *   the parent's backend selection in turn-setup.ts
  * - Sub-agent graphs carry the parent's filesystem permissions explicitly
  *   (issue #255): pre-built CompiledSubAgents never inherit them, so plan
  *   mode's deny-all-writes rule is baked into each graph at compile time
@@ -31,20 +31,16 @@ import type { BaseChatModel } from "@langchain/core/language_models/chat_models"
 import type { SubAgent, McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 
 import type { WorkspaceBackend } from "../../shared/workspace/types.js";
-import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { ApprovalGateConfig } from "../../middleware/approval-gate.js";
 import { createCasCaptureBackend } from "./cas-capture-backend.js";
 import type { CasCaptureObserver } from "./cas-capture-observer.js";
-import type { CostCapMiddleware, StigmerMiddleware } from "../../middleware/index.js";
+import type { CostAdvisoryMiddleware, StigmerMiddleware } from "../../middleware/index.js";
 import { createThinkTool, createWebFetchTool, type GuardPosture } from "../../tools/index.js";
 import { buildSubAgentMiddleware } from "./subagent-wiring.js";
 import { SubAgentGate } from "../../shared/subagent-gate.js";
 import { isModelRegistered } from "../../shared/model-registry.js";
-import {
-  fetchSkillsByRefs,
-  mountSkills,
-  generatePromptSection,
-} from "../../shared/skill-writer.js";
+import type { SkillMetadata } from "../../shared/skill-resolver.js";
+import { renderSkillsSection } from "./prompt-builder.js";
 
 // =========================================================================
 // Built-in subagent types and prompts
@@ -141,7 +137,14 @@ export interface SubagentTransformOptions {
   readonly parentMcpTools: readonly StructuredTool[];
   readonly parentMcpServerToolMap: ReadonlyMap<string, readonly StructuredTool[]>;
   readonly parentMcpUsages: readonly McpServerUsage[];
-  readonly skillClient: StigmerClient;
+  /**
+   * Each sub-agent's mounted skills, keyed by the sub-agent's name — the
+   * runtime's `TurnSkills.bySubAgent` (resolved and mounted by its skills
+   * phase, S3 M1 Q-S3-5). A sub-agent with no entry renders no skills
+   * section. Until S3 M2a this module fetched and mounted them itself with
+   * a control-plane client; the compile step is client-free now.
+   */
+  readonly skills: ReadonlyMap<string, readonly SkillMetadata[]>;
   readonly workspaceBackend: WorkspaceBackend;
   /**
    * The parent's approval-gate config, inherited verbatim so a mutating tool
@@ -162,11 +165,11 @@ export interface SubagentTransformOptions {
   readonly parentHasNativeThinking: boolean;
   /**
    * URL-guard posture for the native `web_fetch` tool, inherited from the
-   * parent (resolveGuardPosture(config.mode) in setup.ts) so a sub-agent
+   * parent (resolveGuardPosture(config.mode) in turn-setup.ts) so a sub-agent
    * fetch is bounded exactly like a parent fetch.
    */
   readonly webFetchPosture: GuardPosture;
-  readonly costCap?: CostCapMiddleware;
+  readonly costAdvisory?: CostAdvisoryMiddleware;
   /**
    * Builds a configured chat-model instance for a given model name. When
    * provided, sub-agents are compiled with the same proxy-aware model client
@@ -184,7 +187,7 @@ export interface SubagentTransformOptions {
   readonly shellEnv?: Record<string, string>;
   /**
    * Filesystem permission rules baked into each compiled sub-agent graph,
-   * inherited from the parent's rules in setup.ts (plan mode's deny-all-writes
+   * inherited from the parent's rules in turn-setup.ts (plan mode's deny-all-writes
    * today). Required because deepagents' parent-permission inheritance covers
    * only spec-style sub-agents — pre-built CompiledSubAgents bypass it, so
    * without this a plan-mode sub-agent could still write (issue #255).
@@ -321,7 +324,7 @@ export async function transformSingleSubagent(
   }
 
   // web_fetch is unconditional — unlike think, it is a capability, not a
-  // reasoning aid, and the parent always has it (setup.ts Step 11). A
+  // reasoning aid, and the parent always has it (turn-setup.ts `buildEngine`). A
   // sub-agent silently lacking web access the parent has would recreate the
   // harness-parity gap of issue #214 one level down.
   tools.push(createWebFetchTool({ posture: opts.webFetchPosture }) as unknown as StructuredTool);
@@ -415,64 +418,38 @@ export function filterMcpToolsForSubagent(
 // =========================================================================
 
 /**
- * Collect all unique skill refs across all subagents for batch fetching.
- *
- * Deduplicates by slug to minimize gRPC calls. Returns an array of refs
- * and the mapping from slug to original refs for distribution.
+ * The `## Skills` section of one sub-agent's system prompt, from the skills
+ * the runtime mounted for it. Empty when it has none.
  */
-export function collectAllSkillRefs(
-  subAgents: readonly SubAgent[],
-): { slug: string; ref: unknown }[] {
-  const seen = new Set<string>();
-  const unique: { slug: string; ref: unknown }[] = [];
-
-  for (const sa of subAgents) {
-    for (const ref of sa.skillRefs) {
-      const slug = (ref as { slug?: string }).slug;
-      if (slug && !seen.has(slug)) {
-        seen.add(slug);
-        unique.push({ slug, ref });
-      }
-    }
-  }
-
-  return unique;
+export function resolveSubagentSkillPrompt(
+  subAgent: SubAgent,
+  skills: ReadonlyMap<string, readonly SkillMetadata[]>,
+): string {
+  return renderSkillsSection(skills.get(subAgent.name) ?? []);
 }
 
 /**
- * Resolve skills for a single subagent and return the prompt section.
- *
- * Looks up each of the subagent's skill_refs in the pre-fetched skills
- * collection and generates a prompt section containing activation
- * instructions and file paths.
- *
- * Returns empty string if no skills match or if the subagent has no skill_refs.
+ * Heuristic check for native extended thinking support. Models with thinking
+ * support don't need the explicit think tool. Read for the parent (does its
+ * graph carry `think`?) and inherited by every sub-agent that names no model
+ * of its own. Moved from `setup.ts` at S3 M2a: the compile step is where it
+ * is consumed, and the adapter's setup reads it from here too.
  */
-export function resolveSubagentSkillPrompt(
-  subAgent: SubAgent,
-  skillsBySlug: ReadonlyMap<string, { skill: unknown; path: string }>,
-): string {
-  if (subAgent.skillRefs.length === 0) return "";
+export function modelHasNativeThinking(modelId: string): boolean {
+  const lower = modelId.toLowerCase();
 
-  const matchedSkills: unknown[] = [];
-  const matchedPaths = new Map<string, string>();
+  if (lower.includes("haiku")) return false;
+  if (lower.includes("gpt-4o-mini")) return false;
 
-  for (const ref of subAgent.skillRefs) {
-    const slug = (ref as { slug?: string }).slug;
-    if (!slug) continue;
+  if (lower.includes("claude") && (
+    lower.includes("sonnet") || lower.includes("opus")
+  )) return true;
 
-    const entry = skillsBySlug.get(slug);
-    if (entry) {
-      matchedSkills.push(entry.skill);
-      const id = (entry.skill as { metadata?: { id?: string } }).metadata?.id;
-      if (id) matchedPaths.set(id, entry.path);
-    }
+  if (lower.includes("o1") || lower.includes("o3") || lower.includes("o4")) {
+    return true;
   }
 
-  if (matchedSkills.length === 0) return "";
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return generatePromptSection(matchedSkills as any[], matchedPaths);
+  return false;
 }
 
 // =========================================================================
@@ -481,7 +458,7 @@ export function resolveSubagentSkillPrompt(
 
 /**
  * Select a sub-agent's deepagents backend, mirroring the parent's selection in
- * setup.ts along two independent axes:
+ * turn-setup.ts along two independent axes:
  *
  * - CAS observation (capture mode): when a shared observer is supplied, the
  *   backend records pre-turn bytes of CAS-owned paths so the sub-agent's
@@ -535,7 +512,7 @@ async function buildSubagentBackend(opts: {
 export async function compileSubagents(
   transformed: readonly TransformedSubagent[],
   opts: {
-    readonly costCap?: CostCapMiddleware;
+    readonly costAdvisory?: CostAdvisoryMiddleware;
     readonly approvalGate?: ApprovalGateConfig | null;
     readonly parentModelName: string;
     readonly workspaceRootDir: string;
@@ -562,7 +539,7 @@ export async function compileSubagents(
       // (issue #754): every graph speaks the virtual dialect, so every graph
       // carries the repair seam — matching the parent's composition.
       const middleware = buildSubAgentMiddleware({
-        costCap: opts.costCap,
+        costAdvisory: opts.costAdvisory,
         approvalGate: opts.approvalGate,
         captureIgnored: !!opts.casObserver,
         pathNormalization: { rootDir: opts.workspaceRootDir },
@@ -623,7 +600,7 @@ export async function compileSubagents(
 /**
  * Transform proto SubAgents and compile into CompiledSubAgent instances.
  *
- * This is the main entry point called from setup.ts. It orchestrates:
+ * This is the main entry point called from turn-setup.ts. It orchestrates:
  * 1. Built-in subagent creation (explore, shell, general-purpose)
  * 2. Per-subagent transformation (proto → TransformedSubagent)
  * 3. MCP tool filtering per subagent
@@ -640,14 +617,14 @@ export async function transformAndCompileSubagents(
     parentMcpTools,
     parentMcpServerToolMap,
     parentMcpUsages,
-    skillClient,
+    skills,
     workspaceBackend,
     approvalGate,
     casObserver,
     parentModelName,
     parentHasNativeThinking,
     webFetchPosture,
-    costCap,
+    costAdvisory,
     modelFactory,
     shellEnv,
     permissions,
@@ -669,42 +646,6 @@ export async function transformAndCompileSubagents(
     webFetchPosture,
   );
 
-  // Step 1b: Batch fetch all skills referenced by subagents
-  const allSkillRefs = collectAllSkillRefs(subAgents);
-  const skillsBySlug = new Map<string, { skill: unknown; path: string }>();
-
-  if (allSkillRefs.length > 0) {
-    try {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const refs = allSkillRefs.map((r) => r.ref) as any[];
-      const skills = await fetchSkillsByRefs(skillClient, refs);
-
-      if (skills.length > 0) {
-        // Runs after the parent's setup step 7b mounted its skills, so any
-        // skill shared by parent and sub-agent is a cache hit here — the
-        // hash-keyed marker turns the old double download into a no-op.
-        // platformDir is an invariant: provisionWorkspace threads
-        // ensurePlatformDir into every backend it constructs.
-        const { paths: skillPaths } = await mountSkills(
-          skillClient, skills, workspaceBackend.platformDir!,
-        );
-
-        for (const skill of skills) {
-          const slug = (skill as { metadata?: { slug?: string } }).metadata?.slug;
-          const id = (skill as { metadata?: { id?: string } }).metadata?.id;
-          if (slug && id) {
-            skillsBySlug.set(slug, { skill, path: skillPaths.get(id) ?? "" });
-          }
-        }
-        console.log(
-          `[subagent-transformer] Fetched ${skills.length} skill(s) for subagents`,
-        );
-      }
-    } catch (err) {
-      console.error(`[subagent-transformer] Failed to fetch skills for subagents: ${err}`);
-    }
-  }
-
   // Step 2: Transform proto subagents
   const transformed: TransformedSubagent[] = [];
 
@@ -735,7 +676,7 @@ export async function transformAndCompileSubagents(
         );
 
         // Resolve skills prompt section for this subagent
-        const skillsSection = resolveSubagentSkillPrompt(subAgent, skillsBySlug);
+        const skillsSection = resolveSubagentSkillPrompt(subAgent, skills);
         const enhancedPrompt = skillsSection
           ? result.systemPrompt.replace(
               RESPONSE_RULES,
@@ -770,7 +711,7 @@ export async function transformAndCompileSubagents(
 
   // Step 4: Compile all subagents
   const compiled = await compileSubagents(allSpecs, {
-    costCap,
+    costAdvisory,
     approvalGate,
     parentModelName,
     workspaceRootDir: workspaceBackend.rootDir,

package/src/activities/execute-deep-agent/subagent-wiring.ts

@@ -41,7 +41,7 @@ import type {
   ToolTruncationConfig,
   PathNormalizationConfig,
 } from "../../middleware/types.js";
-import type { CostCapMiddleware } from "../../middleware/index.js";
+import type { CostAdvisoryMiddleware } from "../../middleware/index.js";
 import { createPathNormalizationMiddleware } from "../../middleware/path-normalization.js";
 import { createLoopDetectionMiddleware } from "../../middleware/loop-detection.js";
 import { createToolTruncationMiddleware } from "../../middleware/tool-truncation.js";
@@ -57,7 +57,8 @@ const SUB_AGENT_ADVISORY_INTERVAL = 30;
 const SUB_AGENT_MAX_ADVISORIES = 4;
 
 export interface SubAgentMiddlewareOptions {
-  readonly costCap?: CostCapMiddleware;
+  /** The parent's cost advisory, whose running total the sub-agent's calls advance. */
+  readonly costAdvisory?: CostAdvisoryMiddleware;
   readonly toolTruncation?: Partial<ToolTruncationConfig>;
   /**
    * Approval gate config inherited from the parent. When present, the sub-agent
@@ -142,8 +143,8 @@ export function buildSubAgentMiddleware(
     ));
   }
 
-  if (options.costCap) {
-    stack.push(options.costCap.forSubAgent());
+  if (options.costAdvisory) {
+    stack.push(options.costAdvisory.forSubAgent());
   }
 
   stack.push(createErrorHintsMiddleware());

package/src/activities/execute-deep-agent/turn-settle.ts

@@ -0,0 +1,164 @@
+/**
+ * The native deep-agent harness's settle — from a consumed stream to a
+ * `TurnOutcome`.
+ *
+ * In order: drain the inline publishes the stream fired and, on a finished
+ * turn, run the auto-publish safety net; settle the gate's unattended skips
+ * (the one settlement whose evidence exists only inside this harness); on
+ * the runtime's stop, mark in-flight sub-agent rows through the shared act
+ * and settle `interrupted` with nothing further; the graph's
+ * `structuredResponse` folded onto the status; the interrupts a completed
+ * stream left pending seeded as WAITING rows; and the outcome.
+ *
+ * What this module never does: write a phase, a terminal copy or
+ * `completedAt` — those are the runtime's (`harness/run-turn.ts`,
+ * `terminal-table.ts`); settle SKIP and REJECT rows — the runtime's
+ * (`harness/approval-decisions.ts`, after every outcome); withhold secret
+ * content — the runtime's chokepoint does it on every write; finalize the
+ * write-back — the runtime's epilogue; capture the turn's file changes or
+ * decide whether a review is pending — the runtime's (`harness/capture.ts`,
+ * once, over whatever the whole turn left on the tree, after this settle
+ * returns; S3 M4). It does mutate `sink.status`'s transcript rows, which
+ * are this harness's to write.
+ *
+ * The structured response is folded BEFORE the outcome is decided, so a turn
+ * the runtime then pauses for file review persists it and the pure
+ * file-review resume completes with it (the runtime's text fallback runs on
+ * the review-pending path too, Q-M4-8).
+ *
+ * Moved from `index.ts` (post-stream through the terminal arms) at S3 M2a;
+ * the capture boundary left for the runtime at M4.
+ */
+
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import type { TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
+import { POLICY_ENGINE_VERSION, toProtoPolicySource } from "../../shared/approval-policy.js";
+import { utcTimestamp } from "../../shared/status.js";
+import { cancelInProgressSubAgentProtos } from "../../shared/subagent-rows.js";
+import { classifyTool } from "../../shared/tool-kind.js";
+import { captureApprovalArtifacts } from "./approval-file-change.js";
+import { autoPublishWrittenFiles } from "./auto-publish.js";
+import { detectPendingInterrupts, reconcileUnattendedSkips, type GraphStateSnapshot } from "./hitl.js";
+import type { DeepAgentEngine } from "./turn-setup.js";
+import type { DeepAgentStreamResult, DeepAgentTranscript } from "./turn-stream.js";
+
+export interface DeepAgentSettleDeps {
+  readonly input: TurnInput;
+  readonly sink: TurnSink;
+  readonly engine: DeepAgentEngine;
+  readonly transcript: DeepAgentTranscript;
+  readonly stream: DeepAgentStreamResult;
+}
+
+export async function settleDeepAgentTurn(deps: DeepAgentSettleDeps): Promise<TurnOutcome> {
+  const { input, sink, engine, transcript, stream } = deps;
+  const { executionId } = input;
+  const { status } = sink;
+
+  // Drain the publishes the stream fired (fire-and-forget completions); the
+  // safety net that scans tool calls for files the stream missed runs only
+  // on a finished turn, as it always did.
+  if (stream.pendingPublishPromises.length > 0) {
+    await Promise.allSettled(stream.pendingPublishPromises);
+  }
+  if (stream.reason === "completed") {
+    try {
+      await autoPublishWrittenFiles(status, transcript.publisher);
+    } catch (err) {
+      console.warn(`[turn-settle] execution=${executionId} — auto-publish safety net error: ${err}`);
+    }
+  }
+  sink.recordActivity();
+
+  // Terminalize every tool call the gate auto-skipped under UNATTENDED
+  // approval mode (DD-014): the skip has no human decision behind it, so the
+  // runtime's terminalizer cannot see it; the gate's registry is this
+  // harness's evidence.
+  reconcileUnattendedSkips(status, engine.gate.unattendedSkips);
+
+  if (stream.reason === "interrupted") {
+    // A stopped turn aborted the graph run, so any sub-agent the parent had
+    // delegated is no longer executing: CANCELLED through the one shared act
+    // (the runtime marks them itself only on its thrown arms), its messages'
+    // streaming flags cleared. There is no review to open.
+    cancelInProgressSubAgentProtos(status.subAgentExecutions);
+    transcript.builder.finalizeSubAgentStreaming();
+    return { kind: "interrupted" };
+  }
+
+  // The graph's structured response, when the run surfaced one: folded now,
+  // so a turn the runtime pauses for review persists it and the pure
+  // file-review resume completes with it.
+  if (engine.hasStructuredOutput) {
+    const sr = stream.runOutput?.structuredResponse;
+    if (sr != null && typeof sr === "object" && !Array.isArray(sr)) {
+      status.structuredOutput = sr as JsonObject;
+    } else if (sr !== undefined) {
+      console.warn(`[turn-settle] structuredResponse is not a plain object for execution ${executionId}: type=${typeof sr}`);
+    }
+  }
+
+  if (stream.reason === "awaiting_approval") {
+    return { kind: "awaiting_approval" };
+  }
+
+  // A completed stream can still leave the graph interrupted at a gate whose
+  // tool start produced no row (the durable savers resume without a
+  // tool_started; the replay path never re-drives it): read the checkpoint
+  // once more and seed a WAITING row per pending interrupt. Skipped under
+  // the global bypass, where no gate is installed.
+  if (!engine.gate.globalBypass && (await seedPendingInterrupts(deps))) {
+    return { kind: "awaiting_approval" };
+  }
+
+  return { kind: "completed" };
+}
+
+/**
+ * Seed one WAITING_APPROVAL row per interrupt the graph left pending, on one
+ * AI message, with the sanitized args preview AND the redacted args read
+ * from the AI message in graph state (the single source of truth for the
+ * proposed call; issue #754: a placeholder without args rendered a pathless
+ * header). Returns whether any was seeded.
+ */
+async function seedPendingInterrupts(deps: DeepAgentSettleDeps): Promise<boolean> {
+  const { input, sink, engine } = deps;
+  const graphState: GraphStateSnapshot = await engine.graph.getState(engine.langgraphConfig);
+  const pending = detectPendingInterrupts(graphState);
+  if (pending.length === 0) return false;
+
+  const graphMessages = (graphState.values as { messages?: unknown }).messages;
+  const aiMessages = Array.isArray(graphMessages) ? graphMessages : [];
+  console.log(`[turn-settle] Detected ${pending.length} pending interrupt(s) for execution ${input.executionId} — awaiting approval`);
+
+  const aiMsg = create(AgentMessageSchema, {
+    type: MessageType.MESSAGE_AI,
+    content: "",
+    timestamp: utcTimestamp(),
+    isStreaming: false,
+  });
+  for (const intr of pending) {
+    const toolCall = create(ToolCallSchema, {
+      id: intr.toolCallId,
+      name: intr.toolName,
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      requiresApproval: true,
+      approvalMessage: intr.message,
+      approvalRequestedAt: utcTimestamp(),
+      mcpServerSlug: intr.mcpServerSlug,
+      startedAt: utcTimestamp(),
+      toolKind: classifyTool(intr.toolName, intr.mcpServerSlug),
+      approvalPolicySource: toProtoPolicySource(intr.policySource),
+      policyEngineVersion: intr.policySource ? POLICY_ENGINE_VERSION : "",
+    });
+    const { argsPreview, args } = captureApprovalArtifacts({ toolCallId: intr.toolCallId, messages: aiMessages });
+    if (argsPreview) toolCall.argsPreview = argsPreview;
+    if (args) toolCall.args = args as typeof toolCall.args;
+    aiMsg.toolCalls.push(toolCall);
+  }
+  sink.status.messages.push(aiMsg);
+  return true;
+}