@sagentlab/navarch-runtime 0.1.0

package/README.md

@@ -0,0 +1,351 @@
+# navarch-runtime
+
+The machine-side half of Navarch (WP-07): registers this machine with the
+control plane, then loops claim → sandbox → agent CLI → report until you stop
+it. Plain Node/TypeScript, zero production dependencies, no Next.js coupling
+— this directory is a self-contained package you can `npx` on any fresh
+machine.
+
+The agent CLI a session runs is either **Claude Code** or **OpenAI Codex**,
+selected per machine via `FLOTILLA_AGENT` (default `claude-code`) — see
+"Choosing an agent (Claude Code vs. Codex)" below.
+
+See [`docs/agent-platform-project-plan.md`](../docs/agent-platform-project-plan.md)
+§3.8/§3.9/§3.11 and [`docs/flotilla/implementation-plan.md`](../docs/flotilla/implementation-plan.md)
+WP-07 for the design this implements, and
+[`docs/flotilla/schema-design.md`](../docs/flotilla/schema-design.md) §7 for
+the API contract.
+
+## Quick start on a fresh machine
+
+```sh
+git clone <this repo> && cd sagentlab/runtime
+./install.sh          # checks node/docker, npm install, npm run build
+export FLOTILLA_API_BASE=https://flotilla.example.com
+node bin/navarch.cjs register --token <enrollment-token> --name my-machine-1
+node bin/navarch.cjs start
+```
+
+Or, once dependencies are installed:
+
+```sh
+npm run build
+FLOTILLA_API_BASE=https://flotilla.example.com npm run register -- --token <enrollment-token> --name my-machine-1
+npm start
+```
+
+`register` is the one command that prints the machine's auth token — exactly
+once, to stdout. It is stored at `$FLOTILLA_CONFIG_DIR/machine.json` (default
+`~/.flotilla/machine.json`, mode `0600`) and never echoed again. For
+twelve-factor deployments (systemd `EnvironmentFile`, container secrets),
+skip `register` and set `FLOTILLA_MACHINE_TOKEN` + `FLOTILLA_MACHINE_ID`
+directly.
+
+Run `node bin/navarch.cjs doctor` any time to print resolved config, Docker
+availability, and registration status without starting the daemon.
+
+### Connecting an agent to one project
+
+`connect` is the project-scoped sibling of `register` — "Connect an agent to
+a project" (self-hosted-runner style, like a GitHub Actions self-hosted
+runner token): a project **owner** mints a short-lived (60 minute),
+single-use token from the platform UI (the project settings page's "Connect
+an agent" panel, or the onboarding wizard's Agent step),
+`POST /api/projects/:id/enrollment-tokens`, and pastes you the ready-to-run
+command. Unlike `register`, no `FLOTILLA_ENROLLMENT_SECRET` or
+`--owner-zone` is needed — the token is already scoped to exactly one
+project, and the resulting machine's `project_bindings` is set to that
+project only (it will never be dispatched work from any other project).
+
+```sh
+npx @sagentlab/navarch-runtime connect --token flmt_<...> --project <project-id> \
+    --name my-agent-1 --api-base https://flotilla.example.com
+node bin/navarch.cjs start
+```
+
+(`@sagentlab/navarch-runtime` is not yet published to npm — see "What needs
+live verification" below for the from-source equivalent, i.e. the
+`git clone` + `./install.sh` + `node bin/navarch.cjs connect ...` flow
+above.)
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `register --token <t> --name <n> [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]` | Registers this machine (global enrollment secret), prints the token once. |
+| `connect --token <t> --name <n> [--project <id>] [--capabilities a,b] [--max-sessions N] [--api-base url]` | Connects this machine to exactly one project (project-scoped enrollment token), prints the token once. |
+| `start` | Runs the daemon: machine heartbeat loop + claim loop, `FLOTILLA_MAX_SESSIONS` concurrent task sessions. |
+| `doctor` | Prints resolved config + Docker/registration status; no side effects. |
+
+## Configuration (`FLOTILLA_*` env vars)
+
+| Var | Default | Meaning |
+|---|---|---|
+| `FLOTILLA_API_BASE` | `http://localhost:3000` | Control-plane base URL. |
+| `FLOTILLA_MACHINE_TOKEN` / `FLOTILLA_MACHINE_ID` | — | Skip `register`/the config file; twelve-factor auth. |
+| `FLOTILLA_MACHINE_NAME` | — | Used by `register`. |
+| `FLOTILLA_ENROLLMENT_TOKEN` | — | Alternative to `register --token` / `connect --token`. |
+| `FLOTILLA_PROJECT_ID` | — | Alternative to `connect --project`. |
+| `FLOTILLA_CONFIG_DIR` | `~/.flotilla` | Where `machine.json` lives. |
+| `FLOTILLA_WORKSPACE_ROOT` | `<config dir>/sandboxes` | Per-session working directories (host side; mounted into each container). |
+| `FLOTILLA_MAX_SESSIONS` | `3` | Capacity cap — see `src/capacity.cts`. |
+| `FLOTILLA_CAPABILITIES` | `docker-sandbox,shell` | Comma list reported at heartbeat/claim time. |
+| `FLOTILLA_OWNER_ZONE` | `sagentlab` | `sagentlab` or `customer-<slug>-premises` (project-plan.md §3.11). |
+| `FLOTILLA_POLL_INTERVAL_MS` | `5000` | Claim-loop poll interval. |
+| `FLOTILLA_HEARTBEAT_INTERVAL_MS` | `60000` | Machine-level heartbeat interval. |
+| `FLOTILLA_LEASE_HEARTBEAT_INTERVAL_MS` | `300000` | Per-lease heartbeat interval; must stay well under the 15-minute lease TTL (schema-design.md §4). |
+| `FLOTILLA_SESSION_TIMEOUT_MS` | `2700000` (45 min) | Hard kill timeout for a single session. |
+| `FLOTILLA_SANDBOX_MODE` | `docker` | `docker` or `host` (host mode skips the container — dev/debug only, no isolation). |
+| `FLOTILLA_DOCKER_IMAGE` | `node:20-slim` | Image used for the per-session container. |
+| `FLOTILLA_AGENT` | `claude-code` | Which agent CLI runs sessions: `claude-code` or `codex`. Any other value falls back to `claude-code`. Recorded as `agent_type` on the `complete()` call so the sessions row shows which one ran. |
+| `FLOTILLA_CLAUDE_BIN` | `claude` | Path/name of the Claude Code CLI binary. |
+| `FLOTILLA_CLAUDE_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `--mcp-config` (Claude Code). |
+| `FLOTILLA_CODEX_BIN` | `codex` | Path/name of the Codex CLI binary. |
+| `FLOTILLA_CODEX_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `--mcp-config`/`--json` (Codex). |
+| `FLOTILLA_MCP_CONFIG_PATH` | — | Path to the platform MCP config passed as `--mcp-config`. |
+
+## Choosing an agent (Claude Code vs. Codex)
+
+Each machine runs sessions with exactly one agent CLI, set once via
+`FLOTILLA_AGENT`:
+
+```sh
+# Claude Code (default) — requires the `claude` CLI installed and
+# authenticated on this machine (or FLOTILLA_CLAUDE_BIN pointing at it).
+export FLOTILLA_AGENT=claude-code
+
+# OpenAI Codex — requires the `codex` CLI installed and authenticated on
+# this machine (or FLOTILLA_CODEX_BIN pointing at it), analogous to the
+# Claude Code prerequisite above.
+export FLOTILLA_AGENT=codex
+```
+
+Both adapters implement the same `AgentAdapter` interface
+(`src/adapters/types.cts`) and run either directly on the host or via
+`docker exec` in the session's sandbox container, exactly like the Claude
+adapter always has — `session.cts` picks one (`src/adapters/index.cts`'s
+`selectAdapter`) at the start of each session and passes `agent_type`
+through to `complete()` unchanged by whatever happened during the run.
+
+**The Codex CLI invocation (`codex exec "<prompt>" --json [--mcp-config
+<path>]`) is unverified** — there is no `codex` binary available to test
+against in this offline build environment, so every flag and the JSONL
+output shape it's assumed to produce are inferred by analogy with the Claude
+Code adapter's own documented `--output-format json` assumption. See
+`src/adapters/codex.cts`'s module doc comment and
+`src/exit-conditions.cts`'s `parseCodexJsonEvents` doc comment for the full
+list of assumptions to confirm once a real `codex` binary is available, and
+"What needs live verification" below.
+
+## Architecture
+
+```
+cli.cts
+ ├─ register            → api.registerMachine()      → machine-store.cts (writes machine.json once)
+ ├─ connect             → api.connectMachine()       → machine-store.cts (writes machine.json once)
+ └─ start
+     ├─ MachineHeartbeatLoop   (heartbeat-loop.cts)   → api.machineHeartbeat()   [every FLOTILLA_HEARTBEAT_INTERVAL_MS]
+     └─ ClaimLoop              (claim-loop.cts)        → api.claim()             [every FLOTILLA_POLL_INTERVAL_MS, gated by CapacityTracker]
+          └─ runSession (session.cts), one per claimed lease, run concurrently up to FLOTILLA_MAX_SESSIONS:
+               1. write prompt.md (prompt.cts renders the 4-layer context bundle)
+               2. api.issueSecrets()                  → held in memory only
+               3. DockerSandbox.create/injectEnv/cloneRepo (sandbox.cts)
+               4. selectAdapter(config.agentType) (adapters/index.cts) picks one AgentAdapter
+                  (adapters/types.cts) by FLOTILLA_AGENT, then .run(...):
+                    - claudeCodeAdapter (adapters/claude.cts) — `claude -p <prompt> --mcp-config <path>`
+                    - codexAdapter      (adapters/codex.cts)  — `codex exec <prompt> --json --mcp-config <path>` (ASSUMED)
+                  heartbeating the lease every FLOTILLA_LEASE_HEARTBEAT_INTERVAL_MS throughout either;
+                  a failed heartbeat aborts the run (kills the process) and marks the outcome as lease-lost
+               5. mapExitCondition (exit-conditions.cts) → redact.cts scrubs the transcript → upload.cts PUTs it
+               6. api.completeLease(), reporting agent_type: config.agentType
+               7. sandbox.wipe() unconditionally (finally block)
+```
+
+`adapter.cts` (top-level) is now a backward-compat re-export of
+`adapters/claude.cts` — new code should import `adapters/index.cts` (for
+`selectAdapter`) or `adapters/claude.cts` / `adapters/codex.cts` directly.
+
+`api.cts` is the single choke point for every HTTP call; nothing else in the
+package talks to `fetch` directly for control-plane traffic.
+
+## Secret handling
+
+- Task secrets come from `POST /api/broker/issue` **once**, at session start,
+  and are held only in memory (`session.cts`) — never written to the host
+  filesystem.
+- Inside the sandbox, `DockerSandbox.injectEnv()` writes `KEY=value` lines to
+  a **tmpfs-backed** file (`/tmp/session.env`) over `docker exec -i` **stdin**
+  — never a `docker run -e` flag (visible via `docker inspect`) and never a
+  host-side file. The container's `/tmp` and `/run` are tmpfs, so nothing
+  persists past `wipe()`.
+- `cloneRepo()` wires a git credential helper that echoes `$GITHUB_TOKEN` —
+  the literal token value never appears as a literal string in any argv the
+  host's `ps` can see; only the variable *reference* does.
+- Before upload, `redact.cts` scrubs the transcript against every value the
+  session's `SecretRegistry` actually saw, plus pattern-based fallbacks
+  (GitHub PAT shapes, PEM private keys, generic `sk-...` tokens) as
+  defense-in-depth for values the registry didn't see directly.
+
+## Assumptions to confirm (control-plane contracts not yet pinned)
+
+`schema-design.md` §7 enumerates `POST /api/dispatch/claim`, `POST
+/api/dispatch/:leaseId/heartbeat`, `POST /api/dispatch/:leaseId/complete`, and
+`POST /api/broker/issue` — those are implemented in `api.cts` exactly as
+documented. Three routes WP-07 also needs are **not** enumerated there and
+were inferred from the closest analogous shape (each is called out in
+`types.cts` with an "ASSUMED" doc comment and isolated to one method in
+`api.cts`):
+
+1. **`POST /api/machines/register`** — machine self-registration via a
+   short-lived enrollment token (issued out-of-band by an owner/admin). The
+   docs describe the *behavior* ("one command, prints machine token once")
+   but WP-01/WP-04/WP-05 own the actual admin-console/enrollment-token flow.
+2. **`POST /api/machines/:id/heartbeat`** — a machine-level heartbeat
+   distinct from the per-lease heartbeat, needed because `machines.last_heartbeat_at`
+   /`status` must update even when no task is claimed.
+3. **`POST /api/dispatch/:leaseId/transcript-upload-url`** — a signed
+   Supabase Storage upload URL, per `sessions.transcript_url`'s "object
+   storage, not in DB" note and WP-07's "transcript → Supabase Storage via a
+   control-plane upload URL" line.
+
+Reconciling any of these against the real routes, once WP-01/WP-04/WP-05
+land, means editing the corresponding method in `api.cts` — no other file
+should need to change.
+
+`POST /api/machines/connect` (`api.cts#connectMachine`, the `connect`
+command) is **not** in this ASSUMED list — it was built in the same change
+as `app/api/machines/connect/route.ts`, so the shapes in `types.cts`
+(`ConnectMachineRequest`/`ConnectMachineResult`) are confirmed against the
+real route, not inferred.
+
+## What needs live verification
+
+This was built and tested offline (no Docker daemon, no `claude` or `codex`
+binary, no live control-plane API in this environment). Unit tests cover
+everything that can be verified without those:
+
+- `api.cts` — request/response shapes, error mapping, auth header handling (`tests/api.test.cts`).
+- `exit-conditions.cts` — every exit-condition → complete/fail mapping, priority order,
+  plus Claude's and Codex's usage/report parsing (`tests/exit-conditions.test.cts`).
+- `redact.cts` — exact-value and pattern-based redaction (`tests/redact.test.cts`).
+- `capacity.cts` — capacity math and acquire/release bookkeeping (`tests/capacity.test.cts`).
+- `config.cts` — env var parsing and defaults, including `FLOTILLA_AGENT`/
+  `FLOTILLA_CODEX_BIN`/`FLOTILLA_CODEX_EXTRA_ARGS` (`tests/config.test.cts`).
+- `sandbox.cts` — command construction (flags, env-via-stdin, credential-helper
+  argv hygiene) against an injected fake `CommandRunner`, plus `isDockerAvailable()`
+  degrading to `false` instead of throwing when Docker is absent (`tests/sandbox.test.cts`).
+- `adapters/index.cts#selectAdapter` — picks the right `AgentAdapter` for every
+  `FLOTILLA_AGENT` value, including the claude-code fallback for an unrecognized
+  one (`tests/adapters/index.test.cts`).
+- `adapters/codex.cts` — arg construction on both the host path (mocked `spawn`)
+  and the docker-exec path (fake `CommandRunner`), and usage/report-text
+  attachment from fixed JSONL fixtures (`tests/adapters/codex.test.cts`).
+
+Not exercised by unit tests, and needing a real machine per the WP-07 DoD
+("on a real machine: register → claim a seeded docs task → session runs
+Claude Code headless → PR opens on GitHub → complete lands with evidence;
+secrets absent from disk after exit"):
+
+- Actually running `claude -p` headless and confirming its real
+  `--output-format json` shape (WP-13). `adapters/claude.cts` now appends
+  `--output-format json` by default and best-effort parses stdout as a single
+  JSON result object shaped like `{ type, subtype, is_error, result,
+  session_id, total_cost_usd, usage: { input_tokens, output_tokens,
+  cache_creation_input_tokens, cache_read_input_tokens } }` (see
+  `exit-conditions.cts#parseClaudeJsonResult` for the exact assumption and
+  fallback behavior). Unit tests (`tests/adapter.test.cts`,
+  `tests/exit-conditions.test.cts`) cover the parsing and arg-construction
+  logic against fixed JSON strings; what's untested offline is whether a real
+  `claude -p --output-format json` invocation actually produces this shape.
+  If it doesn't, parsing degrades to `null` and `tokensIn`/`tokensOut`/
+  `costUsd` fall back to 0 (session.cts's existing default) — never a thrown
+  error — but cost/spend data silently goes missing until the shape is
+  reconciled here.
+- **Everything about the Codex CLI adapter (`adapters/codex.cts`) — there is
+  no `codex` binary to test against here at all, unlike Claude Code where at
+  least the flag name and general headless-JSON shape are documented.** Every
+  one of the following is an unverified guess, each flagged "ASSUMED — CONFIRM
+  AGAINST A REAL codex BINARY" at its point of use:
+  - That `codex exec "<prompt>"` is the right non-interactive/headless
+    invocation at all (the `claude -p` analog).
+  - That `--json` is a real flag and that it switches output to
+    newline-delimited JSON "event" objects (`{"id": "...", "msg": {"type":
+    ..., ...}}`) rather than, say, a single JSON object like Claude's
+    `--output-format json`, or no structured-output flag at all.
+  - That the event `msg.type` values used here (`agent_message`,
+    `token_count`, `task_complete`) exist, are spelled this way, and that
+    `token_count` events carry cumulative (not incremental/per-turn) totals —
+    `exit-conditions.cts#extractUsageFromCodexEvents` takes the *last* such
+    event's numbers, which double-counts or under-counts if that guess is
+    wrong.
+  - That `--mcp-config <path>` is accepted at all by `codex exec` — Codex CLI
+    documentation elsewhere describes MCP servers configured via
+    `~/.codex/config.toml`, not a per-invocation flag, so this may need to
+    become "write a config fragment into the sandbox first" instead.
+  - Whether a real `codex exec` run needs an explicit non-interactive/
+    approval-bypass flag (e.g. something like `--full-auto` or
+    `--dangerously-bypass-approvals-and-sandbox` per published Codex CLI
+    docs) to avoid blocking on an approval prompt inside the already-isolated
+    Docker sandbox — deliberately **not** hardcoded, left to
+    `FLOTILLA_CODEX_EXTRA_ARGS` until confirmed, since guessing the wrong
+    flag here could silently disable sandboxing rather than just fail loudly.
+  - Whether the Codex CLI even authenticates/runs non-interactively the same
+    way `claude` does (API key vs. ChatGPT-account OAuth device flow) — this
+    adapter assumes "already authenticated on the machine" exactly like the
+    Claude Code prerequisite, but cannot confirm that story is equivalent.
+
+  If any of this is wrong, `parseCodexJsonEvents` returns an empty array and
+  the adapter's `attachUsage()` leaves `tokensIn`/`tokensOut`/`costUsd`/
+  `reportText` unset — `mapExitCondition` then falls back to raw stdout for
+  the report — same never-throw degradation as the Claude path, just with
+  more to reconcile once a real binary exists.
+- The full Docker sandbox lifecycle against a real Docker daemon (rootless
+  behavior, tmpfs env injection, git clone with a real PAT, `docker exec`
+  timeout/kill semantics under `AbortSignal`).
+- The three assumed endpoints above, once they exist.
+- Lease-loss handling against a real dispatcher (heartbeat 404/409 on an
+  already-reassigned lease) — `session.cts` aborts the running adapter
+  process and still attempts a best-effort `complete()` call, which the
+  real server may reject; that path is untested against real semantics.
+- Transcript upload against a real signed Supabase Storage URL.
+- The end-to-end "Connect an agent to a project" flow against a real
+  Supabase instance: an owner minting a token from `ConnectAgentPanel`
+  (or the onboarding wizard's Agent step), `navarch-runtime connect`
+  redeeming it, and the resulting machine actually claiming a task scoped to
+  that one project. Unit-tested here: `connectMachine()`'s request shape
+  (`tests/api.test.cts`) and the `connect` command's flag/env parsing
+  (`tests/cli.test.cts`); not tested here: the real Postgres round trip
+  (`lib/flotilla/__tests__/enrollment.test.ts` and the
+  `app/api/machines/connect` / `app/api/projects/[id]/enrollment-tokens`
+  route tests cover that with a mocked admin client, not a live database).
+- `@sagentlab/navarch-runtime` is not yet published to npm — every `npx
+  @sagentlab/navarch-runtime ...` command shown above (and in
+  `ConnectAgentPanel`) currently requires the from-source flow instead
+  (`git clone` + `./install.sh` + `node bin/navarch.cjs connect ...`).
+
+## A note on `.cts` instead of `.ts`
+
+Every source and test file in this package uses the `.cts` extension rather
+than `.ts`. This isn't a style preference: the repo root's `tsconfig.json`
+globs `**/*.ts` / `**/*.mts` into the Next.js app's own `next build`
+type-check, and that check runs across the whole matched file set, not just
+files reachable from a page — confirmed empirically while building this
+package (a single stray `.ts` file under `runtime/` failed the root
+`next build`). WP-07's file ownership is scoped to `runtime/` only, so
+editing the root `tsconfig.json`'s `include`/`exclude` was out of bounds.
+`.cts` is a first-class TypeScript/Node extension (forces CommonJS output,
+still allows normal `import`/`export` source syntax) that the root glob does
+not match, making it a clean, zero-touch way to keep this package fully
+isolated. Vite/Vitest's default esbuild transform filter also excludes
+`.cts` by default — `vitest.config.cts` overrides it (`esbuild.include`) so
+tests are actually type-stripped and run.
+
+## Discovered scope (flagging, not editing the plan doc)
+
+- Machine registration, machine-level heartbeat, and the transcript
+  upload-URL endpoint are not in `schema-design.md` §7's API surface list —
+  see "Assumptions to confirm" above. Recommend WP-01/WP-04/WP-05 add these
+  three routes explicitly to the schema doc once designed.
+- No admin-console UI exists yet to actually mint an `enrollment_token` for
+  `register` to redeem — that's WP-08 (Fleet view) / WP-01 (admin console)
+  territory; this package assumes it will exist.

package/bin/navarch.cjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+"use strict";
+
+// Thin npx-able entry point. The real CLI lives in src/cli.cts, compiled to
+// dist/cli.cjs by `npm run build`. Kept deliberately tiny (no logic) so there
+// is nothing here to type-check or unit-test beyond "does it call main()".
+require("../dist/cli.cjs")
+  .main()
+  .catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+  });

package/dist/adapter.cjs

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeAdapter = exports.runClaudeCodeAdapter = void 0;
+/**
+ * Backward-compat re-export shim.
+ *
+ * The Claude Code adapter that used to live entirely in this file now lives
+ * in adapters/claude.cts, implementing the generalized `AgentAdapter`
+ * interface (adapters/types.cts) alongside adapters/codex.cts's Codex CLI
+ * sibling — session.cts picks between the two via FLOTILLA_AGENT
+ * (config.cts's `agentType`) through adapters/index.cts#selectAdapter.
+ *
+ * This file is kept, unchanged in its exported names, so any existing
+ * `import { runClaudeCodeAdapter } from "./adapter.cjs"` (or
+ * `import type { RunClaudeCodeOptions } from "./adapter.cjs"`) continues to
+ * resolve without a call-site change. New code should import from
+ * "./adapters/claude.cjs" (or "./adapters/index.cjs" for the
+ * agent-agnostic selection helper) directly instead.
+ */
+var claude_cjs_1 = require("./adapters/claude.cjs");
+Object.defineProperty(exports, "runClaudeCodeAdapter", { enumerable: true, get: function () { return claude_cjs_1.runClaudeCodeAdapter; } });
+Object.defineProperty(exports, "claudeCodeAdapter", { enumerable: true, get: function () { return claude_cjs_1.claudeCodeAdapter; } });

package/dist/adapters/claude.cjs

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeAdapter = void 0;
+exports.runClaudeCodeAdapter = runClaudeCodeAdapter;
+const node_child_process_1 = require("node:child_process");
+const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
+/**
+ * Headless Claude Code adapter (project-plan.md §3.9 / implementation-plan.md
+ * WP-07): `claude -p "<context bundle>" --mcp-config platform-mcp.json
+ * --output-format json`. Returns raw stdout/stderr/exit signals (plus
+ * best-effort tokensIn/tokensOut/costUsd parsed from the JSON result -- see
+ * exit-conditions.cts#parseClaudeJsonResult) for exit-conditions.cts to map
+ * onto a complete()/fail() call.
+ *
+ * This is one of two implementations of the AgentAdapter interface
+ * (adapters/types.cts) — see adapters/codex.cts for the Codex CLI sibling
+ * session.cts picks between via FLOTILLA_AGENT (config.cts's `agentType`).
+ *
+ * NEEDS LIVE VERIFICATION (WP-13): `--output-format json` is assumed to make
+ * `claude -p` print a single JSON result object with a `usage` block, per
+ * Claude Code's documented headless-mode output. This cannot be confirmed
+ * without a real `claude` binary in this offline build environment. If the
+ * real shape differs, parseClaudeJsonResult() returns null and
+ * tokensIn/tokensOut/costUsd fall back to 0 (session.cts's existing
+ * default) rather than throwing -- see runtime/README.md.
+ */
+async function runClaudeCodeAdapter(options) {
+    const args = ["-p", options.prompt];
+    if (options.mcpConfigPath) {
+        args.push("--mcp-config", options.mcpConfigPath);
+    }
+    // Only append the default when the caller hasn't already asked for a
+    // specific --output-format (extraArgs wins so an operator can opt back
+    // into plain-text output, e.g. while diagnosing a live-verification
+    // mismatch, without an adapter code change).
+    if (!options.extraArgs.includes("--output-format")) {
+        args.push("--output-format", "json");
+    }
+    args.push(...options.extraArgs);
+    const raw = options.dockerExec ? await runViaDocker(options, args) : await runOnHost(options, args);
+    return attachUsage(raw);
+}
+/** Parses stdout for `claude -p --output-format json` usage and folds it onto the raw result (best-effort; leaves tokensIn/tokensOut/costUsd unset when parsing fails). */
+function attachUsage(result) {
+    const parsed = (0, exit_conditions_cjs_1.parseClaudeJsonResult)(result.stdout);
+    if (!parsed)
+        return result;
+    const usage = (0, exit_conditions_cjs_1.extractUsageFromClaudeJson)(parsed);
+    return { ...result, tokensIn: usage.tokensIn, tokensOut: usage.tokensOut, costUsd: usage.costUsd };
+}
+async function runOnHost(options, args) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let killedByLeaseLoss = false;
+        const child = (0, node_child_process_1.spawn)(options.bin, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, options.timeoutMs);
+        const onAbort = () => {
+            killedByLeaseLoss = true;
+            child.kill("SIGKILL");
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout.on("data", (d) => {
+            stdout += d.toString();
+        });
+        child.stderr.on("data", (d) => {
+            stderr += d.toString();
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            stderr += `\n${String(err)}`;
+            resolve({ exitCode: null, timedOut, killedByLeaseLoss, stdout, stderr });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            resolve({ exitCode: code, timedOut, killedByLeaseLoss, stdout, stderr });
+        });
+    });
+}
+async function runViaDocker(options, args) {
+    const { containerName, runner } = options.dockerExec;
+    const quoted = [options.bin, ...args].map(shellQuote).join(" ");
+    const command = `[ -f /tmp/session.env ] && . /tmp/session.env; cd repo 2>/dev/null; ${quoted}`;
+    let killedByLeaseLoss = false;
+    const onAbort = () => {
+        killedByLeaseLoss = true;
+        // Best-effort: kill the exec'd process inside the container. The runner
+        // call below still resolves once `docker exec` itself is torn down by
+        // its own timeout/kill; a true "kill this docker exec now" requires
+        // process-group tracking that nodeCommandRunner does not yet expose.
+        runner.run("docker", ["kill", containerName]).catch(() => undefined);
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const result = await runner.run("docker", ["exec", containerName, "sh", "-c", command], {
+            timeoutMs: options.timeoutMs,
+        });
+        return {
+            exitCode: result.code,
+            timedOut: false,
+            killedByLeaseLoss,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    }
+    catch (err) {
+        return {
+            exitCode: null,
+            timedOut: false,
+            killedByLeaseLoss,
+            stdout: "",
+            stderr: String(err),
+        };
+    }
+    finally {
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** The AgentAdapter (adapters/types.cts) wrapper session.cts selects via FLOTILLA_AGENT=claude-code (the default). */
+exports.claudeCodeAdapter = {
+    agentType: "claude-code",
+    run: runClaudeCodeAdapter,
+};