@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/config.d.ts

@@ -0,0 +1,216 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare const DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS = 180000;
+/**
+ * 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 declare const DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS = 120000;
+export { DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./shared/workspace/workspace-lock.js";
+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 declare function loadConfig(): Config;
+/**
+ * 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 declare function normalizeEndpoint(endpoint: string): string;

package/dist/config.js

@@ -0,0 +1,200 @@
+/**
+ * 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";
+export function loadConfig() {
+    const mode = (process.env.MODE ?? "local");
+    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 = { 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
+        ?? (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() {
+    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() {
+    try {
+        return join(homedir(), ".stigmer", "workspaces", "runner");
+    }
+    catch {
+        return join(tmpdir(), "stigmer-runner-workspace");
+    }
+}
+function requireEnv(name) {
+    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) {
+    if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
+        return endpoint;
+    }
+    if (endpoint.endsWith(":443")) {
+        return `https://${endpoint}`;
+    }
+    return `http://${endpoint}`;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/exit-backstop.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 declare const EXIT_BACKSTOP_MS = 5000;
+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 declare function armExitBackstop(options?: ExitBackstopOptions): ReturnType<typeof setTimeout>;
+/**
+ * `["Timeout", "TCPSocketWrap", "TCPSocketWrap"]` → `"TCPSocketWrap×2, Timeout×1"`:
+ * grouped and sorted, so the same leak reads the same on every exit.
+ */
+export declare function describeResources(resources: readonly string[]): string;

package/dist/exit-backstop.js

@@ -0,0 +1,79 @@
+/**
+ * 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;
+/**
+ * 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 = {}) {
+    const boundMs = options.boundMs ?? EXIT_BACKSTOP_MS;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const activeResources = options.activeResources ?? (() => process.getActiveResourcesInfo());
+    const log = options.log ?? ((line) => 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) {
+    if (resources.length === 0) {
+        return "none reported";
+    }
+    const counts = new Map();
+    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(", ");
+}
+//# sourceMappingURL=exit-backstop.js.map

package/dist/exit-backstop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-backstop.js","sourceRoot":"","sources":["../src/exit-backstop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAatC;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,UAA+B,EAAE;IAEjC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACpD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC;IAC5F,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAElE,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,GAAG,CACD,gCAAgC,OAAO,mCAAmC;YACxE,qBAAqB,iBAAiB,CAAC,eAAe,EAAE,CAAC,EAAE,CAC9D,CAAC;QACF,IAAI,CAAC,CAAC,CAAC,CAAC;IACV,CAAC,EAAE,OAAO,CAAC,CAAC;IACZ,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAA4B;IAC5D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;SACzB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC;SAClD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}