@stigmer/runner 3.40.0 → 3.41.0

package/src/activities/execute-deep-agent/streaming-side-effects.ts

@@ -16,8 +16,17 @@
  * Until #1096 the same correlation also fed the write-back
  * coordinator's per-file commit (`onFileModified`); write-back is
  * finalize-only now, the turn runtime's, so publishing is this trigger's one
- * effect. The loop (`turn-stream.ts`) drains {@link pendingPublishPromises}
- * in the settle.
+ * effect.
+ *
+ * One instance per turn, owned by the turn's transcript
+ * (`turn-stream.ts` `createDeepAgentTranscript`) and not by the stream loop,
+ * so the in-flight publishes outlive a stream that throws: the settle
+ * drains them before its safety net, and the turn's `finally`
+ * (`turn.ts`) drains them on every exit, a thrown turn included, before the
+ * runtime writes the terminal status (stigmer#1116). Until then the loop
+ * built this and handed the list out only on its return values, so a turn
+ * that threw left its uploads to land on a status already persisted for the
+ * last time.
  */
 
 import type { TranscriptEvent } from "../../harness/transcript/events.js";
@@ -33,12 +42,26 @@ export class StreamingSideEffects {
   private readonly inputCache = new Map<string, CachedToolInput>();
   private readonly inlinePublisher: InlinePublisher | undefined;
 
-  readonly pendingPublishPromises: Promise<void>[] = [];
+  private readonly pending: Promise<void>[] = [];
 
   constructor(opts: { inlinePublisher?: InlinePublisher }) {
     this.inlinePublisher = opts.inlinePublisher;
   }
 
+  /** The publishes fired so far, in order; each resolves (a publish logs and swallows its own failure). */
+  get pendingPublishPromises(): readonly Promise<void>[] {
+    return this.pending;
+  }
+
+  /**
+   * Wait for every publish fired so far to land on the status. Idempotent:
+   * a second call over settled publishes returns at once. Bounded by the
+   * artifact storage's own per-call timeouts, as every drain has been.
+   */
+  async drainPublishes(): Promise<void> {
+    if (this.pending.length > 0) await Promise.allSettled(this.pending);
+  }
+
   onEvent(event: TranscriptEvent): void {
     if (!this.inlinePublisher) return;
 
@@ -54,7 +77,7 @@ export class StreamingSideEffects {
       if (!isFileModifyingTool(cached.toolName)) return;
       const filePath = extractFilePath(cached.input);
       if (!filePath) return;
-      this.pendingPublishPromises.push(this.inlinePublisher.publish(filePath));
+      this.pending.push(this.inlinePublisher.publish(filePath));
     }
   }
 }

package/src/activities/execute-deep-agent/translator.ts

@@ -30,10 +30,11 @@
  * mode asks the workspace's git state, asynchronously;
  * `middleware/approval-gate.ts`), and duplicating them would be a second copy
  * of the decision — exactly the drift one writer per fact exists to end. So
- * native emits no `tool_started.gate`; the held call reaches the transcript
- * as `approval_proposed` from the post-stream seed. Until #1097 the builder
- * carried a copy of the decision that gated MCP tools only, a path
- * production never took.
+ * the held call reaches the transcript as `approval_proposed` from the
+ * post-stream seed, the one writer of a row's approval fields; the Cursor
+ * harness answers the same way since #1117. Until #1097 the builder carried a
+ * copy of the decision that gated MCP tools only, a path production never
+ * took.
  *
  * Attribution and provenance are answered for ROOT-scope calls only: a
  * sub-agent's rows carry none on either harness today (#1133), and one

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

@@ -59,12 +59,12 @@ export async function settleDeepAgentTurn(deps: DeepAgentSettleDeps): Promise<Tu
   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);
