@stigmer/runner 3.40.1 → 3.41.0

package/src/activities/execute-deep-agent/platform-route.ts

@@ -30,9 +30,18 @@
  *
  * WHEN IT IS MOUNTED
  * ------------------
- * On the turns where the workspace link points at the platform dir — the
- * turns whose skill or attachment phase made it — so what the agent can
- * reach is exactly what the link exposes to the shell on the same turn.
+ * On every turn: `.stigmer/` is the platform's name whether or not the turn
+ * mounted anything, so a write there never reaches the workspace. Before
+ * #1123 the route existed only on linked turns, and a write under `.stigmer/`
+ * on any other turn made a real directory in the user's tree that the next
+ * link displaced. What the route exposes follows the link, so the file tools
+ * reach exactly what the shell reaches on the same turn:
+ * - on a turn whose skill or attachment phase made the link, the platform dir
+ *   ({@link PlatformContentBackend});
+ * - on any other turn, nothing ({@link NoPlatformContentBackend}): the dir
+ *   still holds earlier turns' skills and inputs, which this turn's shell
+ *   cannot reach, so the file tools must not either. The root listing then
+ *   leaves `.stigmer/` out, as the tree does.
  * The link itself stays: shell commands (a skill's own scripts among them)
  * run in the workspace and resolve `.stigmer/…` through it.
  */
@@ -40,10 +49,16 @@
 import { CompositeBackend, FilesystemBackend } from "deepagents";
 import type {
   AnyBackendProtocol,
+  BackendProtocolV2,
   DeleteResult,
   EditResult,
+  FileDownloadResponse,
   FileUploadResponse,
+  GlobResult,
+  GrepResult,
   LsResult,
+  ReadRawResult,
+  ReadResult,
   WriteResult,
 } from "deepagents";
 import { STIGMER_LOCAL_STATE_DIR, stigmerSymlinkPointsAt } from "../../shared/workspace/stigmer-link.js";
@@ -51,14 +66,25 @@ import { STIGMER_LOCAL_STATE_DIR, stigmerSymlinkPointsAt } from "../../shared/wo
 /** The route prefix, with the trailing slash `CompositeBackend` needs to match `/.stigmer/x` but never `/.stigmerx`. */
 export const PLATFORM_ROUTE_PREFIX = `/${STIGMER_LOCAL_STATE_DIR}/`;
 
+/** The path as the agent named it: the route hands its backend the path with the prefix stripped. */
+function agentPath(routedPath: string): string {
+  return `${PLATFORM_ROUTE_PREFIX.slice(0, -1)}${routedPath}`;
+}
+
 function readOnly(routedPath: string): string {
-  const agentPath = `${PLATFORM_ROUTE_PREFIX.slice(0, -1)}${routedPath}`;
   return (
-    `Error: '${agentPath}' is platform content (skills, attached inputs, the approved plan) ` +
+    `Error: '${agentPath(routedPath)}' is platform content (skills, attached inputs, the approved plan) ` +
     "and is read-only; write your own files in the workspace"
   );
 }
 
+function noPlatformContent(routedPath: string): string {
+  return (
+    `Error: '${agentPath(routedPath)}' does not exist: this turn has no platform content ` +
+    "(no skills or attached inputs)"
+  );
+}
+
 /** The platform dir, virtual-rooted like every native backend, refusing every mutation. */
 export class PlatformContentBackend extends FilesystemBackend {
   constructor(platformDir: string) {
@@ -83,17 +109,80 @@ export class PlatformContentBackend extends FilesystemBackend {
 }
 
 /**
- * The workspace backend with the platform mounted at {@link PLATFORM_ROUTE_PREFIX}.
+ * The `.stigmer/` route on a turn that exposes no platform content: nothing
+ * to read, list or find, and every mutation refused with the same message
+ * the platform dir's route gives. It stands on no filesystem, so it cannot
+ * create or reveal anything, and `ls` answers "does not exist" rather than
+ * an empty listing because the root listing leaves `.stigmer/` out.
+ */
+export class NoPlatformContentBackend implements BackendProtocolV2 {
+  ls(path: string): LsResult {
+    return { error: noPlatformContent(path) };
+  }
+
+  read(filePath: string): ReadResult {
+    return { error: noPlatformContent(filePath) };
+  }
+
+  readRaw(filePath: string): ReadRawResult {
+    return { error: noPlatformContent(filePath) };
+  }
+
+  grep(): GrepResult {
+    return { matches: [] };
+  }
+
+  glob(): GlobResult {
+    return { files: [] };
+  }
+
+  write(filePath: string): WriteResult {
+    return { error: readOnly(filePath) };
+  }
+
+  edit(filePath: string): EditResult {
+    return { error: readOnly(filePath) };
+  }
+
+  delete(filePath: string): DeleteResult {
+    return { error: readOnly(filePath) };
+  }
+
+  uploadFiles(files: Array<[string, Uint8Array]>): FileUploadResponse[] {
+    return files.map(([path]) => ({ path, error: "permission_denied" }));
+  }
+
+  downloadFiles(paths: string[]): FileDownloadResponse[] {
+    return paths.map((path) => ({ path, content: null, error: "file_not_found" }));
+  }
+}
+
+/**
+ * The workspace backend with `.stigmer/` routed to {@link PLATFORM_ROUTE_PREFIX}'s
+ * backend for this turn.
  *
  * One behaviour differs from the stock router: listing `/`. The composite
- * adds each route to the root listing, and the workspace backend already
- * lists `.stigmer/` by following the link, so the stock listing names the
- * same directory twice; the root listing is de-duplicated by path.
+ * adds each route to the root listing whatever the route holds. With the
+ * platform exposed, the workspace backend also lists `.stigmer/` by following
+ * the link, so the stock listing names the same directory twice and is
+ * de-duplicated by path. With nothing exposed, `.stigmer/` is left out of the
+ * root listing altogether: the route has nothing to show, and a real
+ * `.stigmer` the workspace may hold is unreachable behind it.
  */
 export class PlatformRoutedBackend extends CompositeBackend {
+  private readonly exposesPlatform: boolean;
+
+  constructor(backend: AnyBackendProtocol, platform: PlatformContentBackend | NoPlatformContentBackend) {
+    super(backend, { [PLATFORM_ROUTE_PREFIX]: platform });
+    this.exposesPlatform = platform instanceof PlatformContentBackend;
+  }
+
   override async ls(path: string): Promise<LsResult> {
     const result = await super.ls(path);
     if (path !== "/" || !result.files) return result;
+    if (!this.exposesPlatform) {
+      return { ...result, files: result.files.filter((entry) => entry.path !== PLATFORM_ROUTE_PREFIX) };
+    }
     const seen = new Set<string>();
     return {
       ...result,
@@ -114,21 +203,21 @@ export interface PlatformRouteOptions {
 }
 
 /**
- * Mount the platform route over `backend` when this turn exposes platform
- * content; otherwise hand `backend` back unchanged. `execute` and the
- * sandbox identity stay the workspace backend's (`CompositeBackend` delegates
- * both to its default), so a shell-capable graph keeps its `execute` tool and
- * a plan-mode graph stays without one.
+ * Mount the `.stigmer/` route over `backend` for this turn: the platform dir
+ * when the workspace link points at it, the empty route otherwise. Only a
+ * session without a platform dir gets `backend` back unchanged. `execute`
+ * and the sandbox identity stay the workspace backend's (`CompositeBackend`
+ * delegates both to its default), so a shell-capable graph keeps its
+ * `execute` tool and a plan-mode graph stays without one.
  */
 export async function mountPlatformRoute(
   backend: AnyBackendProtocol,
   options: PlatformRouteOptions,
 ): Promise<AnyBackendProtocol> {
   const { workspaceDir, platformDir } = options;
-  if (platformDir === undefined || !(await stigmerSymlinkPointsAt(workspaceDir, platformDir))) {
-    return backend;
-  }
-  return new PlatformRoutedBackend(backend, {
-    [PLATFORM_ROUTE_PREFIX]: new PlatformContentBackend(platformDir),
-  });
+  if (platformDir === undefined) return backend;
+  const platform = (await stigmerSymlinkPointsAt(workspaceDir, platformDir))
+    ? new PlatformContentBackend(platformDir)
+    : new NoPlatformContentBackend();
+  return new PlatformRoutedBackend(backend, platform);
 }

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

@@ -71,7 +71,7 @@ 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";
@@ -436,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
       ? {
@@ -546,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(

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(", ");
+}