@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/src/harness/run-turn.ts

@@ -59,19 +59,23 @@ import {
   getShutdownSignalForQueue,
   type TurnInterruption,
 } from "../shared/worker-shutdown.js";
+import { terminalizeNonExecutingDecisions } from "./approval-decisions.js";
+import { captureCandidate, pinCaptureBaseline, type TurnCapture } from "./capture.js";
 import { PersistChokepoint } from "./persist-chokepoint.js";
 import { StopController } from "./stop-controller.js";
 import {
   applyTerminalArm,
+  awaitingApprovalArm,
+  awaitingReviewArm,
   costCapArm,
   failedArm,
   fileReviewResolvedArm,
   infrastructureCancelArm,
   pauseArm,
   platformStopArm,
-  rejectedByUserArm,
   stallArm,
   TERMINAL_COPY,
+  toolCallLimitArm,
   unexpectedErrorArm,
   workerShutdownArm,
   workspaceLockTimeoutArm,
@@ -161,6 +165,8 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
   const frame: TurnFrame = { primaryDir: undefined, releaseWorkspaceLock: undefined, writeback: null };
   const stop = new StopController();
   let usage: UsageAccumulator | undefined;
+  /** The turn's capture once the baseline is pinned (capture mode only); the chokepoint reads its progress at every write. */
+  let capture: TurnCapture | undefined;
   let heartbeatPhase = "setup";
   let lastActivityDetail: string | undefined;
   let watchdog: StallWatchdog | undefined;
@@ -175,6 +181,7 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
     status,
     offload: artifactStorage ? { artifactStorage, executionId } : undefined,
     usage: () => usage,
+    progress: () => capture?.progress,
     heartbeat,
     onPlatformStop: () => stop.stop({ kind: "platform-stop" }),
   });
@@ -231,9 +238,6 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
         console.warn(`${activityName} workspace lock timeout: execution=${executionId}`);
         return outcome;
       }
-      case "rejected-by-user":
-        // A reject of an irreversible action (shell/MCP) fails the execution.
-        return settleWith(rejectedByUserArm());
       case "file-review-resolved": {
         // Push the APPROVED tree — reconcile snapped rejected files back to
         // baseline, so what finalize commits is exactly what the user kept.
@@ -248,7 +252,10 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
           `${activityName} file-review resume short-circuit: execution=${executionId}, ` +
             `failed=${settlement.failed}, discarded=${settlement.discardedPaths.length}`,
         );
-        return { kind: "return", value: slimStatus(status) };
+        // The execution completes here, so its answer rides the slim as it
+        // does from `completeTurn`: the seed carried the transcript and any
+        // structured output the paused turn resolved (Q-M4-8).
+        return { kind: "return", value: completionSlim(lastAssistantText()) };
       }
       default: {
         const exhaustive: never = settlement;
@@ -312,32 +319,81 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
         await client.updateSession(turn.session);
         console.log(`Stored ${harnessStateId} as harness_state_id on session ${turn.sessionId}`);
       },
+      bindCasObservations: (read) => {
+        // Outside capture mode there is no capture to feed; the bind is a
+        // no-op, as the contract promises a harness that always binds.
+        if (capture) capture.casObservations = read;
+      },
     };
 
+    // The capture baseline: the runtime's LAST act before the engine, after
+    // every write of its own into the tree (the reconcile, the mounts), so
+    // anything on the tree after this point is the turn's change, whoever
+    // wrote it (`capture.ts`). Absent outside capture mode.
+    capture = await pinCaptureBaseline({
+      status,
+      executionId,
+      workspace: turn.workspace,
+      fileReview: adapter.capabilities.fileReview,
+      artifactStorage: turn.artifactStorage,
+    });
+
     heartbeatPhase = "harness";
     const outcome = await adapter.runTurn(turn, sink);
     armedWatchdog.stop();
     heartbeatPhase = "epilogue";
 