-  }
+  // Drain the publishes the stream fired (fire-and-forget completions) BEFORE
+  // the safety net: its publisher skips a file only when the file's row is
+  // already on the status, so an upload still in flight would be sent twice.
+  // The net scans tool calls for files the stream missed and runs only on a
+  // finished turn, as it always did.
+  await transcript.sideEffects.drainPublishes();
   if (stream.reason === "completed") {
     try {
       await autoPublishWrittenFiles(status, transcript.publisher);

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

@@ -67,10 +67,11 @@ import { buildChatModel } from "../../shared/model-client.js";
 import { graphThinks, toAnthropicThinking } from "../../shared/thinking-mode.js";
 import { isUnattendedApprovalMode, type MergedToolPolicy } from "../../shared/approval-policy.js";
 import type { ToolApprovalCategory } from "../../shared/tool-kind.js";
-import { alsoAvailableSkillsNote, selectSkillsForPrompt, visionPromptInfoOf } from "../../shared/prompt-sections.js";
+import { visionPromptInfoOf } from "../../shared/prompt-sections.js";
+import { findApprovedPlanPath } from "../../shared/implement-plan-prompt.js";
 import type { RecalledMemoriesContent } from "../../shared/recalled-memories.js";
 import { toLangChainImageBlocks } from "../../shared/attachment-vision.js";
-import { resolveRecursionLimit, UNBOUNDED_ADVISORY_RECURSION_LIMIT } from "../../shared/tool-rounds.js";
+import { backstopRecursionLimit, resolveToolRoundLimit } from "../../shared/tool-rounds.js";
 import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
 import { CasCaptureObserver } from "./cas-capture-observer.js";
 import { createCasCaptureBackend } from "./cas-capture-backend.js";
@@ -260,25 +261,6 @@ export function readGateState(input: TurnInput, tools: DeepAgentTools): DeepAgen
   };
 }
 
-/**
- * The `## Skills` section of the root prompt: the skills the shared selection
- * highlights for this turn's message (`shared/prompt-sections.ts`
- * `selectSkillsForPrompt`: every skill below the threshold, the relevant ones
- * at and above it), rendered with this engine's activation protocol, plus —
- * when the selection left any out — an `### Also Available` note naming them
- * (the sentence is the shared, tool-neutral one; the heading is this
- * harness's markdown framing).
- */
-export function renderRootSkillsSection(input: TurnInput): string {
-  const { highlighted, alsoAvailable } = selectSkillsForPrompt(input.execution.spec?.message ?? "", input.skills.root);
-  if (alsoAvailable.length === 0) return renderSkillsSection(highlighted);
-  console.log(
-    `[turn-setup] Skill relevance filter: ${highlighted.length} included, ` +
-    `${alsoAvailable.length} excluded: ${alsoAvailable.join(", ")}`,
-  );
-  return renderSkillsSection(highlighted) + "\n### Also Available\n\n" + alsoAvailableSkillsNote(alsoAvailable) + "\n";
-}
-
 /**
  * The system prompt over the runtime's resolved record: every input the
  * builder renders is read from `TurnInput` here, in one place, so the mapping
@@ -287,6 +269,12 @@ export function renderRootSkillsSection(input: TurnInput): string {
  * that is not on the record is the memoized memory selection, which the
  * caller awaits (the runtime stamps the report on the status the first time
  * it is pulled, before this turn's first persist).
+ *
+ * Nothing here reads the turn's message or payload: the system prompt is the
+ * session's (`prompt-builder.ts` says why), so every mounted skill is
+ * described and the turn's files ride its message (`composeTurnMessage`).
+ * The approved plan's path is the one fact taken from the attachments, and
+ * only on a build-from-plan turn, where the mode already changes the prompt.
  */
 export function composeSystemPrompt(input: TurnInput, recalledMemories: RecalledMemoriesContent | undefined): string {
   const spec = input.execution.spec!;
@@ -296,19 +284,17 @@ export function composeSystemPrompt(input: TurnInput, recalledMemories: Recalled
     instructions: input.blueprint.instructions,
     provisionResults: input.workspace.provision.provisionResults,
     containerRoot: primaryDir,
-    skillsPromptSection: renderRootSkillsSection(input),
+    skillsPromptSection: renderSkillsSection(input.skills.root),
     // "" (nothing sendable) threads as undefined: the tool alone still serves
     // text sends inside a 24-hour window (DD-006 D6).
     channelTemplatesPromptSection: input.mcp.channelMessaging.length > 0
       ? formatChannelTemplatesSection(input.mcp.channelMessaging) || undefined
       : undefined,
-    workspaceFileRefs: spec.workspaceFileRefs ?? [],
-    workspaceRoot: primaryDir,
-    inputFiles: input.attachments.results,
-    vision: visionPromptInfoOf(input.attachments),
-    downloadUrlKind: input.artifactStorage?.downloadUrlKind,
     interactionMode: execConfig?.interactionMode,
     buildFromPlan: execConfig?.buildFromPlan,
+    ...(execConfig?.buildFromPlan
+      ? { approvedPlanPath: findApprovedPlanPath(input.attachments.results.map((f) => f.relativePath)) }
+      : {}),
     contextBridge: input.standing.contextBridge,
     senderIdentity: input.standing.senderIdentity,
     sessionContext: input.standing.sessionContext,
@@ -317,6 +303,25 @@ export function composeSystemPrompt(input: TurnInput, recalledMemories: Recalled
   });
 }
 
