@stigmer/runner 0.1.0-dev.20261017064309.g94d062a29f89 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @stigmer/runner
 
-Embeddable Temporal worker for the Stigmer AI agent platform. The runner executes agent sessions — driving the Cursor and native (deep-agent) harnesses, orchestrating MCP servers, and reporting status and artifacts back to the Stigmer backend.
+Embeddable Temporal worker that runs Stigmer's agent sessions: it drives the Stigmer and Claude harnesses, orchestrates MCP servers, and reports status and artifacts back to the Stigmer backend.
 
 It is the single runtime behind three surfaces:
 
@@ -26,6 +26,8 @@ This runs `npm run build` in `backend/services/runner` (`tsc -p tsconfig.build.j
 
 Requires a Node.js whose built-in `node:sqlite` is available unflagged — `>= 22.13` in the 22.x line, and `>= 23.4` after that (23.0–23.3 lack it). The durable local checkpointer depends on it, and the runner probes for it at boot (`src/preflight.ts`), refusing to start with an actionable error rather than crashing on the import.
 
+On those floors below 22.19 / 23.8, npm may warn at install (`EBADENGINE`) that `@stigmer/outbound` and `undici` want a newer Node. That requirement belongs to outbound's `/dial` entry, which the runner never loads (`src/__tests__/runner-is-undici-free.test.ts` keeps it so), so the warning is safe to ignore.
+
 ### The slim embedding artifact
 
 The plain `dist/` resolves its dependencies from `node_modules` at runtime — ~508 MB unpacked, which is unshippable inside a desktop app ([#170](https://github.com/stigmer/stigmer/issues/170)). For embedding, build the **slim artifact**:
@@ -34,29 +36,28 @@ The plain `dist/` resolves its dependencies from `node_modules` at runtime — ~
 make build-runner-slim          # or: npm run build:slim
 ```
 
-This produces `dist-slim/`: a tree-shaken esbuild bundle of the whole runner (`main.js`), a build-time-prebuilt Temporal workflow bundle, and a staged `node_modules` containing only the packages that genuinely cannot be bundled (the platform-pruned Temporal native bridge, `@cursor/sdk` and its native binaries) — **~85 MB per platform**. `node dist-slim/main.js` accepts the same modes, environment variables, and IPC protocol as `dist/main.js`. It also holds `attach/main.js`, the attach entry (below) bundled on its own, which starts the `main.js` beside it with the same Node. See `scripts/bundle-slim.mjs` for the full layout, `scripts/verify-slim-artifact.mjs` for the boot verification that gates releases, and the [embedding guide](https://stigmer.ai/docs/guides/runners/embedding) for how apps stage it.
+This produces `dist-slim/`: a tree-shaken esbuild bundle of the whole runner (`main.js`), and a staged `node_modules` containing only the packages that genuinely cannot be bundled (the platform-pruned Temporal native bridge and the few packages that ship native code). `node dist-slim/main.js` accepts the same modes, environment variables, and IPC protocol as `dist/main.js`. It also holds `attach/main.js`, the attach entry (below) bundled on its own, which starts the `main.js` beside it with the same Node. See `scripts/bundle-slim.mjs` for the full layout, `scripts/verify-slim-artifact.mjs` for the boot verification that gates releases, and the [embedding guide](https://stigmer.ai/docs/guides/runners/embedding) for how apps stage it.
 
-> **Why the slim bundle is CommonJS, not ESM.** The runner's auth correctness depends on a deliberate module **load order**: it installs the fetch + HTTP/2 interceptors first, then lazily loads `@cursor/sdk` and `@connectrpc/connect-node` (via dynamic `import()`) so the interceptors are in place before those packages capture `globalThis.fetch` / snapshot the `node:http2` ESM facade. An **ESM** esbuild bundle destroys this — it hoists every external `import` to the top of the output and evaluates them before any code runs, freezing the `node:http2` facade and capturing the original `fetch` before install, which silently breaks proxy auth on the authenticated path (this was the regression in [#170](https://github.com/stigmer/stigmer/issues/170)). A **CJS** bundle preserves the source's lazy evaluation order, so the dynamic-import boundary keeps both interceptors correct. The meta `package.json` deliberately omits `"type": "module"` so `node main.js` runs as CommonJS — do **not** add it back, and do not flip `format` to `"esm"` in `bundle-slim.mjs`. The boot guard `assertHttp2ConnectPatched()` plus the authenticated check in `verify-slim-artifact.mjs` fail loudly if this is ever reverted.
+> **Why the slim bundle is CommonJS, not ESM.** The runner loads its heavy modules lazily (`@connectrpc/connect-node`, LangChain, the activity factories, via dynamic `import()`) after the harnesses boot. An **ESM** esbuild bundle hoists every external `import` to the top of the output and evaluates them before any code runs; a **CJS** bundle preserves the source's lazy evaluation order (the module-order regression of [#170](https://github.com/stigmer/stigmer/issues/170) was an ESM bundle). The meta `package.json` deliberately omits `"type": "module"` so `node main.js` runs as CommonJS — do **not** add it back, and do not flip `format` to `"esm"` in `bundle-slim.mjs` (see its header). The authenticated boot check in `verify-slim-artifact.mjs` boots the artifact as a release would.
 
 The slim build is also published to npm as `@stigmer/runner-slim` (with per-platform `@stigmer/runner-slim-<platform>` support packages) alongside the full `@stigmer/runner` package on every release.
 
-The sandbox image (`Dockerfile.sandbox`) ships the same directory as its runner layer: `dist-slim/` at `/runner/dist`, started by the layer's own Node at `/runner/bin/node` (the repository's `.nvmrc` version), on a base image that holds the agent's tools. The server's drivers launch it with the command in `backend/services/stigmer-server/src/sandbox/runner-launch.ts`: `/runner/bin/start` (`layer/start.sh`), which refuses a base image the runner cannot run on (no glibc, not root, no `bash`, `git` or the Cursor hook's text tools) in one line that names the contract, refuses a layer whose `/runner/RELEASE` names another release than the server's `STIGMER_SERVER_RELEASE` (stigmer/stigmer#1831), clears `NODE_OPTIONS` and `NODE_PATH`, and execs that Node. The image's release lane runs `verify-slim-artifact.mjs` inside the built image, through the start script, before any tag but `main-<sha>` names it, and publishes the layer alone (`ghcr.io/stigmer/runner-layer`, amd64 and arm64) after booting it on Ubuntu and seeing it refuse Alpine; `deploy/runner-layer/Dockerfile` adds it to an operator's own base (the self-hosting guide's "Bring your own base image").
+The sandbox image (`Dockerfile.sandbox`) ships the same directory as its runner layer: `dist-slim/` at `/runner/dist`, started by the layer's own Node at `/runner/bin/node` (the repository's `.nvmrc` version), on a base image that holds the agent's tools. The server's drivers launch it with the command in `backend/services/stigmer-server/src/sandbox/runner-launch.ts`: `/runner/bin/start` (`layer/start.sh`), which refuses a base image the runner cannot run on (no glibc, not root, no `bash`, `git` or the standard text tools) in one line that names the contract, refuses a layer whose `/runner/RELEASE` names another release than the server's `STIGMER_SERVER_RELEASE` (stigmer/stigmer#1831), clears `NODE_OPTIONS` and `NODE_PATH`, and execs that Node. The image's release lane runs `verify-slim-artifact.mjs` inside the built image, through the start script, before any tag but `main-<sha>` names it, and publishes the layer alone (`ghcr.io/stigmer/runner-layer`, amd64 and arm64) after booting it on Ubuntu and seeing it refuse Alpine; `deploy/runner-layer/Dockerfile` adds it to an operator's own base (the self-hosting guide's "Bring your own base image").
 
 ## Run modes
 
-The runner has three **run modes**, selected at boot by two environment variables (`src/main.ts`): `STIGMER_RUNNER_MODE=manager` selects manager mode; otherwise a set `STIGMER_POOL_MEMBER_ID` selects pool mode; otherwise the runner is static. Do not confuse the run mode (process topology) with the execution location (`MODE=local|cloud`) or the transport (`STIGMER_PROXY_ENDPOINT`) — those are independent axes covered in [Execution location vs transport](#execution-location-vs-transport).
+The runner has two **run modes**, selected at boot by one environment variable (`src/main.ts`): `STIGMER_RUNNER_MODE=manager` selects manager mode; otherwise the runner is static. Do not confuse the run mode (process topology) with the execution location (`MODE=local|cloud`) or the transport (`STIGMER_PROXY_ENDPOINT`) — those are independent axes covered in [Execution location vs transport](#execution-location-vs-transport).
 
 | Run mode | Selector | Topology | Used by |
 |----------|----------|----------|---------|
-| Static | Neither of the two below (default) | One Worker polling one task queue; blocks until shutdown | CLI daemon, cloud deployments |
+| Static | `STIGMER_RUNNER_MODE` unset or not `manager` (default) | One Worker polling one task queue; blocks until shutdown | CLI daemon, cloud deployments |
 | Manager | `STIGMER_RUNNER_MODE=manager` | Shared Temporal connection; dynamic per-session / per-execution Workers; stdin/stdout JSON IPC | Desktop app |
-| Pool | `STIGMER_POOL_MEMBER_ID` set, and `STIGMER_RUNNER_MODE` not `manager` | A warm-pool sandbox: boots the runner manager, then serves what its injected credential says — a blank member polls its `sandbox:{memberId}` control queue for a claim, a claimed member that restarted goes straight to its session's queue (`src/pool-member.ts`) | Hosted cloud sandboxes |
 
 ### Static mode
 
 Static mode creates a single Temporal Worker that polls one task queue and runs until it receives `SIGTERM` / `SIGINT`. This is the right mode when the set of work is fixed at startup (a daemon or a pod dedicated to a queue).
 
-On a signal it drains the worker, releases the harnesses, closes its Temporal connection and flushes telemetry, and the process then exits on its own, normally within milliseconds. As the CLI entry (`stigmer-runner`, and the cloud's pool members, which end the same way), a process still alive 5 s after that is made to exit, with one log line naming the resources that kept it alive (`src/exit-backstop.ts`). That line means a leaked handle to fix, not a slow shutdown to tune.
+On a signal it drains the worker: every turn in flight yields at its engine's next step boundary within the drain grace (`STIGMER_DRAIN_GRACE_MS`), so a step that was running finishes, and the workflow continues the turn on the next runner from where it was. A second signal stops the turns in flight at once; they continue too, and the step each was running is run again. Then it releases the harnesses, closes its Temporal connection and flushes telemetry, and the process exits on its own, normally within milliseconds of the drain. As the CLI entry (`stigmer-runner`), a process still alive 5 s after that is made to exit, with one log line naming the resources that kept it alive (`src/exit-backstop.ts`). That line means a leaked handle to fix, not a slow shutdown to tune.
 
 As a library:
 
@@ -105,19 +106,30 @@ A push is accepted only for the queue whose sandbox name (`sbx-<code>-<12 hex>`,
 
 ### The agent host (where the engines run)
 
-In every run mode, and in a library embedding, the runner runs every harness's engine (the native one and Cursor's) in a second process, the agent host: the runner's own entry started as `main.js agent-host`, on the same Node, with a private pipe on file descriptor 3 (`src/agent-host/`). The runner keeps the turn runtime, its credentials and all its control-plane traffic; the host runs the engines and every process an agent's turn starts there (its shell, its hooks, its MCP servers, the Cursor approval hook's server). The runner's own process loads neither engine's SDK. The two meet at the harness adapter contract (`src/harness/types.ts`): the runner's remote adapter (`src/agent-host/remote-adapter.ts`) forwards each turn to the host and treats everything the host sends back as untrusted, and which harnesses are hosted is one set in `src/harness-adapters.ts` (`HOSTED_HARNESSES`).
+In every run mode, and in a library embedding, the runner runs every harness's engine (the Stigmer one and Claude's) in a second process, the agent host: the runner's own entry started as `main.js agent-host`, on the same Node, with a private pipe on file descriptor 3 (`src/agent-host/`). The runner keeps the turn runtime, its credentials and all its control-plane traffic; the host runs the engines and every process an agent's turn starts there (its shell, its hooks, its MCP servers). The runner's own process loads no engine's SDK. The two meet at the harness adapter contract (`src/harness/types.ts`): the runner's remote adapter (`src/agent-host/remote-adapter.ts`) forwards each turn to the host and treats everything the host sends back as untrusted, and which harnesses are hosted is one set in `src/harness-adapters.ts` (`HOSTED_HARNESSES`).
 
-The host is handed none of the runner's keys. Everything it calls that needs one goes through the runner's local proxy on `127.0.0.1` (`src/agent-proxy/`): model calls, the model registry, its telemetry (forwarded to the operator's collector with the collector's login, below), and on a runner behind the platform proxy the checkpoints. The platform's own MCP servers (memory, channels, the conversation tools) never carry the runner's own key: they carry a credential scoped to the run (in a hosted sandbox, the sandbox's session token until #2080), and a turn for which none can be had runs without them and says so. In a container shape the host's environment is an allow-list, so an ambient cloud identity in the runner's (`AWS_ACCESS_KEY_ID` and its siblings, `AWS_WEB_IDENTITY_TOKEN_FILE`, `GOOGLE_APPLICATION_CREDENTIALS`, Azure client secrets) does not reach it; on a local shape the host gets the runner's environment minus the runner's secret variables, as the agent's tools always did there. Each model lane serves its provider's model calls only, not the rest of the provider's API. The host authenticates with a token minted at each host start, and a model call is served only while a turn of the execution it names is running. On a runner that calls its providers directly, the proxy adds the operator's key or signs with the runner's cloud identity for each model backend (Anthropic, OpenAI, Bedrock, Vertex, Foundry), from the same settings as before; on a runner behind `STIGMER_PROXY_ENDPOINT`, it forwards to that proxy with the runner's own token. The Cursor SDK's traffic has a listener of its own on the proxy, TLS on loopback with a certificate made at each runner start, which the host trusts through `NODE_EXTRA_CA_CERTS` (added to any file the operator named there). The Cursor key exchange is made with the runner's credential, and the access token it returns stays in the runner: the host gets a stand-in, swapped back on every call. Of Cursor's Connect services the lane relays only what the SDK calls: the agent run and the side calls listed in `CURSOR_SIDE_CALLS` (`src/agent-proxy/cursor-lane.ts`); anything else is refused and logged once as `[agent-proxy] refused …`, so an SDK upgrade that adds a call fails the real-SDK wire test until the list names it. The proxy listens on loopback only and needs no configuration.
+The host is handed none of the runner's keys. Everything it calls that needs one goes through the runner's local proxy on `127.0.0.1` (`src/agent-proxy/`): model calls, the model registry, its telemetry (forwarded to the operator's collector with the collector's login, below), and on a runner behind the platform proxy the checkpoints. The platform's own MCP servers (memory, channels, the conversation tools) never carry the runner's own key: they carry a credential scoped to the run (in a hosted sandbox, the sandbox's session token until #2080), and a turn for which none can be had runs without them and says so. In a container shape the host's environment is an allow-list, so an ambient cloud identity in the runner's (`AWS_ACCESS_KEY_ID` and its siblings, `AWS_WEB_IDENTITY_TOKEN_FILE`, `GOOGLE_APPLICATION_CREDENTIALS`, Azure client secrets) does not reach it; on a local shape the host gets the runner's environment minus the runner's secret variables, as the agent's tools always did there. Each model lane serves its provider's model calls only, not the rest of the provider's API. The host authenticates with a token minted at each host start, and a model call is served only while a turn of the execution it names is running. On a runner that calls its providers directly, the proxy adds the operator's key or signs with the runner's cloud identity for each model backend (Anthropic, OpenAI, Bedrock, Vertex, Foundry), from the same settings as before; on a runner behind `STIGMER_PROXY_ENDPOINT`, it forwards to that proxy with the runner's own token. The proxy listens on loopback only and needs no configuration.
 
-The turn runtime's own work on the agent's paths (provisioning the workspace, the `.stigmer` link, skill, plugin and attachment mounts, the file-review capture, write-back's git) goes through `src/shared/agent-fs.ts`, which the runner routes to the host: each file operation and each process is performed there, so a link, a git hook or a `core.fsmonitor` the agent planted never acts with the runner's rights. `src/harness/__tests__/runtime-touches-no-agent-path.test.ts` holds the runtime's graph to that.
+The turn runtime's own work on the agent's paths (provisioning the workspace, the `.stigmer` link, skill, plugin and File mounts, the file-review capture, write-back's commits) goes through `src/shared/agent-fs.ts`, which the runner routes to the host: each file operation and each process is performed there, so a link, a git hook or a `core.fsmonitor` the agent planted never acts with the runner's rights. `src/harness/__tests__/runtime-touches-no-agent-path.test.ts` holds the runtime's graph to that. The one exception is git that talks to GitHub with a repository's token: the runner runs it itself, in a bare repository of its own under `~/.stigmer/git` (`src/shared/workspace/runner-git.ts`), never in the agent's clone, and moves commits to and from the clone as git bundles written and read through the host. So no process the agent can read ever holds the token, and what reaches GitHub is the session branch alone, whatever the clone's configuration says. That repository is a cache: deleted, it is fetched again, and on Kubernetes it sits on the runner container's own disk.
 
 **In a container shape** (root, Linux, started through the runner layer's `/runner/bin/start`, which exports `STIGMER_RUNNER_LAYER=1`), the runner starts the host as a user of its own, `stigmer-agent` (uid and gid 10001), through `setpriv` (`src/shared/agent-identity.ts`), with the agent's home (`STIGMER_AGENT_HOME`, else `/home/stigmer-agent`) as `HOME`, so nothing an agent runs can read the runner's process, files or keys. At boot it adds the user when the image lacks it, hands the agent its home and workspace (on the first such boot, moving the agent's session state into that home, `src/shared/agent-handover.ts`), and proves the drop works; a runner that cannot drop exits 78. It keeps only `SETUID`, `SETGID`, `CHOWN`, `KILL` (to end a host that will not exit, which root cannot signal without it) and `DAC_OVERRIDE` (to write its own state on a volume it shares with the server). There the host's environment is an allow-list (`src/agent-host/environment.ts`), with `STIGMER_AGENT_ENV_PASSTHROUGH` naming extra variables; a credential under an allowed prefix (`NODE_AUTH_TOKEN`, an OpenTelemetry `*_HEADERS` name the runner does not hold) is held back unless named there, and the collector's login (`OTEL_EXPORTER_OTLP_HEADERS` and its per-signal forms) is a runner secret that never reaches it: the host exports through the runner's local proxy. The agent's home may hold none of the runner's own files: a `STIGMER_AGENT_HOME` above the runner's home or inside its `~/.stigmer` is refused with exit 78 before the handover moves anything. `src/__tests__/agent-separation.container.test.ts` proves it in a container (`STIGMER_TEST_CONTAINER=1`). A workspace root inside the runner's home that the agent cannot pass (the default `~/.stigmer/workspaces/runner` under a driver's `/root`) is refused the same way, naming `WORKSPACE_ROOT_DIR`. Local shapes (`stigmer up`, the all-in-one image, which runs it, and the desktop app) run the host as the same user, whose keys are their own.
 
 Elsewhere the host starts with the environment the agent's tools have always seen: the runner's own, without the runner's secrets (`src/agent-host/environment.ts`). Its log lines are relayed through the runner's console unchanged. A host that exits is started again after one second, backing off to thirty; a turn running on it settles as an internal failure at once, and the next turn waits for the new host. The host exits when its pipe closes, so a runner that is killed leaves no host behind. `scripts/verify-agent-host-boot.mjs` (part of `npm run verify:dist`, and of `verify-slim-artifact.mjs` for the slim artifact) proves a build starts as the host.
 
+### The Claude engine
+
+A Claude turn runs Anthropic's engine: the Agent SDK (`@anthropic-ai/claude-agent-sdk`) and its per-platform package holding the `claude` executable, exactly as npm publishes them. The runner finds it at boot (`src/activities/execute-claude/engine-home.ts`): first its own install of the SDK (a checkout's development dependency, or an embedder's install beside `@stigmer/runner`), then the home for its pinned version under `STIGMER_ENGINES_DIR` (default `~/.stigmer/engines`). A published runner pins the version in `claude-engine.json` beside its entry, written from the lockfile with each package's registry URL and integrity, and loads no other version. Boot logs `[claude] engine ready <version> (<where>)`.
+
+- **The images** (the cloud sandbox, the runner layer, compose, Helm and the all-in-one) carry the engine in a layer of their own: the runner layer at `/runner/engines`, which its start script names as `STIGMER_ENGINES_DIR`, and the all-in-one at `/opt/stigmer/engines`.
+- **A local runner** (the desktop app, `stigmer up`, the `local-process` driver) carries only the pin. Its first Claude turn downloads the SDK and this machine's platform package from npm (120 to 140 MB), checks each against the pinned integrity before extracting it, and installs the home atomically under a lock, so runners sharing a machine download once (`src/activities/execute-claude/engine-fetch.ts`). The turn shows "Downloading Claude (one time): N%" while it does; a failed download ends the turn with a sentence saying so, and the next turn tries again. An install removes another version's home unused for 30 days.
+- **Behind a proxy**, the runner's Node 22 honours `HTTPS_PROXY` for the download only with `NODE_USE_ENV_PROXY=1` set beside it (measured; Node calls it experimental).
+- **A runner started from the runner layer never downloads**: its agent host runs as the agent user, which must never install an engine later turns run. Without the engine it refuses Claude turns.
+
+Anthropic's conditions for running the engine in a product bind every path: its bytes are never changed or re-signed, it runs on the API-key method only, and a Claude turn runs on the organization's own Anthropic key, never one of Stigmer's (`src/harness/README.md`, "The Claude engine").
+
 ### Traces: every run as OpenTelemetry GenAI spans
 
-The runner sends every run to the operator's tracing tool over OTLP, in OpenTelemetry's conventions for generative AI (`src/gen-ai-conventions.ts`): each turn an `invoke_agent <agent>` root span in a trace whose id is derived from the run id (`src/run-trace-id.ts`), so a run that resumed after an approval stays one trace; each model call a `chat <model>` span with its provider, model and tokens; each tool call an `execute_tool <tool>` span; a sub-agent an `invoke_agent <name>` span under its `task` call; a Cursor run an `invoke_agent Cursor` span with its summed tokens. It is configured only by the standard variables (`src/otel-export.ts`): an endpoint turns it on, `OTEL_EXPORTER_OTLP_PROTOCOL` picks `http/protobuf` (the default), `http/json` or `grpc`, and `OTEL_EXPORTER_OTLP_HEADERS` (with its per-signal forms) is the collector's login, a runner secret held in custody like the model keys. The conversation's text rides the spans only with `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`, and never shows more than the saved conversation does (`src/shared/telemetry-content.ts`). The agent host never holds the login: it exports to the local proxy's `otlp` lane, which forwards to the collector (`src/agent-proxy/otlp-forward.ts`). The operator's guide is `docs/guides/self-hosting/tracing.mdx`.
+The runner sends every run to the operator's tracing tool over OTLP, in OpenTelemetry's conventions for generative AI (`src/gen-ai-conventions.ts`): each turn an `invoke_agent <agent>` root span in a trace whose id is derived from the run id (`src/run-trace-id.ts`), so a run that resumed after an approval stays one trace; each model call a `chat <model>` span with its provider, model and tokens; each tool call an `execute_tool <tool>` span; a sub-agent an `invoke_agent <name>` span under its `task` call. It is configured only by the standard variables (`src/otel-export.ts`): an endpoint turns it on, `OTEL_EXPORTER_OTLP_PROTOCOL` picks `http/protobuf` (the default), `http/json` or `grpc`, and `OTEL_EXPORTER_OTLP_HEADERS` (with its per-signal forms) is the collector's login, a runner secret held in custody like the model keys. The conversation's text rides the spans only with `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`, and never shows more than the saved conversation does (`src/shared/telemetry-content.ts`). The agent host never holds the login: it exports to the local proxy's `otlp` lane, which forwards to the collector (`src/agent-proxy/otlp-forward.ts`). The operator's guide is `docs/guides/self-hosting/tracing.mdx`.
 
 ### A note for embedders: OpenTelemetry
 
@@ -127,9 +139,9 @@ When you embed the runner as a **library** (`createStigmerRunner` / `createStigm
 Two settings are easy to conflate but are deliberately independent:
 
 - **`MODE` — execution location.** Where the agent runs and whose filesystem it sees. `local` allows local-path workspaces on the host filesystem; `cloud` runs in a server-provisioned sandbox (git-only).
-- **`STIGMER_PROXY_ENDPOINT` — transport.** How credentials and artifacts move. When set, the runner routes Cursor SDK traffic through the Stigmer proxy and pushes artifacts through it, instead of talking to providers and storage directly.
+- **`STIGMER_PROXY_ENDPOINT` — transport.** How credentials and artifacts move. When set, the runner routes model traffic through the Stigmer proxy and pushes artifacts through it, instead of talking to providers and storage directly.
 
-These are orthogonal. The **desktop runner** is the canonical case where they diverge: it executes **locally** (`MODE=local`, so local-path workspaces work) yet still routes Cursor traffic and artifact uploads **through the proxy**. Coupling the two — forcing "proxy implies cloud" — is exactly what previously broke local-path sessions, which is why the env path (`MODE`) and both library factories (`executionMode`) treat them separately.
+These are orthogonal. The **desktop runner** is the canonical case where they diverge: it executes **locally** (`MODE=local`, so local-path workspaces work) yet still routes model traffic and artifact uploads **through the proxy**. Coupling the two — forcing "proxy implies cloud" — is exactly what previously broke local-path sessions, which is why the env path (`MODE`) and both library factories (`executionMode`) treat them separately.
 
 > **Library factories — `executionMode`.** Both `createStigmerRunner` and `createStigmerRunnerManager` accept an optional `executionMode: "local" | "cloud"` that sets execution location independently of proxy transport. When omitted, the static `createStigmerRunner` derives it for backward compatibility (`proxy ⇒ cloud`, otherwise `local`); the manager defaults to `local`. Set `executionMode: "local"` together with `proxyEndpoint` to express the desktop case — local execution with proxy transport.
 
@@ -137,8 +149,8 @@ These are orthogonal. The **desktop runner** is the canonical case where they di
 
 The transport setting drives two credential modes:
 
-- **Direct mode** (local / OSS): you provide `CURSOR_API_KEY` directly (for the Cursor harness); `STIGMER_TOKEN` is optional against a trusted-local server, which verifies no credential, and is the runner's own API key against a self-hosted server with sign-in on (the run's per-run credential arrives with each dispatch; see `src/shared/run-credential.ts`). `STIGMER_PROXY_ENDPOINT` is unset.
-- **Proxy mode** (cloud / managed runners): `STIGMER_PROXY_ENDPOINT` and `STIGMER_TOKEN` are required. You do not supply `CURSOR_API_KEY`: the Cursor key is the organization's own, saved in Settings → Provider keys, and the proxy validates your token and injects that key upstream, so the key never reaches the runner or the sandbox. An organization with no Cursor key is refused at the key exchange, and the turn fails with "This organization has no Cursor key. An admin can add one in Settings → Provider keys." The agent host's Cursor SDK talks to the runner's local proxy, which forwards to `STIGMER_PROXY_ENDPOINT`; `CURSOR_BACKEND_URL` in the host is runner-managed, not configuration you set. On a direct-mode runner, `CURSOR_BACKEND_URL` set on the runner still names the Cursor backend the local proxy calls.
+- **Direct mode** (local / OSS): the runner calls its model providers with the keys or cloud identity you configure; `STIGMER_TOKEN` is optional against a trusted-local server, which verifies no credential, and is the runner's own API key against a self-hosted server with sign-in on (the run's per-run credential arrives with each dispatch; see `src/shared/run-credential.ts`). `STIGMER_PROXY_ENDPOINT` is unset.
+- **Proxy mode** (cloud / managed runners): `STIGMER_PROXY_ENDPOINT` and `STIGMER_TOKEN` are required. The organization's own provider keys are saved on the Models & providers page, and the proxy validates your token and injects the key upstream, so the key never reaches the runner or the sandbox. The agent host's model calls go to the runner's local proxy, which forwards them to `STIGMER_PROXY_ENDPOINT`.
 
 ## Required infrastructure
 
@@ -146,7 +158,7 @@ The transport setting drives two credential modes:
 |-----------|------|---------|
 | Temporal | Always | The runner is a Temporal Worker. It needs a reachable Temporal frontend and a namespace. You may set these explicitly (`TEMPORAL_SERVICE_ADDRESS`, `TEMPORAL_NAMESPACE`), but when a token is present the runner self-discovers them from the control plane at boot — see the env reference below. |
 | Stigmer backend | Always | The control plane (`STIGMER_BACKEND_ENDPOINT`) for status updates, blueprints, and (local) artifact serving. |
-| Stigmer proxy + token | Proxy/cloud only | The proxy (`STIGMER_PROXY_ENDPOINT`) injects the organization's own Cursor key (saved in Settings → Provider keys) and brokers artifact storage; `STIGMER_TOKEN` authenticates to it. |
+| Stigmer proxy + token | Proxy/cloud only | The proxy (`STIGMER_PROXY_ENDPOINT`) injects the organization's own provider keys (saved on the Models & providers page) and brokers artifact storage; `STIGMER_TOKEN` authenticates to it. |
 
 In local/direct mode, only Temporal and the Stigmer backend are required, and both default to localhost.
 
@@ -174,16 +186,16 @@ All configuration is environment-driven. Every variable the runner's source read
 
 | Variable | Applies to | Required | Default | Purpose |
 |----------|-----------|----------|---------|---------|
-| `STIGMER_RUNNER_MODE` | All | No | `static` | Selects the run mode. Set to `manager` for dynamic per-session/per-execution Workers; any other value (or unset) means static mode, or pool mode when `STIGMER_POOL_MEMBER_ID` is set. |
-| `STIGMER_POOL_MEMBER_ID` | Hosted sandboxes | No | _(none)_ | Selects pool mode (see [Run modes](#run-modes)): the sandbox's identity in the warm pool. Set by the hosted edition's sandbox provisioning; a self-hosted runner never sets it. |
+| `STIGMER_RUNNER_MODE` | All | No | `static` | Selects the run mode. Set to `manager` for dynamic per-session/per-execution Workers; any other value (or unset) means static mode. |
 | `STIGMER_ATTACH_PORT` | The attach entry | No | `80` | Port the attach waiter listens on (`src/attach/entry.ts`), 80 being the port a Substrate router reaches without a `CONNECT` tunnel. Not passed to the runner. |
 | `STIGMER_SANDBOX_NAME_FILE` | The attach entry | No | `/run/ate/actor-name` | File holding this sandbox's name, read on every push because each clone of a snapshot has its own (a Substrate template projects it with an actor-metadata volume). A push for a queue whose sandbox name differs is refused. Not passed to the runner. |
+| `STIGMER_SANDBOX_ENVIRONMENT` | Sandboxes | No | _(none)_ | The sandbox's Environment as JSON, `{network, packages}`, set by the `docker` and `agent-sandbox` drivers and, on Substrate, by the attach waiter from the first push (`src/environment/spec.ts`). The runner installs the packages once its agent's home is handed over (apt as root, the other managers as the agent into `/opt/stigmer/environment`, first on the agent's `PATH`); each turn waits for the install. Unset: no Environment. |
 | `STIGMER_SERVER_RELEASE` | The start script | No | _(none)_ | The server's release, set when the server is a release by the built-in `agent-sandbox`, `docker` and `substrate` drivers, and by a composition's own driver once it hands `SandboxDriverConfig.serverRelease` on (`SERVER_RELEASE_ENV` in the server's `src/sandbox/runner-launch.ts`); a sandbox started without it is not checked. The layer's start script (`layer/start.sh`) refuses a layer whose `/runner/RELEASE` names another release, and warns about one that names none. Read by the start script only, not by the runner. |
 | `MODE` | All | No | `local` | Execution location: `local` (host filesystem, local-path workspaces) or `cloud` (server-provisioned sandbox, git-only). Independent of `STIGMER_PROXY_ENDPOINT`. Also the default for the two guards below. |
-| `STIGMER_WEB_FETCH_ALLOW_PRIVATE` | All (native `web_fetch`) | No | follows `MODE`: strict in `cloud`, relaxed in `local` | The `web_fetch` address guard's override. `true` lets the agent fetch loopback and private-network addresses on any runner (link-local, which holds the cloud metadata endpoint, stays refused); `false` refuses them on a local runner too. For embedders whose execution location and network differ; managed cloud deployments never set it. See `src/tools/url-guard.ts`. |
+| `STIGMER_WEB_FETCH_ALLOW_PRIVATE` | All (the Stigmer harness's `web_fetch`) | No | follows `MODE`: strict in `cloud`, relaxed in `local` | The `web_fetch` address guard's override. `true` lets the agent fetch loopback and private-network addresses on any runner (link-local, which holds the cloud metadata endpoint, stays refused); `false` refuses them on a local runner too. For embedders whose execution location and network differ; managed cloud deployments never set it. See `src/tools/url-guard.ts`. |
 | `STIGMER_MCP_ALLOW_STDIO` | All | No | follows `MODE`: forbidden in `cloud`, allowed in `local` | The MCP transport guard's override. `true` lets a cloud runner start stdio MCP servers, which download a package and run it as a subprocess holding the execution's secrets; `false` forbids them on a local runner too. For rolling the policy back without a redeploy; managed cloud deployments never set it. See `src/shared/mcp-transport-guard.ts`. |
-| `STIGMER_TASK_QUEUE` | Static mode | No | `stigmer_runner` | Temporal task queue the static Worker polls. (Legacy alias: `TEMPORAL_AGENT_EXECUTION_RUNNER_TASK_QUEUE`.) Unused in manager mode, where each Worker derives its own queue. |
-| `TEMPORAL_SERVICE_ADDRESS` | All | No | _(discovered)_ | Address of the Temporal frontend. **Resolution order:** an explicit value always wins; otherwise, if `STIGMER_TOKEN` is set, the runner discovers it from the control plane at boot (`getRunnerBootstrapConfig`); otherwise it falls back to `localhost:7233`. Discovery failure aborts startup with an actionable error (no silent fallback). |
+| `STIGMER_TASK_QUEUE` | Static mode | No | `stigmer_runner` | Temporal task queue the static Worker polls. Unused in manager mode, where each Worker derives its own queue. |
+| `TEMPORAL_SERVICE_ADDRESS` | All | No | _(discovered)_ | Address of the Temporal frontend. **Resolution order:** an explicit value always wins; otherwise, if `STIGMER_TOKEN` is set, the runner discovers it from the control plane at boot (`getRunnerBootstrapConfig`); otherwise it falls back to `localhost:7233`. Discovery failure aborts startup with an actionable error (no silent fallback). When the address is the backend endpoint's own host and port, the runner reaches Temporal through the Stigmer server, as a sandboxed runner does: its `STIGMER_TOKEN` is its Temporal API key, TLS follows the endpoint's scheme, and the `STIGMER_TEMPORAL_*` settings below must be unset (`src/temporal-lane.ts`). |
 | `TEMPORAL_NAMESPACE` | All | No | `default` | Temporal namespace. |
 | `STIGMER_TEMPORAL_API_KEY` | All | No | — | Temporal frontend API key (Temporal Cloud, or a frontend with an authorizer); implies TLS. Taken into the credential store at boot, so agent tools never see it. |
 | `STIGMER_TEMPORAL_TLS` | All | No | — | `true` or `1`: TLS to the frontend against the system's trusted roots. A CA, a client certificate or an API key implies it. |
@@ -192,15 +204,14 @@ All configuration is environment-driven. Every variable the runner's source read
 | `STIGMER_TEMPORAL_TLS_CLIENT_CERT_DATA` / `_PATH`, `STIGMER_TEMPORAL_TLS_CLIENT_KEY_DATA` / `_PATH` | All | No | — | Mutual TLS: the client certificate and its key, both or neither (half a pair stops the boot). The key's `_DATA` form is taken into the credential store; a `_PATH` key is a file the agent's tools can read, so prefer `_DATA`. These are Stigmer's own names: Temporal's `TEMPORAL_API_KEY` and `TEMPORAL_TLS_*` belong to the user's own Temporal work and are never read. |
 | `STIGMER_BACKEND_ENDPOINT` | All | In cloud mode | `http://localhost:7234` (local) | Stigmer backend endpoint for status, blueprints, and local artifact serving. A bare `host:port` is normalized to `http://` (or `https://` for port `443`). |
 | `STIGMER_TOKEN` | Cloud or proxy mode | Yes (cloud/proxy) | _(none)_ | Auth token for the Stigmer backend / proxy. Required when `MODE=cloud` or `STIGMER_PROXY_ENDPOINT` is set; optional in local/direct mode. |
-| `CURSOR_API_KEY` | Direct mode | Yes (Cursor harness, direct) | _(empty)_ | Cursor API key for direct mode. In proxy mode it is not required: the proxy injects the organization's own Cursor key (saved in Settings → Provider keys), so the key never reaches the sandbox, and the SDK transport presents the current `STIGMER_TOKEN` (read per turn, so a rotated token is honoured). |
-| `STIGMER_PROXY_ENDPOINT` | Proxy/cloud | No | _(none)_ | Stigmer proxy endpoint. When set, activates proxy transport: Cursor SDK traffic and artifact uploads are routed through the proxy. |
-| `GIT_CONFIG_COUNT` | Git workspaces | No | _(none)_ | git's own per-command configuration, honoured as git honours it: a runner that sets it (a container's `safe.directory`, for one) keeps it, and the settings that hand a repository's token to a network git command are appended after it (`src/shared/workspace/git-credential.ts`), never in its place. |
+| `STIGMER_PROXY_ENDPOINT` | Proxy/cloud | No | _(none)_ | Stigmer proxy endpoint. When set, activates proxy transport: model traffic and artifact uploads are routed through the proxy. |
+| `GIT_CONFIG_COUNT` | Git workspaces | No | _(none)_ | git's own per-command configuration, honoured as git honours it: a runner that sets it (a container's `safe.directory`, for one) keeps it, and the settings that hand a repository's token to the runner's own git are appended after it (`src/shared/workspace/git-credential.ts`), never in its place. |
 | `WORKSPACE_ROOT_DIR` | All | No | `~/.stigmer/workspaces/runner` (fallback) | Root directory for agent workspaces. If unset, the runner warns and creates an isolated fallback directory — it never falls back to the process working directory. |
+| `STIGMER_ENGINES_DIR` | All | No | `~/.stigmer/engines`; `/runner/engines` under the runner layer | Where the Claude engine lives: one home per version, `<dir>/claude/<version>/node_modules/@anthropic-ai/`, holding the Agent SDK and its platform package exactly as npm publishes them. The runner layer's start script sets it to the engine the layer carries. A local runner (the desktop app, `stigmer up`, the `local-process` driver) that finds none downloads the version its `claude-engine.json` pins into it on the first Claude turn; on a machine that cannot download, put the two packages there yourself. The runner's own install of the SDK, when it has one, is used first. See [The Claude engine](#the-claude-engine). |
 | `TEMPORAL_MAX_CONCURRENCY` | All | No | `5` | Maximum concurrent Temporal activity executions (per session Worker in manager mode). |
-| `STIGMER_CHECKPOINTER_TYPE` | All | No | `sqlite` (local), `http` (cloud) | LangGraph checkpointer backend for the native harness's agent state: `sqlite` (a durable per-session file under the platform dir, so a paused or interrupted run resumes across invocations), `http` (the proxy-backed saver), or `memory` (ephemeral; test runs only — a paused run cannot resume on it). |
+| `STIGMER_CHECKPOINTER_TYPE` | All | No | `sqlite` (local), `http` (cloud) | LangGraph checkpointer backend for the Stigmer harness's agent state: `sqlite` (a durable per-session file under the platform dir, so a paused or interrupted run resumes across invocations), `http` (the proxy-backed saver), or `memory` (ephemeral; test runs only — a paused run cannot resume on it). The same setting places the Claude harness's conversation: a per-session transcript file under the session directory (`sqlite`), the platform's engine-sessions lane through the local proxy (`http`), or memory. |
 | `STIGMER_CHECKPOINTER_PROXY_ENDPOINT` | `http` checkpointer | No | value of `STIGMER_PROXY_ENDPOINT` | Endpoint for the HTTP checkpointer; falls back to the proxy endpoint. |
 | `STIGMER_PRIMARY_MODEL` | All | No | `gpt-4.1` | Default LLM model identifier. |
-| `STIGMER_CURSOR_CLOUD_MODE_ENABLED` | All | No | `false` | When `true`, enables Cursor cloud (workspace-less) execution mode for the Cursor harness. |
 | `STIGMER_IDLE_TIMEOUT_SECONDS` | All | No | _(none)_ | **Reserved.** Parsed from the environment but not currently honored by the runtime — no component reads it today. Documented for completeness; setting it has no effect. |
 
 ### Artifact storage
@@ -209,7 +220,7 @@ All configuration is environment-driven. Every variable the runner's source read
 |----------|-----------|----------|---------|---------|
 | `ARTIFACT_STORAGE_TYPE` | All | No | `proxy` if `STIGMER_ARTIFACT_PROXY_ENDPOINT` or `STIGMER_PROXY_ENDPOINT` is set, else `local` | Selects the artifact backend: `local` (filesystem, served by the Stigmer backend), `proxy` (presigned URLs via the proxy), or `none` (storage deliberately disabled: artifact features are refused rather than stored). An explicit value always wins. Storage follows transport, not execution location (`src/shared/artifact-storage.ts`). |
 | `STIGMER_ARTIFACT_PROXY_ENDPOINT` | Proxy storage | No | value of `STIGMER_PROXY_ENDPOINT` | Endpoint the proxy artifact store presigns against, when artifact traffic must reach a different host than LLM traffic (the checkpointer-override pattern). |
-| `LOCAL_ARTIFACT_PATH` | Local storage | No | `~/.stigmer/data/artifacts` | Filesystem root of the local artifact store. **Must equal the stigmer-server's `ARTIFACT_LOCAL_BASE_PATH`** — in local mode the server writes an artifact to `<ARTIFACT_LOCAL_BASE_PATH>/<key>` and the runner reads it from `<LOCAL_ARTIFACT_PATH>/<key>`, so a mismatch makes every storage-key attachment and offload fail to resolve. The defaults align out of the box; the CLI local daemon sets both explicitly. |
+| `LOCAL_ARTIFACT_PATH` | Local storage | No | `~/.stigmer/data/artifacts` | Filesystem root of the local artifact store. **Must equal the stigmer-server's `ARTIFACT_LOCAL_BASE_PATH`** — in local mode the server writes an artifact to `<ARTIFACT_LOCAL_BASE_PATH>/<key>` and the runner reads it from `<LOCAL_ARTIFACT_PATH>/<key>`, so a mismatch makes every artifact read and offload fail to resolve. The defaults align out of the box; the CLI local daemon sets both explicitly. |
 
 ### Payload encryption (Temporal history at rest)
 
@@ -239,10 +250,10 @@ The claim-check codec offloads oversized Temporal payloads to artifact storage a
 
 | Variable | Applies to | Required | Default | Purpose |
 |----------|-----------|----------|---------|---------|
-| `OPENAI_API_KEY` | Direct mode (native/OpenAI) | When using OpenAI directly | _(empty)_ | OpenAI API key for the native harness in direct mode. Not needed in proxy mode. |
-| `ANTHROPIC_API_KEY` | Direct mode (native/Anthropic) | When using Anthropic directly | _(empty)_ | Anthropic API key for the native harness in direct mode. Not needed in proxy mode. |
-| `ANTHROPIC_BASE_URL` | Direct mode (native/Anthropic, `public` backend) | No | _(empty: api.anthropic.com)_ | The address of an LLM gateway in front of Anthropic (the API root, without `/v1`). A value that is not an http(s) URL stops the runner at startup; ignored, with a warning, under the proxy or a non-`public` backend. |
-| `STIGMER_LLM_REQUEST_TIMEOUT_MS` | Native harness | No | `0` (no timeout) | Per-request timeout for native LLM calls, in milliseconds. `0` or unset means no explicit timeout. |
+| `OPENAI_API_KEY` | Direct mode (Stigmer/OpenAI) | When using OpenAI directly | _(empty)_ | OpenAI API key for the Stigmer harness in direct mode. Not needed in proxy mode. |
+| `ANTHROPIC_API_KEY` | Direct mode (Stigmer/Anthropic) | When using Anthropic directly | _(empty)_ | Anthropic API key for the Stigmer harness in direct mode. Not needed in proxy mode. |
+| `ANTHROPIC_BASE_URL` | Direct mode (Stigmer/Anthropic, `public` backend) | No | _(empty: api.anthropic.com)_ | The address of an LLM gateway in front of Anthropic (the API root, without `/v1`). A value that is not an http(s) URL stops the runner at startup; ignored, with a warning, under the proxy or a non-`public` backend. |
+| `STIGMER_LLM_REQUEST_TIMEOUT_MS` | Stigmer harness | No | `0` (no timeout) | Per-attempt bound on a Stigmer-harness LLM request, in milliseconds. On a streamed reply (every agent turn) it bounds the wait for the reply to begin, and a timed-out attempt is retried like any other passing failure; on a reply that does not stream (structured extraction, session subjects) it bounds the whole reply, and a timed-out attempt is not retried (`src/shared/model-retry.ts`). `0` or unset means no explicit timeout. |
 | `STIGMER_CLOUD_API_URL` | All | No | _(unset)_ | Explicit override for the origin serving `/v1/proxy/model-registry` (model resolution and pricing). When unset, fetches go to `STIGMER_PROXY_ENDPOINT` (proxy mode) or `STIGMER_BACKEND_ENDPOINT` (direct/local mode — the local stigmer-server serves the registry). |
 | `STIGMER_AUTH_TOKEN` | Pricing/registry fetch | No | value of `STIGMER_TOKEN` | Fallback bearer token for model-pricing and model-registry requests when `STIGMER_TOKEN` is not set. |
 | `GITHUB_TOKEN` | Deep-agent git writeback | When writing back to GitHub | _(none)_ | Token used by the deep-agent harness for git writeback operations. |
@@ -250,7 +261,7 @@ The claim-check codec offloads oversized Temporal payloads to artifact storage a
 
 ### Model backends
 
-Where the native harness's models are served when the runner talks to providers directly. Under `STIGMER_PROXY_ENDPOINT` the proxy owns provider routing, and the runner warns that a non-`public` backend is ignored. The [model backends guide](https://stigmer.ai/docs/guides/runners/model-backends) is the one explanation of each backend, its credentials and its errors; the rows below index what the runner reads.
+Where the Stigmer harness's models are served when the runner talks to providers directly. Under `STIGMER_PROXY_ENDPOINT` the proxy owns provider routing, and the runner warns that a non-`public` backend is ignored. The [model backends guide](https://stigmer.ai/docs/guides/runners/model-backends) is the one explanation of each backend, its credentials and its errors; the rows below index what the runner reads.
 
 | Variable | Applies to | Required | Default | Purpose |
 |----------|-----------|----------|---------|---------|
@@ -290,15 +301,16 @@ These tune internal behavior or support testing. Most operators never set them.
 | `STREAMING_MAX_INTERVAL_MS` | `5000` | Maximum time before a forced keepalive status update. Clamped up to the min if set lower. |
 | `STREAMING_BURST_THRESHOLD` | `50` | Event count that triggers an immediate status update (burst protection). |
 | `STIGMER_PROGRESS_CAPTURE_MIN_INTERVAL_MS` | `2000` | Minimum time between two mid-run captures of the "N files changed so far" strip. Each capture stages the working tree with git (git workspaces) or reads the touched files (other workspaces), so this bounds that cost however often status is written. Read once at startup; a non-numeric or negative value keeps the default, and `0` captures on every status write. |
-| `CURSOR_STREAM_STALL_TIMEOUT_MS` | `180000` (3 min) | **Parsed but not yet honoured** ([#1731](https://github.com/stigmer/stigmer/issues/1731)): `loadConfig` reads it, but no boot path passes it to the runner, so the default always applies to `stigmer-runner`. The bound it names: how long an engine may report no activity before the run is cancelled and the execution fails with a stall error, for every harness (the name is the Cursor harness's, its first user). Embedders set it through the `cursorStreamStallTimeoutMs` option. |
-| `CURSOR_AGENT_RESOLVE_TIMEOUT_MS` | `120000` (2 min) | **Parsed but not yet honoured**, as above; embedders use the `agentResolveTimeoutMs` option. The bound it names: the Cursor SDK's agent create or resume, which has no timeout of its own; on expiry the execution fails with a transport diagnosis instead of hanging until Temporal's heartbeat timeout. |
-| `STIGMER_CURSOR_AGENT_CACHE_TTL_MS` | `1800000` (30 min) | How long an idle Cursor agent stays parked between turns, holding its MCP subprocesses, before it is closed. A non-positive or non-numeric value keeps the default. |
-| `WORKSPACE_LOCK_TIMEOUT_MS` | `900000` (15 min) | **Parsed but not yet honoured**, as above; embedders use the `workspaceLockTimeoutMs` option. The bound it names: how long a turn waits for another session's lock on the same workspace before the execution fails with "workspace is in use by another session" (`src/shared/workspace/workspace-lock.ts`). |
-| `STIGMER_MCP_BRIDGE_ENDPOINT` | _(none)_ | The MCP bridge the runner's own attachments (channel messaging, conversation participation) connect to, as `https://…`. Unset selects the local shape: a spawned `stigmer mcp-server` stdio child against the local backend. |
-| `STIGMER_WORKFLOW_BUNDLE` | _(discovered)_ | An explicit path to the pre-built Temporal workflow bundle, for tests and for embedders that stage it elsewhere (`src/workflow-source.ts`). A path that does not exist stops the boot. |
+| `CURSOR_STREAM_STALL_TIMEOUT_MS` | `180000` (3 min) | How long a turn may go with nothing open and nothing arriving before the run is cancelled and the execution fails with a stall error, for every harness (the name predates the harnesses that read it). A tool call or delegated task that is still running holds it, so a long silent build is not a stall (`src/harness/open-operations.ts`). Embedders set it through the `cursorStreamStallTimeoutMs` option. |
+| `STIGMER_OPEN_OPERATION_MAX_MS` | `3600000` (60 min) | The backstop for one open operation: a tool call or delegated task still running after this long is stopped and the execution fails with a sentence naming it. It exists for what has no bound of the runner's own (an engine's opaque tool); every operation the runner runs itself is bounded well below it. Embedders set it through the `openOperationMaxMs` option. |
+| `STIGMER_DRAIN_GRACE_MS` | `25000` (25 s) | How long a static runner's shutdown waits for the turns in flight to reach a step boundary (Temporal's `shutdownGraceTime`). A turn that reaches one stops there and continues on the next runner; one still mid-step when it runs out is stopped there and continues too, running that step again. Keep it under the host's own termination grace: the default sits under Kubernetes' 30 s, and the agent sandbox's pod, whose grace is 600 s, sets 540 s. Embedders set it through the `drainGraceMs` option. The desktop manager has none: it exits at once. |
+| `STIGMER_LIVENESS_INTERVAL_MS` | `30000` (30 s) | How often a working turn says what it has open: the runner sends a `stigmer.run.liveness` preview naming each open operation and its age at this interval while the turn runs, and at once when what is open changes, so a watcher that reconnects learns within the interval. From 1000 to under 60000; any other value falls back to the default with a warning. Embedders set it through the `livenessIntervalMs` option. |
+| `STIGMER_SHELL_TIMEOUT_MAX_SECONDS` | `3300` (55 min) | The most the Stigmer harness's model may raise one shell command's timeout to; a command's default bound is 120 s, and a larger request is clamped to this and the result says so. A command the agent starts in the background (`execute` with `background: true`) is bounded by this unless it asks for less; it is stopped, and awaited, when its turn's invocation ends, an approval pause included, and the agent can stop it sooner with `stop_background_command` (`src/shared/shell/background-commands.ts`). The session's log carries each one's life as `stigmer.background_command.status` beside the call that started it, with its output previewed under that call (`src/activities/execute-deep-agent/background-facts.ts`), so the console shows it running and how it ended; a person can stop one alone (`SessionCommandController.stopBackgroundCommand`), which the runtime reads every 2 s while a command runs (`src/harness/background-stops.ts`). Kept under `STIGMER_OPEN_OPERATION_MAX_MS`, so the shell's own bound fires first. Embedders set it through the `shellTimeoutMaxSeconds` option. |
+| `STIGMER_SHELL_BACKGROUND_ENABLED` | `true` | Whether the Stigmer harness's model may start a shell command in the background. `false` turns it off: `execute` is declared without `background`, `stop_background_command` is not bound, and no turn waits at its end for a command, so every command runs in the foreground, a turn never waits on one, and a sandbox never stays awake for one. Any other value keeps it on with a warning. Embedders set it through the `shellBackgroundEnabled` option. |
+| `WORKSPACE_LOCK_TIMEOUT_MS` | `900000` (15 min) | How long a turn waits for another session's lock on the same workspace before the execution fails with "workspace is in use by another session" (`src/shared/workspace/workspace-lock.ts`). Embedders use the `workspaceLockTimeoutMs` option. |
+| `STIGMER_MCP_BRIDGE_ENDPOINT` | _(none)_ | The MCP bridge the runner's own attachments (memory, channel messaging, conversation participation) connect to, as `https://…`. An embedded runner that discovers its Temporal coordinates from a server also learns the bridge from it, when the server names one (`STIGMER_RUNNER_BOOTSTRAP_MCP_BRIDGE_ENDPOINT`); a value set here wins. Neither selects the local shape: a spawned `stigmer mcp-server` stdio child against the local backend. |
 | `SKIP_MCP_CONNECT_BACKFILL` | `false` | When `true`, skips MCP Connect backfill. |
 | `STIGMER_MCP_PUBLIC_ENDPOINT` | _(none)_ | The server's public endpoint. A server that provisions this runner's sandbox sets it from its own configuration (`STIGMER_SANDBOX_MCP_PUBLIC_ENDPOINT`). Fills `STIGMER_SERVER_ADDRESS` (as `host:port`) for MCP servers that declare it and carry no value; without it, only stdio servers are filled, from `STIGMER_BACKEND_ENDPOINT`. A value already present is never overridden. |
-| `CURSOR_EVENT_RECORD_DIR` | _(none)_ | Directory to record Cursor harness events (debugging/fixtures). |
 | `V3_EVENT_RECORD_DIR` | _(none)_ | Directory to record deep-agent harness events (debugging/fixtures). |
 
 ## Related documentation

package/dist/.build-fingerprint

@@ -1 +1 @@
-{"hash":"08bc52db3583a672","builtAt":"2026-10-17T06:48:02.891Z","fileCount":363}
+{"hash":"9ac3c1b119ed74a8","builtAt":"2026-11-05T11:02:34.439Z","fileCount":385}

package/dist/activities/ensure-thread.d.ts

@@ -2,8 +2,8 @@
  * EnsureThread Temporal activity — resolves a LangGraph thread ID for an
  * agent execution.
  *
- * Called by the Java/Go InvokeAgentExecutionWorkflow as Step 1 of the
- * native (deep-agent) harness flow, before ExecuteDeepAgent. The returned
+ * Called by the server's InvokeAgentExecutionWorkflow as Step 1 of the
+ * Stigmer harness flow, before ExecuteDeepAgent. The returned
  * thread ID keys the LangGraph checkpointer for conversation continuity.
  *
  * Thread ID conventions (load-bearing for proxy authorization):

package/dist/activities/ensure-thread.js

@@ -2,8 +2,8 @@
  * EnsureThread Temporal activity — resolves a LangGraph thread ID for an
  * agent execution.
  *
- * Called by the Java/Go InvokeAgentExecutionWorkflow as Step 1 of the
- * native (deep-agent) harness flow, before ExecuteDeepAgent. The returned
+ * Called by the server's InvokeAgentExecutionWorkflow as Step 1 of the
+ * Stigmer harness flow, before ExecuteDeepAgent. The returned
  * thread ID keys the LangGraph checkpointer for conversation continuity.
  *
  * Thread ID conventions (load-bearing for proxy authorization):
@@ -20,10 +20,12 @@
  *   Output: string (thread ID)
  */
 import { randomUUID } from "node:crypto";
+import { ENSURE_THREAD_ACTIVITY_NAME } from "@stigmer/temporal-codecs/activity-names";
 import { activityStarted, activityFinished } from "../idle-watchdog.js";
 export function createEnsureThreadActivities() {
     return {
-        EnsureThread: async (sessionId, agentId) => {
+        // Registered under the name the server's workflow schedules, declared once for both.
+        [ENSURE_THREAD_ACTIVITY_NAME]: async (sessionId, agentId) => {
             activityStarted();
             try {
                 if (sessionId) {

package/dist/activities/ensure-thread.js.map

@@ -1 +1 @@
-{"version":3,"file":"ensure-thread.js","sourceRoot":"","sources":["../../src/activities/ensure-thread.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAExE,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,YAAY,EAAE,KAAK,EAAE,SAAiB,EAAE,OAAe,EAAmB,EAAE;YAC1E,eAAe,EAAE,CAAC;YAClB,IAAI,CAAC;gBACH,IAAI,SAAS,EAAE,CAAC;oBACd,MAAM,QAAQ,GAAG,UAAU,SAAS,EAAE,CAAC;oBACvC,OAAO,CAAC,GAAG,CAAC,wCAAwC,QAAQ,EAAE,CAAC,CAAC;oBAChE,OAAO,QAAQ,CAAC;gBAClB,CAAC;gBAED,MAAM,QAAQ,GAAG,aAAa,OAAO,IAAI,UAAU,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;gBACtF,OAAO,CAAC,GAAG,CAAC,oCAAoC,QAAQ,EAAE,CAAC,CAAC;gBAC5D,OAAO,QAAQ,CAAC;YAClB,CAAC;oBAAS,CAAC;gBACT,gBAAgB,EAAE,CAAC;YACrB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"ensure-thread.js","sourceRoot":"","sources":["../../src/activities/ensure-thread.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,2BAA2B,EAAE,MAAM,yCAAyC,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAExE,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,qFAAqF;QACrF,CAAC,2BAA2B,CAAC,EAAE,KAAK,EAAE,SAAiB,EAAE,OAAe,EAAmB,EAAE;YAC3F,eAAe,EAAE,CAAC;YAClB,IAAI,CAAC;gBACH,IAAI,SAAS,EAAE,CAAC;oBACd,MAAM,QAAQ,GAAG,UAAU,SAAS,EAAE,CAAC;oBACvC,OAAO,CAAC,GAAG,CAAC,wCAAwC,QAAQ,EAAE,CAAC,CAAC;oBAChE,OAAO,QAAQ,CAAC;gBAClB,CAAC;gBAED,MAAM,QAAQ,GAAG,aAAa,OAAO,IAAI,UAAU,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;gBACtF,OAAO,CAAC,GAAG,CAAC,oCAAoC,QAAQ,EAAE,CAAC,CAAC;gBAC5D,OAAO,QAAQ,CAAC;YAClB,CAAC;oBAAS,CAAC;gBACT,gBAAgB,EAAE,CAAC;YACrB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/activities/execute-claude/adapter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The Claude harness as a `HarnessAdapter` — the worker- and session-
+ * lifetime half of its Agent SDK slice, behind the turn runtime's contract
+ * (`harness/types.ts`). One engine turn is `turn.ts`'s `runClaudeTurn`; this
+ * module boots and delegates.
+ *
+ * THIS MODULE'S STATIC GRAPH IS SDK-FREE, ON PURPOSE, as every adapter's is
+ * (`harness-adapters.ts`): `@anthropic-ai/claude-agent-sdk` and the turn
+ * module are loaded with a dynamic import inside `boot`.
+ * `__tests__/adapter-graph-is-sdk-free.test.ts` pins it.
+ *
+ * WHERE THE ENGINE COMES FROM (`engine-home.ts` has the order and the pin).
+ * `boot` finds it once and leaves one of three states:
+ *
+ *  - ready: the engine loaded, from the runner's own install or an engine
+ *    home, and boot logged `[claude] engine ready <version> (<where>)`;
+ *  - fetchable: no engine, but the runner carries its pin and was not started
+ *    from the runner layer. This is a local runner (the desktop app,
+ *    `stigmer up`, the `local-process` driver), and its first Claude turn
+ *    installs the engine into its home (`engine-fetch.ts`), showing
+ *    "Downloading Claude (one time): N%" in the turn's setup label, then
+ *    loads it and runs; every later turn starts at once. A failed download
+ *    ends the turn `actionable` with {@link downloadFailedMessage}, and the
+ *    next turn tries again;
+ *  - absent: neither. The turn fails `actionable` with
+ *    {@link NOT_INSTALLED_MESSAGE} before anything runs.
+ *
+ * A runner started from the runner layer (`layer/start.sh` exports
+ * `STIGMER_RUNNER_LAYER=1`, which reaches the agent host under its
+ * `STIGMER_` prefix) never fetches: every image built on the layer carries
+ * the engine in it, and in a separating runner this host runs as the agent
+ * user, which must never install an engine later turns run. The marker is
+ * read, not `agentIdentity()`: inside the separated host that is always
+ * null (it runs as uid 10001, and the identity is the runner's to know).
+ *
+ * A worker that failed its boot over one engine would take the others down
+ * with it, so nothing here throws out of `boot`.
+ *
+ * Anthropic's conditions for running the engine in a product bind this
+ * slice (`harness/README.md`, "The Claude engine"): the engine's bytes are
+ * never changed or re-signed, it runs on the API-key method only
+ * (`engine-env.ts`), and no Claude turn runs on a Stigmer-owned key.
+ *
+ * Nothing is parked per session: each invocation starts the engine's
+ * process and ends it, and the session's conversation lives in the session
+ * store (`session-store.ts`), so `releaseSession` is a no-op and `shutdown`
+ * holds nothing.
+ *
+ * What this adapter never does: throw out of `runTurn`, branch on why
+ * `stopSignal` aborted, write a phase or a terminal copy, bind a state id
+ * (the session id derives from the runtime's thread id, `deterministic`), or
+ * import `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
+ */
+import type { Config } from "../../config.js";
+import type { HarnessAdapter } from "../../harness/types.js";
+import { findClaudeEngine, type ClaudeEnginePin, type FoundEngine } from "./engine-home.js";
+import type { ClaudeAdapterConfig, ClaudeSdk } from "./turn.js";
+/** What a Claude turn on a runner without the engine is refused with. */
+export declare const NOT_INSTALLED_MESSAGE = "The Claude Agent SDK is not installed on this runner, so this turn cannot run on the Claude Agent harness. Run it on another harness.";
+/** What a Claude turn whose engine could not be downloaded ends with; the next turn tries again. */
+export declare function downloadFailedMessage(reason: string): string;
+/** The setup label while the engine downloads. */
+export declare function downloadLabel(percent: number): string;
+/** The least time between two download labels, so a fast download does not write a status per chunk. */
+export declare const DOWNLOAD_LABEL_INTERVAL_MS = 1000;
+/** The config slice this adapter reads per turn, taken at `boot`; a whole `Config` satisfies it. */
+export declare function resolveClaudeConfig(config: Config): ClaudeAdapterConfig;
+/** What `boot` reads from where it runs; a test replaces any of it. */
+export interface ClaudeBootDeps {
+    readonly env: NodeJS.ProcessEnv;
+    readonly readPin: () => ClaudeEnginePin | null;
+    readonly find: typeof findClaudeEngine;
+    /** Imports a found engine's SDK: the runner's own by its bare name, a home's by file URL. */
+    readonly load: (engine: FoundEngine) => Promise<ClaudeSdk>;
+    /** Installs the engine for one turn (`engine-fetch.ts` `installForTurn`, loaded on first use). */
+    readonly install: (options: {
+        readonly root: string;
+        readonly pin: ClaudeEnginePin;
+        readonly platformPackage: string;
+    }, waiter: {
+        readonly signal: AbortSignal;
+        readonly onProgress: (fraction: number) => void;
+        readonly onActivity: () => void;
+    }) => Promise<{
+        readonly home: string;
+        readonly downloaded: boolean;
+    }>;
+    readonly now: () => number;
+}
+export declare function createClaudeAdapter(overrides?: Partial<ClaudeBootDeps>): HarnessAdapter;