@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/client/token-claims.ts

@@ -0,0 +1,103 @@
+/**
+ * Read-only claim inspection for the runner's own credentials.
+ *
+ * The runner never verifies signatures — the server does that. It only needs
+ * to look at its own token's `token_type` claim to decide which credential
+ * flow applies (e.g. "do I hold an unscoped bootstrap credential that must be
+ * exchanged for a scoped one before a value fetch?"), and the
+ * attach waiter checks a pushed token's shape and expiry before it starts a
+ * runner with it (`src/attach/push.ts`). Claim names
+ * and values mirror the server's single source of truth,
+ * `StigmerTokenType` (stigmer-cloud, api-authentication).
+ */
+
+/** The `token_type` claim value of a bootstrap-minted embedded runner token. */
+export const TOKEN_TYPE_EMBEDDED_RUNNER = "embedded_runner";
+
+/** The `token_type` claim value of a session sandbox token. */
+export const TOKEN_TYPE_SANDBOX = "sandbox";
+
+/** The `token_type` claim value of a warm-pool member's pre-claim credential. */
+export const TOKEN_TYPE_POOL_SANDBOX = "pool_sandbox";
+
+const CLAIM_TOKEN_TYPE = "token_type";
+const CLAIM_SESSION_ID = "session_id";
+
+/**
+ * Decode a JWT's payload without verifying it, or undefined when the token is
+ * absent or not three dot-separated parts with a JSON object payload.
+ */
+function payloadOf(
+  token: string | null | undefined,
+): Record<string, unknown> | undefined {
+  if (!token) return undefined;
+  const parts = token.split(".");
+  if (parts.length !== 3) return undefined;
+  try {
+    const payload: unknown = JSON.parse(
+      Buffer.from(parts[1]!, "base64url").toString("utf8"),
+    );
+    return typeof payload === "object" && payload !== null && !Array.isArray(payload)
+      ? (payload as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Extract one string claim from a JWT without verifying it.
+ *
+ * Returns undefined for null/malformed tokens and for tokens without the
+ * claim — callers branch on the specific value, so "unknown" and "absent"
+ * collapse to the same answer.
+ */
+function claimOf(
+  token: string | null | undefined,
+  claim: string,
+): string | undefined {
+  const value = payloadOf(token)?.[claim];
+  return typeof value === "string" ? value : undefined;
+}
+
+/** Whether the token has a JWT's shape: three parts and a JSON object payload. */
+export function isJwtShaped(token: string | null | undefined): boolean {
+  return payloadOf(token) !== undefined;
+}
+
+/** The `exp` claim in seconds since the epoch, when the token carries a numeric one. */
+export function expiryClaimOf(token: string | null | undefined): number | undefined {
+  const value = payloadOf(token)?.exp;
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/** Extract the `token_type` claim (e.g. a user's Auth0 token has none). */
+export function tokenTypeOf(token: string | null | undefined): string | undefined {
+  return claimOf(token, CLAIM_TOKEN_TYPE);
+}
+
+/**
+ * Extract the `session_id` claim of a session-scoped token. A claimed pool
+ * member reads its post-claim identity from this on restart.
+ */
+export function sessionIdClaimOf(token: string | null | undefined): string | undefined {
+  return claimOf(token, CLAIM_SESSION_ID);
+}
+
+/** Whether the token is a bootstrap-minted `embedded_runner` credential. */
+export function isEmbeddedRunnerToken(token: string | null | undefined): boolean {
+  return tokenTypeOf(token) === TOKEN_TYPE_EMBEDDED_RUNNER;
+}
+
+/**
+ * `token` when it is a runner-class credential already scoped below the
+ * runner (a cloud sandbox's session token, a connect token): one the
+ * scoped-token exchange leaves in use rather than exchanging
+ * (`stigmer-client.ts` `acquireScopedRunnerToken`). `undefined` for an
+ * unscoped key (an operator's API key, an embedded runner's bootstrap
+ * token) and for none.
+ */
+export function scopedRunnerCredential(token: string | null | undefined): string | undefined {
+  const type = tokenTypeOf(token);
+  return token && type !== undefined && type !== TOKEN_TYPE_EMBEDDED_RUNNER ? token : undefined;
+}

package/src/config.ts

@@ -0,0 +1,378 @@
+/**
+ * Environment-based configuration for the unified runner service.
+ *
+ * Supports both ExecuteCursor and ExecuteDeepAgent activities from a single
+ * process. All values come from environment variables set by the CLI daemon,
+ * Kubernetes pod spec, or Daytona sandbox launcher.
+ *
+ * Credential modes:
+ *
+ * 1. Direct mode (local / OSS):
+ *    - CURSOR_API_KEY provided directly by the user (for Cursor harness).
+ *    - STIGMER_TOKEN is optional against a trusted-local server (it verifies
+ *      no credential) and is the runner's own API key against a self-hosted
+ *      server with sign-in on; each run's credential arrives with its
+ *      dispatch (shared/run-credential.ts).
+ *    - STIGMER_PROXY_ENDPOINT is NOT set.
+ *
+ * 2. Proxy mode (cloud / managed runners):
+ *    - STIGMER_PROXY_ENDPOINT + STIGMER_TOKEN are required.
+ *    - CURSOR_API_KEY is NOT required — the proxy injects it.
+ *    - The fetch interceptor rewrites outbound Cursor SDK requests.
+ *
+ * The credential is never held by value:
+ *
+ * The control-plane credential rotates while the process runs (the manager's
+ * `updateToken` on a pool claim or a host refresh, the static root's
+ * sandbox-token renewal), so `Config` carries it as a shared {@link TokenRef}
+ * and nothing else. Every reader resolves `ref.current` at the moment of use;
+ * a client that makes many requests over its life holds the ref and reads it
+ * per request (the artifact store, the checkpoint saver). The two roots own
+ * the writable ref; readers see it through `Readonly`, so a rotation has one
+ * writer and no copy to go stale. {@link loadConfig} is the environment
+ * boundary and is read once, by `main.ts`: the ref it returns holds the boot
+ * capture that the roots turn into the live ref (a test pins that no other
+ * module imports it). The only by-value reads are the pool boot's, where the
+ * credential the pod BOOTED with is the fact (`main.ts`).
+ *
+ * Workspace isolation:
+ *
+ * WORKSPACE_ROOT_DIR must always resolve to a directory that is NOT the
+ * runner's own app directory. Falling back to process.cwd() would expose
+ * runner internals to agents. The fallback creates an isolated directory.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+
+/**
+ * Default no-progress bound for every harness's engine stream (ms); named for
+ * the Cursor harness, its first user, and armed by the turn runtime for every
+ * engine since #1070. Larger than the shared DEFAULT_STALL_TIMEOUT_MS (120s)
+ * because opaque MCP / GUI tool calls can run for minutes while emitting no
+ * stream activity. Single source of truth
+ * for env-loaded ({@link loadConfig}) and options-mapped (runner / manager)
+ * config so the three construction sites never drift.
+ */
+export const DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS = 180_000;
+
+/**
+ * Default bound for Cursor Agent.create/Agent.resume (ms). These SDK calls
+ * have no timeout of their own; a degraded transport (dead proxy connection,
+ * stale HTTP/2 session) hangs them forever — which surfaces as an opaque
+ * Temporal heartbeat timeout minutes later instead of an actionable error.
+ * 120s comfortably covers a slow create (token exchange + workspace
+ * registration) while failing fast enough to diagnose. Single source of truth
+ * for env-loaded and options-mapped config (mirrors the stall timeout above).
+ */
+export const DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS = 120_000;
+
+// Re-exported so the runner/manager options mappers default the lock-wait
+// bound from the same constant the lock module owns (no drift across the
+// three construction sites — mirrors DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS).
+export { DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./shared/workspace/workspace-lock.js";
+import { DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./shared/workspace/workspace-lock.js";
+import { getRunnerSecret } from "./shared/runner-credential-store.js";
+import { loadTemporalConnectionConfig } from "@stigmer/temporal-codecs";
+import type { TemporalConnectionConfig } from "@stigmer/temporal-codecs";
+
+/**
+ * A shared mutable credential reference. The root that owns a credential
+ * writes `current` on every rotation; every reader resolves it at the moment
+ * of use, so one write reaches all of them (the per-request reads in the
+ * Cursor interceptors, StigmerClient, the artifact store and the checkpoint
+ * saver). `Config` hands readers a `Readonly` view: rotation has one writer.
+ */
+export interface TokenRef {
+  current: string | null;
+}
+
+export interface Config {
+  readonly taskQueue: string;
+  readonly temporalAddress: string;
+  readonly temporalNamespace: string;
+  /**
+   * TLS, mutual TLS or an API key for the Temporal connection, read from
+   * the `STIGMER_TEMPORAL_*` settings through the credential store (the
+   * API key and the client key are in its custody list, so they never
+   * stay in the environment agent tools inherit). `{}` is plaintext.
+   */
+  readonly temporalConnection: TemporalConnectionConfig;
+  readonly stigmerBackendEndpoint: string;
+  /**
+   * The control-plane credential, read per use (the module header). The
+   * static root and the manager both rotate it in place; `main.ts`'s
+   * `loadConfig` result holds the boot capture the roots start from.
+   */
+  readonly stigmerTokenRef: Readonly<TokenRef>;
+  /**
+   * The MCP bridge endpoint for the runner-synthesized attachments —
+   * channel messaging and conversation participation
+   * (STIGMER_MCP_BRIDGE_ENDPOINT, e.g. https://mcp.stigmer.ai). Null
+   * selects the OSS/local shape: a spawned `stigmer mcp-server` stdio
+   * child against the local backend. See shared/channel-attachment.ts
+   * 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
+   * set CURSOR_API_KEY anyway): the credential the SDK transport presents to
+   * the proxy is the control-plane credential, read from
+   * {@link stigmerTokenRef} per turn by the Cursor adapter, never copied here.
+   * Named after the CURSOR_API_KEY env var the SDK reads.
+   */
+  readonly cursorApiKey: string;
+  readonly workspaceRootDir: string;
+  /**
+   * Execution location: where the agent runs and whose filesystem it sees.
+   * "local" allows local-path workspaces (host filesystem); "cloud" runs in a
+   * server-provisioned sandbox (git-only). Independent of {@link proxyEndpoint},
+   * which controls credential/artifact transport — the desktop runner executes
+   * locally yet still proxies its Cursor traffic.
+   */
+  readonly mode: "local" | "cloud";
+  readonly proxyEndpoint: string | null;
+  readonly maxConcurrentActivities: number;
+  readonly idleTimeoutSeconds: number | null;
+  readonly cloudModeEnabled: boolean;
+  readonly checkpointerType: "memory" | "http" | "sqlite";
+  readonly checkpointerProxyEndpoint: string | null;
+  /**
+   * Endpoint the proxy artifact store presigns against
+   * (STIGMER_ARTIFACT_PROXY_ENDPOINT), defaulting to {@link proxyEndpoint} —
+   * the checkpointer-override pattern (stigmer#803). Splitting the two lets
+   * artifact traffic target the real control plane while LLM traffic goes
+   * elsewhere (the conformance harness points LLM calls at a mock proxy that
+   * serves no presign routes; embedders can route artifact storage
+   * independently the same way).
+   */
+  readonly artifactProxyEndpoint: string | null;
+  readonly primaryModel: string;
+  /**
+   * No-progress bound for every harness's engine stream (milliseconds); the
+   * name is the Cursor harness's, its first user. The roots set it from the
+   * `cursorStreamStallTimeoutMs` option; `loadConfig` also reads
+   * CURSOR_STREAM_STALL_TIMEOUT_MS, which no boot path in `main.ts` forwards
+   * yet (stigmer/stigmer#1731). If the engine reports no activity for this
+   * long, the turn runtime's stall watchdog (harness/run-turn.ts over
+   * shared/stall-watchdog.ts) cancels the run and fails the execution with a
+   * StallTimeoutError rather than hanging at RUN_IN_PROGRESS forever.
+   *
+   * Larger than the shared DEFAULT_STALL_TIMEOUT_MS (120s) because opaque MCP /
+   * GUI tool calls can legitimately run for minutes while emitting no stream
+   * activity. This bounds no-progress time only; it is orthogonal to Temporal's
+   * heartbeatTimeout (process liveness) and the 30s keep-alive heartbeat.
+   */
+  readonly cursorStreamStallTimeoutMs: number;
+  /**
+   * Bound (milliseconds) for Cursor Agent.create/Agent.resume. On expiry the
+   * execution fails fast with an explicit transport diagnosis instead of
+   * hanging into Temporal's heartbeat timeout. See
+   * {@link DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS} for why this exists.
+   */
+  readonly agentResolveTimeoutMs: number;
+  /**
+   * Max wait (milliseconds) for the per-workspace turn lock before failing
+   * the execution with a "workspace is in use by another session" error.
+   * See shared/workspace/workspace-lock.ts for the serialization model.
+   */
+  readonly workspaceLockTimeoutMs: number;
+  /**
+   * Shared reference to the runner credential (the roots bind it): the
+   * server-minted runner token once adopted, tracking the control-plane token
+   * in lockstep before that. StigmerClient authenticates value fetches with
+   * it so the server's runner-class gate recognizes a desktop runner (see
+   * stigmer-client.ts).
+   */
+  readonly stigmerRunnerTokenRef?: Readonly<TokenRef>;
+  /**
+   * Shared mutable reference to the credential the Cursor proxy transport
+   * sends as `x-stigmer-auth` (the fetch and HTTP/2 interceptors read it per
+   * request). Each composition root binds its own credential here, because
+   * the two differ: the static root binds the control-plane token (its host
+   * provides the proxy credential and mints no other, so
+   * `proxyTokenRef === stigmerTokenRef`), the manager binds the minted runner
+   * token (`proxyTokenRef === stigmerRunnerTokenRef`). Reading either sibling
+   * directly would send the wrong credential from one of the two roots.
+   * Required whenever `proxyEndpoint` is set; the Cursor adapter's
+   * boot refuses a proxy without it.
+   */
+  readonly proxyTokenRef?: Readonly<TokenRef>;
+  /**
+   * Where the Cursor SDK's traffic goes, when that is not {@link proxyEndpoint}:
+   * set only in the agent host, to the local proxy's Cursor lane
+   * (`agent-proxy/cursor-lane.ts`), which holds the Cursor credentials. The
+   * Cursor harness then runs as a proxy-mode client of that lane whatever
+   * the runner's own mode, while {@link proxyEndpoint} still says whether
+   * the key is the platform's (`activities/execute-cursor/adapter.ts`).
+   * Absent everywhere else.
+   */
+  readonly cursorEndpoint?: string;
+}
+
+export function loadConfig(): Config {
+  const mode = (process.env.MODE ?? "local") as "local" | "cloud";
+  const proxyEndpoint = process.env.STIGMER_PROXY_ENDPOINT ?? null;
+  const proxyActive = !!proxyEndpoint;
+
+  const taskQueue = process.env.STIGMER_TASK_QUEUE
+    ?? process.env.TEMPORAL_AGENT_EXECUTION_RUNNER_TASK_QUEUE
+    ?? "stigmer_runner";
+
+  // Temporal address is no longer required up front. When unset, the runner
+  // self-discovers it from the control plane during boot (see bootstrap.ts):
+  // an explicit value always wins, a token triggers discovery, and a tokenless
+  // local runner falls back to localhost. An empty string here means "resolve
+  // later" — the factory fills it in before connecting to Temporal.
+  const temporalAddress = process.env.TEMPORAL_SERVICE_ADDRESS ?? "";
+
+  const temporalNamespace = process.env.TEMPORAL_NAMESPACE ?? "default";
+
+  const stigmerBackendEndpoint = normalizeEndpoint(
+    mode === "local"
+      ? (process.env.STIGMER_BACKEND_ENDPOINT ?? "http://localhost:7234")
+      : requireEnv("STIGMER_BACKEND_ENDPOINT"),
+  );
+
+  // Secrets resolve through the credential store, not process.env — the
+  // boot capture has already moved them out of the environment (#508). The
+  // ref holds the boot capture: this function is read once, by main.ts, and
+  // the root it feeds builds the live ref from the value (the module header).
+  const stigmerTokenValue = getRunnerSecret("STIGMER_TOKEN");
+  if ((mode === "cloud" || proxyActive) && !stigmerTokenValue) {
+    throw new Error("Required environment variable STIGMER_TOKEN is not set");
+  }
+  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);
+  // the placeholder here is the two option mappers' exact value, so the three
+  // construction sites agree and no copy of the credential rides in Config.
+  const cursorApiKey = proxyActive
+    ? (getRunnerSecret("CURSOR_API_KEY") ?? "proxy-managed")
+    : (getRunnerSecret("CURSOR_API_KEY") ?? "");
+
+  const workspaceRootDir = resolveWorkspaceRootDir();
+
+  const maxConcurrentActivities = parseInt(
+    process.env.TEMPORAL_MAX_CONCURRENCY ?? "5",
+    10,
+  );
+
+  const idleTimeoutRaw = process.env.STIGMER_IDLE_TIMEOUT_SECONDS;
+  const idleTimeoutSeconds = idleTimeoutRaw ? parseInt(idleTimeoutRaw, 10) : null;
+
+  // Local/OSS default is the durable SQLite saver so HITL/pause/transient-recovery
+  // resume across ExecuteDeepAgent invocations (stigmer/stigmer#204); cloud stays
+  // on the proxy-backed http saver. STIGMER_CHECKPOINTER_TYPE overrides explicitly
+  // (e.g. "memory" for ephemeral test runs).
+  const checkpointerType =
+    (process.env.STIGMER_CHECKPOINTER_TYPE as "memory" | "http" | "sqlite" | undefined)
+    ?? (mode === "cloud" ? "http" : "sqlite");
+  const checkpointerProxyEndpoint = process.env.STIGMER_CHECKPOINTER_PROXY_ENDPOINT
+    ?? proxyEndpoint;
+  const artifactProxyEndpoint = process.env.STIGMER_ARTIFACT_PROXY_ENDPOINT
+    ?? proxyEndpoint;
+
+  const primaryModel = process.env.STIGMER_PRIMARY_MODEL ?? "gpt-4.1";
+
+  const cursorStreamStallTimeoutMs = process.env.CURSOR_STREAM_STALL_TIMEOUT_MS
+    ? parseInt(process.env.CURSOR_STREAM_STALL_TIMEOUT_MS, 10)
+    : DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS;
+
+  const workspaceLockTimeoutMs = process.env.WORKSPACE_LOCK_TIMEOUT_MS
+    ? parseInt(process.env.WORKSPACE_LOCK_TIMEOUT_MS, 10)
+    : DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS;
+
+  const agentResolveTimeoutMs = process.env.CURSOR_AGENT_RESOLVE_TIMEOUT_MS
+    ? parseInt(process.env.CURSOR_AGENT_RESOLVE_TIMEOUT_MS, 10)
+    : DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS;
+
+  return {
+    taskQueue,
+    temporalAddress,
+    temporalNamespace,
+    temporalConnection: loadTemporalConnectionConfig(getRunnerSecret),
+    stigmerBackendEndpoint,
+    stigmerTokenRef,
+    mcpBridgeEndpoint,
+    mcpPublicEndpoint,
+    cursorApiKey,
+    workspaceRootDir,
+    mode,
+    proxyEndpoint,
+    maxConcurrentActivities,
+    idleTimeoutSeconds,
+    cloudModeEnabled: process.env.STIGMER_CURSOR_CLOUD_MODE_ENABLED === "true",
+    checkpointerType,
+    checkpointerProxyEndpoint,
+    artifactProxyEndpoint,
+    primaryModel,
+    cursorStreamStallTimeoutMs,
+    agentResolveTimeoutMs,
+    workspaceLockTimeoutMs,
+  };
+}
+
+function resolveWorkspaceRootDir(): string {
+  const explicit = process.env.WORKSPACE_ROOT_DIR;
+  if (explicit) {
+    return explicit;
+  }
+
+  console.warn(
+    "WORKSPACE_ROOT_DIR is not set — creating isolated fallback workspace. " +
+    "This likely means the runner was started outside the CLI daemon.",
+  );
+
+  const fallbackDir = safeWorkspaceFallback();
+  mkdirSync(fallbackDir, { recursive: true });
+  return fallbackDir;
+}
+
+function safeWorkspaceFallback(): string {
+  try {
+    return join(homedir(), ".stigmer", "workspaces", "runner");
+  } catch {
+    return join(tmpdir(), "stigmer-runner-workspace");
+  }
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Required environment variable ${name} is not set`);
+  }
+  return value;
+}
+
+/**
+ * Ensures the endpoint has an HTTP(S) scheme. Port 443 implies TLS;
+ * all other bare host:port endpoints get http://.
+ *
+ * Exported so registry-endpoint.ts applies the same normalization to
+ * STIGMER_BACKEND_ENDPOINT that this module applies when loading config.
+ */
+export function normalizeEndpoint(endpoint: string): string {
+  if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
+    return endpoint;
+  }
+  if (endpoint.endsWith(":443")) {
+    return `https://${endpoint}`;
+  }
+  return `http://${endpoint}`;
+}

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