+/**
+ * The turn's user message over the runtime's resolved record: what the user
+ * typed, with this turn's payload (its input files and referenced paths) and
+ * the conversation catchup composed around it (`prompt-builder.ts`
+ * `composeUserMessage`). The twin of `composeSystemPrompt` for the turn's
+ * half, so the goldens pin this mapping and not a copy of it.
+ */
+export function composeTurnMessage(input: TurnInput): string {
+  const spec = input.execution.spec!;
+  return composeUserMessage({
+    message: spec.message,
+    conversationCatchup: input.standing.conversationCatchup,
+    inputFiles: input.attachments.results,
+    vision: visionPromptInfoOf(input.attachments),
+    downloadUrlKind: input.artifactStorage?.downloadUrlKind,
+    workspaceFileRefs: spec.workspaceFileRefs ?? [],
+  });
+}
+
 /**
  * Build the engine: the model, the middleware stack with the gate, the
  * tools, the compiled sub-agents, the system prompt and `createDeepAgent`.
@@ -431,10 +436,10 @@ export async function buildEngine(
     : null;
 
   const maxCostUsd = execConfig?.maxCostUsd ?? 0;
-  const recursionLimit = resolveRecursionLimit(execConfig?.maxToolRounds);
+  const toolRoundLimit = resolveToolRoundLimit(execConfig?.maxToolRounds);
   const { middleware, costAdvisory } = buildMiddlewareStack({
     loopDetection: { historySize: 20, consecutiveThreshold: 7, totalThreshold: 20 },
-    executionBudget: { recursionLimit: recursionLimit ?? UNBOUNDED_ADVISORY_RECURSION_LIMIT, warningPct: 80 },
+    executionBudget: { maxToolRounds: toolRoundLimit, warningPct: 80 },
     toolTruncation: { maxChars: execConfig?.maxToolResultChars || 30_000 },
     costAdvisory: maxCostUsd > 0
       ? {
@@ -541,10 +546,10 @@ export async function buildEngine(
 
   const langgraphConfig: Record<string, unknown> = {
     configurable: { thread_id: input.threadId },
-    // Hard enforcement of max_tool_rounds (null = unlimited): when the graph
-    // exhausts this, the stream throws GraphRecursionError and the adapter
-    // ends the turn `tool_call_limit` with the work checkpointed.
-    ...(recursionLimit !== null ? { recursionLimit } : {}),
+    // max_tool_rounds is enforced by the execution budget middleware, round
+    // by round; this is only its backstop against a graph that loops without
+    // calling the model (`shared/tool-rounds.ts`). Unset = unlimited = none.
+    ...(toolRoundLimit !== null ? { recursionLimit: backstopRecursionLimit(toolRoundLimit) } : {}),
   };
 
   console.log(
@@ -577,9 +582,10 @@ export async function buildEngine(
  * What the graph is invoked with. The checkpoint is read once (on the
  * durable http saver an extra `getState` is a network round-trip): pending
  * interrupts that the runtime's decisions answer make a `Command(resume)`;
- * anything else is the turn's user message — the conversation catchup
- * framed before it (cloud DD-006; in the USER MESSAGE so it enters the
- * checkpointer with the turn), the structured-output contract appended, and
+ * anything else is the turn's user message — this turn's payload and the
+ * conversation catchup framed before it (`composeTurnMessage`; in the USER
+ * MESSAGE so it enters the checkpointer with the turn and the system prompt
+ * stays the session's), the structured-output contract appended, and
  * the inline images FIRST as content blocks when the turn carries any (per
  * Anthropic's images-before-text guidance; a plain string otherwise).
  */
@@ -590,8 +596,7 @@ export async function composeGraphInput(input: TurnInput, engine: DeepAgentEngin
     return { kind: "resume", command: resume.graphInput };
   }
 
-  const spec = input.execution.spec!;
-  let userMessage = composeUserMessage(spec.message, input.standing.conversationCatchup);
+  let userMessage = composeTurnMessage(input);
   if (engine.hasStructuredOutput) {
     userMessage += `\n\n---\nIMPORTANT: When your analysis is complete, provide your findings as structured output matching the required schema. The system will capture your structured response automatically.`;
   }

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

