@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

package/src/encryption/payload-codec.ts

@@ -0,0 +1,152 @@
+/**
+ * Temporal PayloadCodec that encrypts payloads at rest in workflow
+ * history (stigmer-cloud#227).
+ *
+ * Why: the workflow engine runs inside the Temporal deterministic
+ * sandbox, so decrypted execution-context values cross the history
+ * boundary in many places — the hydrate activity result, the runtime
+ * env passed as an input to every per-task activity, and expression
+ * results recorded as local-activity markers. Encrypting at the payload
+ * codec layer closes the entire class with one mechanism instead of
+ * chasing each crossing.
+ *
+ * Envelope (cross-SDK contract — the Java decode-only codec in
+ * stigmer-cloud's temporal-starter must match it byte-for-byte, pinned
+ * by the conformance fixture in __tests__/fixtures/):
+ *
+ *   metadata: encoding            = "binary/encrypted"
+ *             encryption-key-id   = <key id that encrypted this payload>
+ *   data:     iv (12 bytes) ‖ AES-256-GCM(ciphertext ‖ tag (16 bytes))
+ *
+ * The plaintext is the serialized ORIGINAL Payload proto (metadata AND
+ * data), so decode restores the payload exactly — including its
+ * original encoding — with no side channel.
+ *
+ * Decode passes through payloads it did not encode. This is what keeps
+ * plaintext signals from the Java/Go orchestrators and pre-rollout
+ * in-flight histories working with zero migration. Everything else
+ * fails closed: unknown key id, missing key id, and ciphertext tampering
+ * all throw rather than surfacing bogus payloads.
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import type { Payload, PayloadCodec } from "@temporalio/common";
+// Default-import + destructure, NOT `import { temporal } from …`:
+// @temporalio/proto is CommonJS and its `temporal` export defeats Node's
+// cjs-module-lexer named-export detection, so the named form loads under
+// tsx/vitest (their interop is looser) but crashes plain `node dist/main.js`
+// at startup with "Named export 'temporal' not found" (stigmer/stigmer#399
+// boot regression). Pinned by scripts/verify-dist-boot.mjs in CI.
+import proto from "@temporalio/proto";
+import type { EncryptionKey, PayloadEncryptionConfig } from "./config.js";
+
+const { temporal } = proto;
+
+const ENCODING_METADATA_KEY = "encoding";
+const ENCRYPTED_ENCODING_VALUE = "binary/encrypted";
+const KEY_ID_METADATA_KEY = "encryption-key-id";
+
+/** AES-GCM parameters shared with the Java implementation. */
+const IV_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+
+export class EncryptionPayloadCodec implements PayloadCodec {
+  private readonly decryptKeysById: Map<string, Buffer>;
+
+  constructor(private readonly config: PayloadEncryptionConfig) {
+    this.decryptKeysById = new Map([[config.primary.keyId, config.primary.key]]);
+    if (config.secondary) {
+      this.decryptKeysById.set(config.secondary.keyId, config.secondary.key);
+    }
+  }
+
+  async encode(payloads: Payload[]): Promise<Payload[]> {
+    return payloads.map((p) => this.encodePayload(p));
+  }
+
+  async decode(payloads: Payload[]): Promise<Payload[]> {
+    return payloads.map((p) => this.decodePayload(p));
+  }
+
+  private encodePayload(payload: Payload): Payload {
+    // Data-less payloads (binary/null from void results) stay as-is:
+    // there is nothing to protect, and the cross-language parents that
+    // await our workflows as void must be able to read them without a key.
+    if (!payload.data || payload.data.length === 0) {
+      return payload;
+    }
+
+    const plaintext = temporal.api.common.v1.Payload.encode(payload).finish();
+    return {
+      metadata: {
+        [ENCODING_METADATA_KEY]: Buffer.from(ENCRYPTED_ENCODING_VALUE),
+        [KEY_ID_METADATA_KEY]: Buffer.from(this.config.primary.keyId),
+      },
+      data: encrypt(plaintext, this.config.primary),
+    };
+  }
+
+  private decodePayload(payload: Payload): Payload {
+    if (!isEncryptedPayload(payload)) {
+      return payload;
+    }
+
+    const keyIdBytes = payload.metadata?.[KEY_ID_METADATA_KEY];
+    if (!keyIdBytes) {
+      throw new Error(
+        "Encrypted payload is missing its encryption-key-id metadata — refusing to decode",
+      );
+    }
+    const keyId = Buffer.from(keyIdBytes).toString("utf-8");
+    const key = this.decryptKeysById.get(keyId);
+    if (!key) {
+      throw new Error(
+        `Encrypted payload uses unknown key id '${keyId}' — configure it as the ` +
+          `primary or secondary payload encryption key (rotation window?)`,
+      );
+    }
+
+    const plaintext = decrypt(payload.data!, key, keyId);
+    return temporal.api.common.v1.Payload.decode(plaintext);
+  }
+}
+
+function isEncryptedPayload(payload: Payload): boolean {
+  const encoding = payload.metadata?.[ENCODING_METADATA_KEY];
+  if (!encoding) return false;
+  return Buffer.from(encoding).toString("utf-8") === ENCRYPTED_ENCODING_VALUE;
+}
+
+function encrypt(plaintext: Uint8Array, key: EncryptionKey): Buffer {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", key.key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  // Layout iv ‖ ciphertext ‖ tag matches Java's AES/GCM/NoPadding, whose
+  // doFinal() output is ciphertext ‖ tag.
+  return Buffer.concat([iv, ciphertext, cipher.getAuthTag()]);
+}
+
+function decrypt(data: Uint8Array, key: Buffer, keyId: string): Buffer {
+  if (data.length < IV_BYTES + AUTH_TAG_BYTES) {
+    throw new Error(
+      `Encrypted payload under key id '${keyId}' is truncated (${data.length} bytes)`,
+    );
+  }
+  const buf = Buffer.from(data);
+  const iv = buf.subarray(0, IV_BYTES);
+  const ciphertext = buf.subarray(IV_BYTES, buf.length - AUTH_TAG_BYTES);
+  const tag = buf.subarray(buf.length - AUTH_TAG_BYTES);
+
+  const decipher = createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(tag);
+  try {
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch {
+    // GCM auth failure: tampered ciphertext or a key that does not match
+    // its advertised id. Never surface partially decrypted bytes.
+    throw new Error(
+      `Failed to decrypt payload under key id '${keyId}' — ciphertext is ` +
+        `corrupt or the configured key does not match`,
+    );
+  }
+}

package/src/middleware/__tests__/path-normalization.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect, vi } from "vitest";
+import { ToolMessage } from "@langchain/core/messages";
+import {
+  createPathNormalizationMiddleware,
+  normalizeWorkspacePathArg,
+} from "../path-normalization.js";
+import type { ToolCallRequest } from "../types.js";
+
+const ROOT = "/workspace/session-1/repo";
+
+function makeRequest(
+  name: string,
+  args: Record<string, unknown>,
+): ToolCallRequest {
+  return {
+    toolCall: { id: "tc_1", name, args },
+    tool: undefined,
+    state: { messages: [] },
+    runtime: {},
+  };
+}
+
+/** Run the middleware and return the args the inner handler observed. */
+async function argsSeenByHandler(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const mw = createPathNormalizationMiddleware({ rootDir: ROOT });
+  const handler = vi.fn(async (req: ToolCallRequest) => {
+    return new ToolMessage({ content: "ok", tool_call_id: req.toolCall.id, name });
+  });
+  await mw.wrapToolCall!(makeRequest(name, args), handler);
+  expect(handler).toHaveBeenCalledTimes(1);
+  return handler.mock.calls[0][0].toolCall.args;
+}
+
+describe("normalizeWorkspacePathArg", () => {
+  it("maps a workspace-relative path to its rootDir-joined absolute form", () => {
+    expect(normalizeWorkspacePathArg("src/main.py", ROOT)).toBe(`${ROOT}/src/main.py`);
+  });
+
+  it("strips a leading ./ before joining", () => {
+    expect(normalizeWorkspacePathArg("./notes.md", ROOT)).toBe(`${ROOT}/notes.md`);
+  });
+
+  it("handles multi-workspace entry-relative paths", () => {
+    expect(normalizeWorkspacePathArg("entry-1/src/main.py", ROOT)).toBe(
+      `${ROOT}/entry-1/src/main.py`,
+    );
+  });
+
+  it("resolves interior .. segments that stay inside the root", () => {
+    expect(normalizeWorkspacePathArg("src/../notes.md", ROOT)).toBe(`${ROOT}/notes.md`);
+  });
+
+  it("leaves absolute paths untouched", () => {
+    expect(normalizeWorkspacePathArg("/etc/hosts", ROOT)).toBeUndefined();
+    expect(normalizeWorkspacePathArg(`${ROOT}/src/main.py`, ROOT)).toBeUndefined();
+    expect(normalizeWorkspacePathArg("/", ROOT)).toBeUndefined();
+  });
+
+  it("refuses to rewrite relatives that escape the workspace root", () => {
+    // A naive join would resolve `..` away and hand upstream validation a
+    // clean out-of-root absolute path — an out-of-root read that today's
+    // validation refuses. The guard keeps the refusal.
+    expect(normalizeWorkspacePathArg("../sibling/secret.txt", ROOT)).toBeUndefined();
+    expect(normalizeWorkspacePathArg("src/../../escape.txt", ROOT)).toBeUndefined();
+  });
+
+  it("leaves ~-carrying paths untouched (upstream refuses them either way)", () => {
+    expect(normalizeWorkspacePathArg("~/notes.md", ROOT)).toBeUndefined();
+    expect(normalizeWorkspacePathArg("docs/~/x.md", ROOT)).toBeUndefined();
+  });
+
+  it("leaves the empty string untouched", () => {
+    expect(normalizeWorkspacePathArg("", ROOT)).toBeUndefined();
+  });
+});
+
+describe("createPathNormalizationMiddleware", () => {
+  it("rewrites file_path on the file tools", async () => {
+    for (const tool of ["read_file", "write_file", "edit_file"]) {
+      const args = await argsSeenByHandler(tool, {
+        file_path: "src/main.py",
+        content: "x",
+      });
+      expect(args.file_path).toBe(`${ROOT}/src/main.py`);
+      // Sibling args ride along untouched.
+      expect(args.content).toBe("x");
+    }
+  });
+
+  it("rewrites the base path on ls/glob/grep", async () => {
+    for (const tool of ["ls", "glob", "grep"]) {
+      const args = await argsSeenByHandler(tool, { path: "src", pattern: "**/*.py" });
+      expect(args.path).toBe(`${ROOT}/src`);
+      // The pattern is never a path — byte-untouched.
+      expect(args.pattern).toBe("**/*.py");
+    }
+  });
+
+  it("passes absolute paths through byte-untouched", async () => {
+    const args = await argsSeenByHandler("read_file", { file_path: "/etc/hosts" });
+    expect(args.file_path).toBe("/etc/hosts");
+  });
+
+  it("leaves an omitted base path (backend default) alone", async () => {
+    const args = await argsSeenByHandler("ls", {});
+    expect(args.path).toBeUndefined();
+  });
+
+  it("never touches tools outside the built-in filesystem set", async () => {
+    // An MCP tool could plausibly carry a same-named arg with different
+    // semantics; only the six built-in names are rewritten.
+    const args = await argsSeenByHandler("vendor_upload", { file_path: "src/main.py" });
+    expect(args.file_path).toBe("src/main.py");
+  });
+
+  it("leaves non-string path args for the tool's own input validation", async () => {
+    const args = await argsSeenByHandler("read_file", { file_path: 42 });
+    expect(args.file_path).toBe(42);
+  });
+
+  it("preserves the original request identity fields on rewrite", async () => {
+    const mw = createPathNormalizationMiddleware({ rootDir: ROOT });
+    const handler = vi.fn(async (req: ToolCallRequest) => {
+      return new ToolMessage({ content: "ok", tool_call_id: req.toolCall.id, name: req.toolCall.name });
+    });
+    const original = makeRequest("read_file", { file_path: "notes.md" });
+    await mw.wrapToolCall!(original, handler);
+
+    const seen = handler.mock.calls[0][0];
+    expect(seen.toolCall.id).toBe("tc_1");
+    expect(seen.toolCall.name).toBe("read_file");
+    expect(seen.state).toBe(original.state);
+    expect(seen.runtime).toBe(original.runtime);
+    // The original request is never mutated in place.
+    expect(original.toolCall.args.file_path).toBe("notes.md");
+  });
+});