+    // The capture boundary, ONCE, over whatever the whole turn left on the
+    // tree — unless a stop fired mid-turn (`interrupted`: the tree may be
+    // mid-edit and the pause or drain reinvokes this same turn). Before the
+    // decisions settle below, so the stamp reads the rows as the engine
+    // left them. A pending review is the outcome table's second WAITING
+    // cause (`awaitingReviewArm`).
+    const reviewPending =
+      capture !== undefined && outcome.kind !== "interrupted"
+        ? await captureCandidate({
+            status,
+            executionId,
+            workspace: turn.workspace,
+            fileReview: adapter.capabilities.fileReview,
+            artifactStorage: turn.artifactStorage,
+            capture,
+            globalBypass: turn.mcp.leases.global,
+          })
+        : false;
+
+    // The rows whose decision never runs the tool (SKIP, REJECT) are settled
+    // by the runtime, once, now that the adapter has had its look at them and
+    // before any persist of the outcome: no engine event flips such a row, so
+    // without this it would persist WAITING on a finished execution. Every
+    // outcome passes through here (`approval-decisions.ts`).
+    terminalizeNonExecutingDecisions(status);
+
     switch (outcome.kind) {
       case "completed":
-        return completeTurn(turn, ExecutionPhase.EXECUTION_COMPLETED);
+        return reviewPending ? pauseCompletedTurnForReview(turn) : completeTurn(turn, ExecutionPhase.EXECUTION_COMPLETED);
       case "cancelled":
-        return completeTurn(turn, ExecutionPhase.EXECUTION_CANCELLED);
-      case "awaiting_approval": {
-        // Pause for review exactly like the native harness: the adapter put
-        // the WAITING rows on the transcript; flip the phase, persist, and
-        // RETURN to the workflow, which waits for the approval signal and
-        // reinvokes.
-        status.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
-        await chokepoint.write();
-        return { kind: "return", value: slimStatus(status) };
+        return reviewPending ? settleWith(awaitingReviewArm()) : completeTurn(turn, ExecutionPhase.EXECUTION_CANCELLED);
+      case "awaiting_approval":
+        // The adapter put the WAITING rows on the transcript (and a captured
+        // candidate, if any, rides the same write); the arm flips the phase,
+        // persists once, and RETURNS to the workflow, which waits for the
+        // approval or file-review signal and reinvokes.
+        return settleWith(awaitingApprovalArm());
+      case "tool_call_limit": {
+        // A review wins over the terminal (Q-M4-2): the limit's copy rides
+        // the transcript and the reinvocation's reconcile completes the turn.
+        const settledLimit = await settleWith(reviewPending ? awaitingReviewArm(toolCallLimitArm()) : toolCallLimitArm());
+        console.log(`${activityName} terminated (tool-call limit): execution=${executionId}${reviewPending ? ", review pending" : ""}`);
+        return settledLimit;
       }
       case "failed": {
-        const settledFailure = await settleWith(failedArm(outcome.message, outcome.surface));
+        const arm = failedArm(outcome.message, outcome.surface);
+        const settledFailure = await settleWith(reviewPending ? awaitingReviewArm(arm) : arm);
         console.error(
           `${activityName} failed (${outcome.surface}): execution=${executionId}, error=${outcome.message}` +
-            (outcome.cause instanceof Error ? `, cause=${outcome.cause.message}` : ""),
+            (outcome.cause instanceof Error ? `, cause=${outcome.cause.message}` : "") +
+            (reviewPending ? " — edits on the tree; review pending" : ""),
         );
         return settledFailure;
       }
@@ -400,6 +456,19 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
     return settleWith(unexpectedErrorArm("HarnessContractError", `${adapter.name} settled interrupted with no stop`));
   }
 
+  /**
+   * The engine finished AND left a reviewable change: the structured output
+   * is resolved now, before the WAITING persist, so the resume that
+   * reconciles the review completes with it (Q-M4-8 closes Q-M2a-5); then
+   * the review pause. Nothing else of the completion epilogue runs here —
+   * the plan artifact and the write-back belong to the settlement that
+   * actually completes the execution.
+   */
+  async function pauseCompletedTurnForReview(turn: TurnInput): Promise<Settled> {
+    await resolveStructuredOutput(turn, lastAssistantText());
+    return settleWith(awaitingReviewArm());
+  }
+
   /**
    * A turn the engine finished (COMPLETED) or ended cancelled on its own
    * (CANCELLED): the final text from the last AI row; the structured output
@@ -413,18 +482,11 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
     status.completedAt = utcTimestamp();
     status.phase = phase;
 
-    let structuredOutput: unknown = status.structuredOutput;
     let finalText: string | undefined;
 
     if (phase === ExecutionPhase.EXECUTION_COMPLETED) {
-      finalText = [...status.messages].reverse().find((m) => m.type === MessageType.MESSAGE_AI)?.content;
-
-      if (structuredOutput === undefined && turn.structuredOutputSchema && finalText) {
-        structuredOutput = await extractStructuredOutputFromText(turn, finalText);
-        if (structuredOutput !== undefined) {
-          status.structuredOutput = structuredOutput as JsonObject;
-        }
-      }
+      finalText = lastAssistantText();
+      await resolveStructuredOutput(turn, finalText);
 
       // Plan mode: publish the final plan message as a plan artifact (named
       // from the plan's title); the only artifact path a harness without an
@@ -452,14 +514,43 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
     await chokepoint.write();
     console.log(
       `${activityName} completed: execution=${executionId}, phase=${ExecutionPhase[status.phase]}, ` +
-        `hasStructuredOutput=${structuredOutput !== undefined}` +
+        `hasStructuredOutput=${status.structuredOutput !== undefined}` +
         (status.error ? `, error=${status.error}` : ""),
     );
+    return { kind: "return", value: completionSlim(finalText) };
+  }
 
+  /** The last assistant text on the transcript: the turn's `final_text`. */
+  function lastAssistantText(): string | undefined {
+    return [...status.messages].reverse().find((m) => m.type === MessageType.MESSAGE_AI)?.content;
+  }
+
+  /**
+   * The structured output the execution asked for, folded onto the status
+   * unless the adapter already did (the deep-agent's `structuredResponse`):
+   * extracted from the final text through the tiers below. Runs where the
+   * engine has FINISHED speaking — a completed turn, and a completed turn
+   * the runtime pauses for file review (Q-M4-8: the pure-reconcile
+   * COMPLETED then carries it, on every harness).
+   */
+  async function resolveStructuredOutput(turn: TurnInput, finalText: string | undefined): Promise<void> {
+    if (status.structuredOutput !== undefined || !turn.structuredOutputSchema || !finalText) return;
+    const extracted = await extractStructuredOutputFromText(turn, finalText);
+    if (extracted !== undefined) status.structuredOutput = extracted as JsonObject;
+  }
+
+  /**
+   * The slim return of a COMPLETED execution: the status the workflow reads,
+   * with `final_text` and `structured` beside it for the callers that consume
+   * an agent's answer as a value (`call-agent-orchestrator.ts`). One shape for
+   * the two ways an execution completes — the engine's own finish and the
+   * pure file-review resume.
+   */
+  function completionSlim(finalText: string | undefined): Record<string, unknown> {
     const slim = slimStatus(status) as Record<string, unknown>;
     if (finalText !== undefined) slim.final_text = finalText;
-    if (structuredOutput !== undefined) slim.structured = structuredOutput;
-    return { kind: "return", value: slim };
+    if (status.structuredOutput !== undefined) slim.structured = status.structuredOutput;
+    return slim;
   }
 
   /**

package/src/harness/terminal-table.ts

@@ -8,8 +8,8 @@
  * contract of the runner (the hermetic goldens pin every string below byte
  * for byte, `activities/execute-cursor/__tests__/hermetic/`), and a table a
  * reader can scan is how that contract stays reviewable. The native
- * harness's `execute-deep-agent/streaming-terminal.ts` keeps one function
- * per arm; S3 aligns the two (P-1's copy alignment) with both in view.
+ * harness once kept one function per arm (`streaming-terminal.ts`, retired
+ * at S3 M2b); since S3 M2a both harnesses' turns end through this one table.
  *
  * The throw-vs-return rule, unchanged from the orchestrator it replaces:
  *  - RETURN when a Temporal retry would only repeat the outcome — a stall
@@ -36,6 +36,7 @@ import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexec
 import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
 import { COST_LIMIT_USER_COPY, formatCostLimitError } from "../shared/cost-guard.js";
+import { TOOL_CALL_LIMIT_USER_COPY, formatToolCallLimitError } from "../shared/tool-rounds.js";
 import { formatStallFailure, type StallTimeoutError } from "../shared/stall-watchdog.js";
 import { utcTimestamp } from "../shared/status.js";
 import type { WorkspaceLockTimeoutError } from "../shared/workspace/workspace-lock.js";
@@ -79,10 +80,6 @@ export const TERMINAL_COPY = {
   platformStop: {
     row: "Execution stopped by the platform.",
   },
-  rejectedByUser: {
-    error: "Execution rejected by user",
-    row: "Execution was rejected by the user during tool approval.",
-  },
   fileReview: {
     applyFailedPrefix: "Some approved file changes could not be applied because the file changed after review: ",
     discardedPrefix: "Some proposed file changes were discarded by the user and were not applied: ",
@@ -110,9 +107,9 @@ export function stallArm(error: StallTimeoutError): TerminalArm {
 /**
  * The cost cap stopped the turn. TERMINATED, not FAILED: the platform
  * deliberately stopped the run, work is checkpointed, and the conversation
- * continues on the next message (the recursion-limit precedent in
- * `execute-deep-agent/streaming-terminal.ts`). RETURN: a retry would burn
- * the same budget again.
+ * continues on the next message (the recursion-limit precedent,
+ * {@link toolCallLimitArm}). RETURN: a retry would burn the same budget
+ * again.
  */
 export function costCapArm(maxCostUsd: number, estimatedCostUsd: number): TerminalArm {
   return {
@@ -124,6 +121,23 @@ export function costCapArm(maxCostUsd: number, estimatedCostUsd: number): Termin
   };
 }
 
+/**
+ * The engine exhausted its tool-round budget (`max_tool_rounds`). TERMINATED,
+ * not FAILED, for the cost cap's reason: the platform deliberately stopped
+ * the run, work is checkpointed, and the conversation continues on the next
+ * message. RETURN: a retry would spend the same budget again. The error's
+ * prefix is a cross-repo contract (`shared/tool-rounds.ts`).
+ */
+export function toolCallLimitArm(): TerminalArm {
+  return {
+    phase: ExecutionPhase.EXECUTION_TERMINATED,
+    error: formatToolCallLimitError(),
+    rows: [TOOL_CALL_LIMIT_USER_COPY],
+    completes: true,
+    disposition: RETURN,
+  };
+}
+
 /** The runner is draining. Not a user pause: FAILED with the shutdown copy, thrown as cancelled. */
 export function workerShutdownArm(): TerminalArm {
   return {
@@ -156,6 +170,44 @@ export function infrastructureCancelArm(): TerminalArm {
   };
 }
 
+/**
+ * The engine proposed at least one gated side effect and stopped: the
+ * WAITING_APPROVAL rows are already on the transcript. Not an error, not
+ * complete, no copy; RETURN to the workflow, which waits for the approval
+ * signal and reinvokes with the decisions. Until S3 M4 this was an inline
+ * phase flip in `run-turn.ts`; it is an arm because every way an activity
+ * ends belongs in this one table.
+ */
+export function awaitingApprovalArm(): TerminalArm {
+  return { phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL, rows: [], completes: false, disposition: RETURN };
+}
+
+/**
+ * The engine's turn left a reviewable change on the tree (the runtime
+ * captured a candidate, `harness/capture.ts`): the same WAITING pause as an
+ * approval, because a file review is the other thing the workflow waits on
+ * and reinvokes for. A review WINS over the terminal the engine reported:
+ * edits on the user's disk must reach review whatever else happened, and a
+ * FAILED or TERMINATED execution never reinvokes, so the terminal is
+ * DEFERRED — its ROWS ride the transcript now (the failure copy, the
+ * tool-call-limit copy; an `engine`-surface failure has none), never its
+ * phase, its `error` or its completion stamp, and the resume's reconcile
+ * settles the execution COMPLETED as every pure file-review resume does
+ * (`fileReviewResolvedArm`). Until S3 M4 only the Cursor harness behaved so,
+ * and only because its boundary ran before it consulted its engine's
+ * result; the deep-agent wrote FAILED with the edits applied and unreviewed.
+ * Stated cost: the cloud's `status.error` prefix match for a tool-call limit
+ * does not fire when that limit left edits (Q-M4-2).
+ */
+export function awaitingReviewArm(deferred?: TerminalArm): TerminalArm {
+  return {
+    phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+    rows: deferred?.rows ?? [],
+    completes: false,
+    disposition: RETURN,
+  };
+}
+
 /** The control plane answered STOP. A clean COMPLETED early exit. */
 export function platformStopArm(): TerminalArm {
   return {
@@ -177,17 +229,6 @@ export function workspaceLockTimeoutArm(error: WorkspaceLockTimeoutError): Termi
   };
 }
 
-/** An adjudicated irreversible action (shell / MCP) was REJECTed. */
-export function rejectedByUserArm(): TerminalArm {
-  return {
-    phase: ExecutionPhase.EXECUTION_FAILED,
-    error: TERMINAL_COPY.rejectedByUser.error,
-    rows: [TERMINAL_COPY.rejectedByUser.row],
-    completes: true,
-    disposition: RETURN,
-  };
-}
-
 /**
  * A pure file-review resume: the agent already finished its turn during
  * capture, so keeping or discarding a change never re-prompts it