@@ -89,8 +89,6 @@ export interface DeepAgentStreamResult {
   readonly eventsProcessed: number;
   /** The graph's final state (`structuredResponse` rides it); absent unless the stream completed and the output resolved in time. */
   readonly runOutput: Record<string, unknown> | undefined;
-  /** Inline publishes fired mid-turn, drained by the settle. */
-  readonly pendingPublishPromises: readonly Promise<void>[];
 }
 
 /**
@@ -98,14 +96,19 @@ export interface DeepAgentStreamResult {
  * the engine's events into canonical ones (over the gate's posture, so every
  * tool start carries its attribution and gate answer), and the publisher
  * that registers artifacts on the runtime's builder (`sink.transcript`, so
- * a published artifact still dirties the next persist). The builder itself
- * is the runtime's, one per turn, and is read from the sink where it is
- * needed. Built by the adapter's turn once and shared by the stream and the
- * settle.
+ * a published artifact still dirties the next persist) and checks the rows
+ * already on `sink.status` before uploading, so an earlier turn's unchanged
+ * file is not sent again; and the side effects that fire the publisher
+ * mid-turn and hold its in-flight uploads until they are drained. The
+ * builder itself is the runtime's, one per turn, and is read from the sink
+ * where it is needed. Built by the adapter's turn once and shared by the
+ * stream, the settle and the turn's `finally`, which drains the publishes
+ * on every exit (`streaming-side-effects.ts`).
  */
 export interface DeepAgentTranscript {
   readonly translator: DeepAgentTranslator;
   readonly publisher: InlinePublisher;
+  readonly sideEffects: StreamingSideEffects;
 }
 
 export function createDeepAgentTranscript(
@@ -119,9 +122,10 @@ export function createDeepAgentTranscript(
     workspaceBackend: workspace.backend,
     artifactStorage: input.artifactStorage,
     artifacts: sink.transcript,
+    record: sink.status,
     executionId: input.executionId,
   });