package/src/middleware/index.ts

@@ -4,6 +4,9 @@
  * Assembles the ordered middleware array from a MiddlewareStackConfig.
  * The composition order matches the Python create_deep_agent injection:
  *
+ *   0. Path normalization (conditional: only on permission-rule-bearing
+ *      graphs — FIRST, so every downstream middleware observes canonical
+ *      workspace-absolute paths)
  *   1. Loop detection (always)
  *   2. Execution budget (always)
  *   3. Tool truncation (always)
@@ -15,6 +18,7 @@
 
 import type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
 import type { GracefulStopMiddleware } from "./graceful-stop.js";
+import { createPathNormalizationMiddleware } from "./path-normalization.js";
 import { createLoopDetectionMiddleware } from "./loop-detection.js";
 import { createExecutionBudgetMiddleware } from "./execution-budget.js";
 import { createToolTruncationMiddleware } from "./tool-truncation.js";
@@ -39,6 +43,10 @@ export function buildMiddlewareStack(
 ): MiddlewareStackResult {
   const stack: StigmerMiddleware[] = [];
 
+  if (config.pathNormalization) {
+    stack.push(createPathNormalizationMiddleware(config.pathNormalization));
+  }
+
   stack.push(createLoopDetectionMiddleware(config.loopDetection));
 
   stack.push(createExecutionBudgetMiddleware(config.executionBudget));

package/src/middleware/path-normalization.ts

@@ -0,0 +1,125 @@
+/**
+ * Workspace-relative path normalization for permission-rule-bearing graphs
+ * (issue #429).
+ *
+ * deepagents' permission enforcement canonicalizes tool-call paths BEFORE any
+ * rule or backend runs, and its validation refuses non-absolute paths — on
+ * EVERY filesystem tool call once a graph carries any permission rules, reads
+ * included. Plan mode is the only rule-bearing production configuration
+ * (shared/plan-mode-permissions.ts), so there a workspace-relative path —
+ * the shape the multi-workspace prompt explicitly mandates, and one models
+ * routinely choose in single-workspace sessions — fails with
+ * `path must be absolute` instead of just working, burning tool rounds until
+ * the model adapts by switching to absolute paths.
+ *
+ * This middleware repairs the contract at our own seam: it rewrites
+ * workspace-relative paths on the deepagents built-in filesystem tools to
+ * workspace-absolute before the tool (and therefore enforcement) runs. The
+ * write-deny rule then fires as designed and reads succeed on the first try.
+ * Rule-less (act-mode) graphs never install it — the legacy backend already
+ * resolves relative paths under the workspace root, so act mode keeps a
+ * byte-zero delta.
+ *
+ * Invariant — nothing becomes newly reachable: only paths whose resolution
+ * stays INSIDE the workspace root are rewritten. Escaping relatives (`../x`)
+ * and `~`-carrying paths are left raw so today's validation refusal keeps
+ * speaking (a naive join would resolve `..` away and smuggle an out-of-root
+ * read past validation), and absolute paths pass through byte-untouched.
+ * The middleware converts false errors into correct behavior — never a
+ * refusal into an allowance the rules didn't decide.
+ *
+ * Tool matching is by bare built-in name, the house doctrine (an MCP server
+ * is not expected to shadow a built-in name — see shared/tool-kind.ts); the
+ * rewrite touches only the tool's path-bearing argument, never glob/grep
+ * patterns. Install FIRST in the stack so every downstream middleware
+ * (approval gate, error hints, otel spans) observes canonical paths.
+ */
+
+import { isAbsolute, relative } from "node:path";
+import { resolveWorkspacePath } from "../shared/file-change.js";
+import type { StigmerMiddleware } from "./types.js";
+
+/**
+ * The path-bearing argument of each deepagents built-in filesystem tool.
+ * `ls`/`glob`/`grep` take a base directory `path` (defaulting to "/" when
+ * omitted — absolute, so untouched here); the file tools take `file_path`.
+ * Confirmed against the installed deepagents' tool definitions.
+ */
+const PATH_ARG_BY_TOOL: ReadonlyMap<string, string> = new Map([
+  ["ls", "path"],
+  ["glob", "path"],
+  ["grep", "path"],
+  ["read_file", "file_path"],
+  ["write_file", "file_path"],
+  ["edit_file", "file_path"],
+]);
+
+export interface PathNormalizationConfig {
+  /** The workspace root the graph's filesystem backend resolves against. */
+  readonly rootDir: string;
+}
+
+/**
+ * Rewrite `raw` to its workspace-absolute form, or return undefined when the
+ * value must be left untouched (absolute already, `~`-carrying, or escaping
+ * the workspace root). Exported for direct unit testing of the mapping table.
+ */
+export function normalizeWorkspacePathArg(
+  raw: string,
+  rootDir: string,
+): string | undefined {
+  if (raw.length === 0 || isAbsolute(raw)) return undefined;
+  // Upstream validation refuses `~` segments even in absolute paths, so a
+  // rewrite could not make such a call succeed — leave the raw shape (and
+  // therefore the honest refusal) intact.
+  if (raw.split("/").includes("~")) return undefined;
+
+  const { absolutePath } = resolveWorkspacePath(raw, rootDir, false);
+
+  // No-new-reachability guard: `join` inside the resolver normalizes `..`
+  // segments away, so an escaping relative would otherwise pass upstream
+  // validation as a clean out-of-root absolute path. Today that shape is
+  // refused; keep it that way.
+  const rel = relative(rootDir, absolutePath);
+  if (rel.startsWith("..") || isAbsolute(rel)) return undefined;
+
+  return absolutePath;
+}
+
+/**
+ * Create middleware that normalizes workspace-relative paths on the built-in
+ * filesystem tools before permission enforcement sees them.
+ *
+ * Installed only on graphs that carry filesystem permission rules — derive
+ * the install condition from the same expression that supplies the rules
+ * (setup.ts / compileSubagents) so the rules and their normalization shim
+ * cannot drift apart.
+ */
+export function createPathNormalizationMiddleware(
+  config: PathNormalizationConfig,
+): StigmerMiddleware {
+  const { rootDir } = config;
+
+  return {
+    name: "PathNormalizationMiddleware",
+
+    wrapToolCall(request, handler) {
+      const argKey = PATH_ARG_BY_TOOL.get(request.toolCall.name);
+      if (!argKey) return handler(request);
+
+      const raw = request.toolCall.args[argKey];
+      if (typeof raw !== "string") return handler(request);
+
+      const normalized = normalizeWorkspacePathArg(raw, rootDir);
+      if (normalized === undefined) return handler(request);
+
+      return handler({
+        ...request,
+        toolCall: {
+          ...request.toolCall,
+          args: { ...request.toolCall.args, [argKey]: normalized },
+        },
+      });
+    },
+  };
+}

package/src/middleware/types.ts

@@ -100,6 +100,11 @@ export interface OtelSpansConfig {
 import type { ApprovalGateConfig } from "./approval-gate.js";
 export type { ApprovalGateConfig };
 
+// Same idiom as ApprovalGateConfig above: the normalization middleware
+// consumes it, this module re-exports it for stack-config assembly.
+import type { PathNormalizationConfig } from "./path-normalization.js";
+export type { PathNormalizationConfig };
+
 /**
  * Top-level configuration for buildMiddlewareStack().
  * All sections are optional — the factory applies sensible defaults.
@@ -111,4 +116,10 @@ export interface MiddlewareStackConfig {
   readonly costCap?: CostCapConfig | null;
   readonly otelSpans?: Partial<OtelSpansConfig>;
   readonly approvalGate?: ApprovalGateConfig | null;
+  /**
+   * Workspace-relative path normalization (issue #429). Set iff the graph
+   * carries filesystem permission rules — derive from the same expression
+   * that supplies the rules so the two cannot drift apart.
+   */
+  readonly pathNormalization?: PathNormalizationConfig | null;
 }

package/src/payload-codecs.ts

@@ -0,0 +1,62 @@
+/**
+ * Single assembly point for the worker's payload codec chain, shared by
+ * the standalone runner (runner.ts) and the runner manager
+ * (runner-manager.ts) so the two entrypoints cannot drift.
+ *
+ * Codec order is a correctness property, not a style choice. Temporal
+ * applies codecs in array order on encode and in reverse on decode, so
+ * with [encryption, claimcheck]:
+ *
+ *   encode: encrypt → claim-check   (payloads the claim-check codec
+ *           relocates to object storage are already ciphertext)
+ *   decode: claim-check → decrypt   (restore the blob, then decrypt)
+ */
+
+import type { PayloadCodec } from "@temporalio/common";
+import type { Config } from "./config.js";
+import type { BootstrapKeyMaterial } from "./encryption/config.js";
+
+export async function createPayloadCodecs(
+  config: Config,
+  bootstrapKeys?: BootstrapKeyMaterial,
+): Promise<PayloadCodec[] | undefined> {
+  const codecs: PayloadCodec[] = [];
+
+  const { loadPayloadEncryptionConfig, EncryptionPayloadCodec } = await import(
+    "./encryption/index.js"
+  );
+  // Env-configured keys win outright; server-managed (bootstrap) keys apply
+  // only when the env is silent — see encryption/config.ts for the rationale.
+  const encryptionConfig = loadPayloadEncryptionConfig(bootstrapKeys);
+  if (encryptionConfig) {
+    codecs.push(new EncryptionPayloadCodec(encryptionConfig));
+    const source = process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY ? "env" : "bootstrap";
+    console.log(
+      `[runner] Payload encryption enabled (source=${source}, ` +
+        `key_id=${encryptionConfig.primary.keyId}` +
+        (encryptionConfig.secondary
+          ? `, secondary_key_id=${encryptionConfig.secondary.keyId})`
+          : ")"),
+    );
+  }
+
+  const { loadClaimcheckConfig, ClaimcheckPayloadCodec } = await import(
+    "./claimcheck/index.js"
+  );
+  const claimcheckConfig = loadClaimcheckConfig();
+  if (claimcheckConfig.enabled) {
+    const { loadArtifactStorageConfig, createArtifactStorage } = await import(
+      "./shared/artifact-storage.js"
+    );
+    const storageConfig = loadArtifactStorageConfig(config);
+    const storage = createArtifactStorage(storageConfig);
+    codecs.push(new ClaimcheckPayloadCodec(storage, claimcheckConfig));
+    console.log(
+      `[runner] Claimcheck enabled (threshold=${claimcheckConfig.thresholdBytes}B, ` +
+        `compression=${claimcheckConfig.compressionEnabled}, ` +
+        `storage=${storageConfig.type})`,
+    );
+  }
+
+  return codecs.length > 0 ? codecs : undefined;
+}

package/src/preflight.ts

@@ -21,8 +21,15 @@
  * The gate is unconditional (not checkpointer-type-dependent): the eager
  * import chain needs `node:sqlite` to LOAD regardless of configuration, so
  * the gate mirrors the actual load-time requirement.
+ *
+ * This module also hosts {@link assertLlmBackendsPreflight}, the
+ * deployment-config gate the runner factories run at construction. The
+ * llm-backend import below is a pure, dependency-free module, so it does
+ * not compromise the load-order guarantees above.
  */
 
+import { preflightLlmBackends } from "./shared/llm-backend.js";
+
 /**
  * True when this Node binary provides the built-in `node:sqlite`.
  *
@@ -57,3 +64,41 @@ export function preflightNodeRuntime(
     `Use Node >= 22.13 (22.x line) or >= 23.4 (23.x and later).`
   );
 }
+
+/**
+ * Validate LLM backend configuration (STIGMER_ANTHROPIC_BACKEND /
+ * STIGMER_OPENAI_BACKEND) at runner construction, throwing an actionable
+ * operator message on fatal misconfiguration and logging precedence
+ * warnings.
+ *
+ * Called from the runner factories rather than main.ts because
+ * @stigmer/runner is a public library: in-process embedders never execute
+ * main.ts, while all of main.ts's process modes construct through the
+ * factories. A library must never process.exit, so this throws — manager
+ * mode's factory catch converts it to a fatal IPC error for the desktop
+ * host, static/pool modes exit through main()'s fatal handler, and
+ * embedders get a rejected promise.
+ *
+ * Backend misconfiguration is deployment-static; failing here means a
+ * broken deployment refuses to accept work instead of failing every
+ * execution mid-flight (the createClient factories construct lazily on
+ * first request, far too late for a good operator experience).
+ *
+ * @param proxyEndpoint The effective proxy endpoint. Factories receive it
+ *   via options (env-derived in main.ts flows, caller-supplied for
+ *   embedders), so it is threaded explicitly instead of re-read from env —
+ *   an options-supplied proxy must downgrade backend vars to warnings the
+ *   same way STIGMER_PROXY_ENDPOINT does.
+ */
+export function assertLlmBackendsPreflight(proxyEndpoint?: string | null): void {
+  const env = proxyEndpoint
+    ? { ...process.env, STIGMER_PROXY_ENDPOINT: proxyEndpoint }
+    : process.env;
+  const { error, warnings } = preflightLlmBackends(env);
+  for (const warning of warnings) {
+    console.warn(`[runner] ${warning}`);
+  }
+  if (error !== null) {
+    throw new Error(error);
+  }
+}