-  return { translator, publisher };
+  return { translator, publisher, sideEffects: new StreamingSideEffects({ inlinePublisher: publisher }) };
 }
 
 /**
@@ -166,12 +170,11 @@ export interface DeepAgentStreamDeps {
 export async function consumeDeepAgentStream(deps: DeepAgentStreamDeps): Promise<DeepAgentStreamResult> {
   const { input, sink, engine, graphInput, transcript } = deps;
   const { executionId } = input;
-  const { translator, publisher } = transcript;
+  const { translator, sideEffects } = transcript;
   const builder = sink.transcript;
 
   const scheduler = new StreamingUpdateScheduler(loadStreamingConfig());
   const recorder = createV3EventRecorder(executionId, process.env.V3_EVENT_RECORD_DIR);
-  const sideEffects = new StreamingSideEffects({ inlinePublisher: publisher });
   const abortController = new AbortController();
   let forceAbort: ReturnType<typeof setTimeout> | undefined;
   const abortRun = (): void => {
@@ -188,12 +191,7 @@ export async function consumeDeepAgentStream(deps: DeepAgentStreamDeps): Promise
   /** The stop, taken at a boundary: abort the run now and settle. */
   const interrupted = (): DeepAgentStreamResult => {
     abortRun();
-    return {
-      reason: "interrupted",
-      eventsProcessed,
-      runOutput: undefined,
-      pendingPublishPromises: sideEffects.pendingPublishPromises,
-    };
+    return { reason: "interrupted", eventsProcessed, runOutput: undefined };
   };
 
   try {
@@ -254,18 +252,13 @@ export async function consumeDeepAgentStream(deps: DeepAgentStreamDeps): Promise
 
     if (builder.awaitingApproval) {
       console.log(`[turn-stream] execution=${executionId} stream ended at a gate; awaiting approval`);
-      return {
-        reason: "awaiting_approval",
-        eventsProcessed,
-        runOutput: undefined,
-        pendingPublishPromises: sideEffects.pendingPublishPromises,
-      };
+      return { reason: "awaiting_approval", eventsProcessed, runOutput: undefined };
     }
 
     console.log(`[turn-stream] execution=${executionId} stream finished — processed ${eventsProcessed} events`);
     const runOutput = await extractRunOutput(run, executionId);
     sink.recordActivity();
-    return { reason: "completed", eventsProcessed, runOutput, pendingPublishPromises: sideEffects.pendingPublishPromises };
+    return { reason: "completed", eventsProcessed, runOutput };
   } finally {
     sink.stopSignal.removeEventListener("abort", onStop);
     if (forceAbort !== undefined) clearTimeout(forceAbort);

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

@@ -24,7 +24,10 @@
  * other exception — a provider error unwrapped from LangChain's middleware
  * wrapper, an MCP connect failure, an empty stream — is `failed` on the
  * `internal` surface with `describeExecutionError`'s sentence as
- * `status.error` whole. Never branches on why `stopSignal`
+ * `status.error` whole, and it returns only after the inline publishes the
+ * turn already fired have landed on the status (the drain in the `finally`),
+ * so an artifact the agent wrote before the throw is on the terminal status
+ * the runtime then persists (stigmer#1116). Never branches on why `stopSignal`
  * aborted, never writes a phase or a terminal copy, never imports
  * `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
  *
@@ -44,7 +47,7 @@ import type { TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
 import type { McpConnectionResult } from "../../shared/mcp-manager.js";
 import { tryInferProvider } from "../../shared/llm-proxy.js";
 import { describeExecutionError } from "../../shared/model-error.js";
-import { isGraphRecursionError } from "../../shared/tool-rounds.js";
+import { isToolCallBudgetStop } from "../../shared/tool-rounds.js";
 import {
   buildDeepAgentWorkspace,
   buildEngine,
@@ -55,7 +58,7 @@ import {
   resolveModelName,
   type DeepAgentAdapterConfig,
 } from "./turn-setup.js";
-import { consumeDeepAgentStream, createDeepAgentTranscript } from "./turn-stream.js";
+import { consumeDeepAgentStream, createDeepAgentTranscript, type DeepAgentTranscript } from "./turn-stream.js";
 import { settleDeepAgentTurn } from "./turn-settle.js";
 
 export async function runDeepAgentTurn(input: TurnInput, sink: TurnSink, config: DeepAgentAdapterConfig): Promise<TurnOutcome> {
@@ -64,6 +67,7 @@ export async function runDeepAgentTurn(input: TurnInput, sink: TurnSink, config:
   let checkpointer: BaseCheckpointSaver | undefined;
   let connection: McpConnectionResult | undefined;
   let modelName: string | undefined;
+  let transcript: DeepAgentTranscript | undefined;
 
   try {
     modelName = await resolveModelName(input);
@@ -83,12 +87,16 @@ export async function runDeepAgentTurn(input: TurnInput, sink: TurnSink, config:
     const graphInput = await composeGraphInput(input, engine);
     sink.recordActivity();
 
-    const transcript = createDeepAgentTranscript(input, sink, engine, workspace);
+    transcript = createDeepAgentTranscript(input, sink, engine, workspace);
     const stream = await consumeDeepAgentStream({ input, sink, engine, graphInput, transcript });
     return await settleDeepAgentTurn({ input, sink, engine, transcript, stream });
   } catch (err) {
     return classifyThrown(err, input, config, modelName);
   } finally {
+    // First, on every exit: the runtime persists the terminal status as soon
+    // as this returns, so an upload still in flight must land before then.
+    // A settled turn already drained in its settle; this is then a no-op.
+    await transcript?.sideEffects.drainPublishes();
     await closeQuietly(input.executionId, "MCP connection", () => connection?.client.close());
     // Only the durable sqlite saver holds an OS handle (an open DB file);
     // memory/http savers have no close(), so this is duck-typed.
@@ -98,8 +106,9 @@ export async function runDeepAgentTurn(input: TurnInput, sink: TurnSink, config:
 }
 
 /**
- * An exception that escaped the turn, classified. The graph's recursion
- * limit is the budget's own signal (`shared/tool-rounds.ts`), not an error:
+ * An exception that escaped the turn, classified. The tool-call budget's stop
+ * (the execution budget's round limit, or its recursion-limit backstop;
+ * `shared/tool-rounds.ts`) is the budget's own signal, not an error:
  * the work is checkpointed and the conversation continues on the next
  * message. Anything else is described by `describeExecutionError` (a model
  * error arrives MiddlewareError-wrapped with raw provider prose and is
@@ -108,7 +117,7 @@ export async function runDeepAgentTurn(input: TurnInput, sink: TurnSink, config:
  * broke.
  */
 function classifyThrown(err: unknown, input: TurnInput, config: DeepAgentAdapterConfig, modelName: string | undefined): TurnOutcome {
-  if (isGraphRecursionError(err)) {
+  if (isToolCallBudgetStop(err)) {
     console.log(`ExecuteDeepAgent reached the tool-call limit: execution=${input.executionId}`);
     return { kind: "tool_call_limit" };
   }

package/src/activities/workflow-event-activities.ts

@@ -337,6 +337,8 @@ export function toProtoEvent(desc: WorkflowEventDescriptor): WorkflowExecutionEv
             : undefined,
           comment: desc.comment,
           waitDurationMs: BigInt(desc.waitDurationMs),
+          outcome: desc.outcome,
+          autoResolved: desc.autoResolved,
         }),
       };
       break;

package/src/config.ts

@@ -113,6 +113,15 @@ export interface Config {
    * and shared/conversation-attachment.ts.
    */
   readonly mcpBridgeEndpoint: string | null;
+  /**
+   * The Stigmer server's public address (STIGMER_MCP_PUBLIC_ENDPOINT), which
+   * the server hands every sandbox it provisions or an operator names to a
+   * runner started by hand. When set, it fills a missing
+   * STIGMER_SERVER_ADDRESS for any MCP server that declares the key; null
+   * leaves a remote server's address unfilled. See
+   * shared/platform-server-address.ts.
+   */
+  readonly mcpPublicEndpoint: string | null;
   /**
    * The Cursor API key for direct mode (authenticates with Cursor directly).
    * In proxy mode this is a placeholder (`"proxy-managed"` unless the operator
@@ -232,6 +241,7 @@ export function loadConfig(): Config {
   const stigmerTokenRef: TokenRef = { current: stigmerTokenValue ?? null };
 
   const mcpBridgeEndpoint = process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null;
+  const mcpPublicEndpoint = process.env.STIGMER_MCP_PUBLIC_ENDPOINT || null;
 
   // In proxy mode the SDK's API key is the control-plane credential, which the
   // Cursor adapter reads from the ref per turn (execute-cursor/turn-setup.ts);
@@ -285,6 +295,7 @@ export function loadConfig(): Config {
     stigmerBackendEndpoint,
     stigmerTokenRef,
     mcpBridgeEndpoint,
+    mcpPublicEndpoint,
     cursorApiKey,
     workspaceRootDir,
     mode,

package/src/exit-backstop.ts

@@ -0,0 +1,97 @@
+/**
+ * The exit backstop for static and pool modes: once the runner's own
+ * shutdown has finished (worker drained, harnesses released, Temporal
+ * connection closed, OTel flushed), the process must end within a named
+ * bound, and when it has to be MADE to end, the log names what kept it
+ * alive.
+ *
+ * Static and pool modes end when the Node event loop drains. That is the
+ * normal path and it stays the normal path: a healthy runner exits in
+ * milliseconds on its own. The failure it guards against is one leaked
+ * handle — a timer, a socket, a child — that outlives the worker and holds
+ * the process until the orchestrator's grace expires. One uncleared timer
+ * in our own code did exactly that to every pool-member roll for three
+ * months (issue #1008), and the next one may sit in a vendor SDK we do not
+ * own. A hosted sandbox pod's grace is ten minutes, so the cost of a leak
+ * is not bounded by anything the runner controls — until this module.
+ *
+ * Why these choices:
+ *
+ * - The timer is `unref()`'d, so arming it never keeps the process alive.
+ *   A drained loop exits naturally and the timer dies with it; the
+ *   backstop only ever fires when something else is still holding the
+ *   loop. An unref'd timer is also absent from
+ *   `process.getActiveResourcesInfo()`, so the line never names the
+ *   backstop itself.
+ * - The bound sits above the conformance harness's slow-exit threshold
+ *   (2 s, `test/conformance/src/harness/runner-process.ts`), so a leak is
+ *   still reported there as a slow exit instead of being hidden under it,
+ *   and far below the harness's 30 s and the hosted 10-minute graces.
+ * - A forced exit exits 0. By the time the backstop is armed the drain and
+ *   the flush have completed; the lingering handle is a defect named in the
+ *   log, not a failed shutdown, and a non-zero code would make Kubernetes
+ *   and the desktop host report a crash for a clean stop.
+ * - It is armed only after everything the shutdown awaits. Work that
+ *   nobody awaits (a fire-and-forget promise) is the only thing it can cut;
+ *   if such work matters at exit, the fix is to await it, and this line
+ *   names it the first time it happens.
+ *
+ * Manager mode does not use this: it is driven by its host over stdin and
+ * exits at once after its shutdown (issue #177, `main.ts`).
+ */
+
+/** How long the process may outlive its own completed shutdown before it is made to exit. */
+export const EXIT_BACKSTOP_MS = 5_000;
+
+export interface ExitBackstopOptions {
+  /** The bound; defaults to {@link EXIT_BACKSTOP_MS}. */
+  readonly boundMs?: number;
+  /** Ends the process; defaults to `process.exit`. */
+  readonly exit?: (code: number) => void;
+  /** Names what still holds the loop; defaults to `process.getActiveResourcesInfo`. */
+  readonly activeResources?: () => string[];
+  /** Writes the forced-exit line; defaults to `console.warn`. */
+  readonly log?: (line: string) => void;
+}
+
+/**
+ * Arm the backstop. Call it once, after the mode's shutdown has returned.
+ * Returns the armed timer so a test can observe that it does not hold the
+ * loop; production callers ignore it.
+ */
+export function armExitBackstop(
+  options: ExitBackstopOptions = {},
+): ReturnType<typeof setTimeout> {
+  const boundMs = options.boundMs ?? EXIT_BACKSTOP_MS;
+  const exit = options.exit ?? ((code: number) => process.exit(code));
+  const activeResources = options.activeResources ?? (() => process.getActiveResourcesInfo());
+  const log = options.log ?? ((line: string) => console.warn(line));
+
+  const timer = setTimeout(() => {
+    log(
+      `[runner] Process still alive ${boundMs}ms after shutdown; forcing exit. ` +
+        `Active resources: ${describeResources(activeResources())}`,
+    );
+    exit(0);
+  }, boundMs);
+  timer.unref();
+  return timer;
+}
+
+/**
+ * `["Timeout", "TCPSocketWrap", "TCPSocketWrap"]` → `"TCPSocketWrap×2, Timeout×1"`:
+ * grouped and sorted, so the same leak reads the same on every exit.
+ */
+export function describeResources(resources: readonly string[]): string {
+  if (resources.length === 0) {
+    return "none reported";
+  }
+  const counts = new Map<string, number>();
+  for (const resource of resources) {
+    counts.set(resource, (counts.get(resource) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([resource, count]) => `${resource}×${count}`)
+    .join(", ");
+}

package/src/harness/README.md

@@ -200,11 +200,10 @@ Every hit falls into one of three classes:
 | `apis/ai/stigmer/agentic/agentexecution/v1/enum.proto`                                                                                                                         | A comment on tool-name casing per harness.                                                                                                                                                                                                                                                                                    |
 | `backend/README.md`                                                                                                                                                            | Lists the harnesses and the SDK behind each.                                                                                                                                                                                                                                                                                  |
 | `client-apps/desktop/scripts/stage-runner-slim.sh`, `client-apps/desktop/scripts/macos-codesign-tree.sh`                                                                       | Stage and sign the vendor SDKs' native helpers for the desktop app; a harness whose SDK ships one touches both.                                                                                                                                                                                                               |
-| `sdk/react/src/models/harness.ts`                                                                                                                                              | The SDK hub: `HarnessOption`, `HARNESS_META`, `HARNESS_LABELS`, `HARNESS_OPTIONS`, `DEFAULT_HARNESS`, `toProtoHarness`, `fromProtoHarness`. `HarnessOption` carries four values beyond the proto's two; `toProtoHarness` maps them to `NATIVE` through its `default` arm.                                                     |
-| `sdk/react/src/models/HarnessSelector.tsx`                                                                                                                                     | `OPTIONS`, the two selectable values.                                                                                                                                                                                                                                                                                         |
-| `sdk/react/src/models/ModelSelector.tsx`                                                                                                                                       | A Cursor-only thinking rule, and the filter that hides the extra options by name.                                                                                                                                                                                                                                             |
+| `sdk/react/src/models/harness.ts`                                                                                                                                              | The SDK hub: `HarnessOption`, `HARNESS_META`, `HARNESS_LABELS`, `HARNESS_OPTIONS`, `DEFAULT_HARNESS`, `isHarnessOption`, `toProtoHarness`, `fromProtoHarness`, all read from one option-to-enum table; its reverse is typed over the whole enum, so a new member fails the SDK's typecheck here.                              |
+| `sdk/react/src/models/HarnessSelector.tsx`                                                                                                                                     | The premium mark on the Cursor segment; the segments themselves come from `HARNESS_OPTIONS`.                                                                                                                                                                                                                                  |
+| `sdk/react/src/models/ModelSelector.tsx`                                                                                                                                       | A Cursor-only thinking rule.                                                                                                                                                                                                                                                                                                  |
 | `sdk/react/src/identity-account/AccountPreferencesPanel.tsx`                                                                                                                   | One `HarnessOptionRow` per harness, placed by hand.                                                                                                                                                                                                                                                                           |
-| `sdk/react/src/identity-account/useAccountExecutionDefaults.ts`                                                                                                                | Validates the preference against the two names.                                                                                                                                                                                                                                                                               |
 | `sdk/react/src/workflow/inspector/forms/AgentCallForm.tsx`                                                                                                                     | Two radio buttons, placed by hand.                                                                                                                                                                                                                                                                                            |
 | `sdk/react/src/pricing-governance/BaselineEditor.tsx`                                                                                                                          | A select with one option per harness.                                                                                                                                                                                                                                                                                         |
 | `site/src/components/pages/pricing/ModelPricingTable.tsx`                                                                                                                      | Harness to display label.                                                                                                                                                                                                                                                                                                     |
@@ -234,7 +233,8 @@ Nothing to touch. Listed so a probe's hit here is a stop, not a lead.
   (read the session's harness or name the activities in prose).
 - The React SDK: `sdk/react/src/models/registry.ts`,
   `sdk/react/src/models/useModelRegistry.ts`,
-  `sdk/react/src/models/service-tier.ts`; everything under
+  `sdk/react/src/models/service-tier.ts`,
+  `sdk/react/src/identity-account/useAccountExecutionDefaults.ts`; everything under
   `sdk/react/src/channel/`, `sdk/react/src/composer/`,
   `sdk/react/src/execution/`, `sdk/react/src/schedule/`,
   `sdk/react/src/session/` (typed by the option or defaulting to one value).

package/src/harness/terminal-table.ts

@@ -11,6 +11,12 @@
  * harness once kept one function per arm (`streaming-terminal.ts`, retired
  * in #1096); since #1096 both harnesses' turns end through this one table.
  *
+ * The `error` of a FAILED arm is the failure itself, never framed: the
+ * `Execution failed:` wording belongs to the rows and to each consumer's
+ * own copy (the console's badge, the CLI's epilogue), so a consumer meets
+ * one grammar whichever arm wrote it. The interruption arms' `Execution
+ * interrupted:` errors are a different outcome, one the user resumes.
+ *
  * The throw-vs-return rule, unchanged from the orchestrator it replaces:
  *  - RETURN when a Temporal retry would only repeat the outcome — a stall
  *    would wedge again, an exhausted budget would burn again, a platform
@@ -293,21 +299,15 @@ export function failedArm(message: string, surface: FailureSurface): TerminalArm
 
 /**
  * An error the runtime caught itself, outside any adapter (a resolution
- * phase, the epilogue): the boilerplate row and the described error as the
- * details, with `status.error` carrying the `Execution failed:` prefix the
- * orchestrator's generic arm always wrote (`describeExecutionError` supplies
- * the two parts). The one arm whose `error` and details row differ, kept as
- * it was because the resolution-error golden pins both.
+ * phase, the epilogue): an `internal` failure like any adapter's, described
+ * as `[<type>] <message>` (`describeExecutionError` supplies the two parts),
+ * so `status.error` reads the same whichever side caught the fault. Until
+ * stigmer#1122 this arm alone prefixed `status.error` with `Execution
+ * failed:`, and a consumer that adds its own failure copy (the CLI's
+ * epilogue) printed the words twice.
  */
 export function unexpectedErrorArm(errorType: string, errorMessage: string): TerminalArm {
-  const described = `[${errorType}] ${errorMessage}`;
-  return {
-    phase: ExecutionPhase.EXECUTION_FAILED,
-    error: `Execution failed: ${described}`,
-    rows: [TERMINAL_COPY.internalFailure.row, `Error details: ${described}`],
-    completes: true,
-    disposition: RETURN,
-  };
+  return failedArm(`[${errorType}] ${errorMessage}`, "internal");
 }
 
 // ── Applying an arm ─────────────────────────────────────────────────────────