@sagentlab/navarch-runtime 0.1.1 → 0.1.3

package/README.md

@@ -7,7 +7,8 @@ it. Plain Node/TypeScript, zero production dependencies, no Next.js coupling
 machine.
 
 The agent CLI a session runs is either **Claude Code** or **OpenAI Codex**,
-selected per machine via `NAVARCH_AGENT` (default `claude-code`) — see
+selected by the local machine via `--agent` or `NAVARCH_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)
@@ -20,7 +21,7 @@ the API contract.
 
 ```sh
 git clone <this repo> && cd sagentlab/runtime
-./install.sh          # checks node/docker, npm install, npm run build
+./install.sh          # checks node, npm install, npm run build
 export NAVARCH_API_BASE=https://navarch.example.com
 node bin/navarch.cjs register --token <enrollment-token> --name my-machine-1
 node bin/navarch.cjs start
@@ -48,8 +49,8 @@ availability, and registration status without starting the daemon.
 
 `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
+runner token): a project **owner** mints a 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 `NAVARCH_ENROLLMENT_SECRET` or
@@ -59,7 +60,7 @@ 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://navarch.example.com
+    --name my-agent-1 --agent codex --api-base https://navarch.example.com
 node bin/navarch.cjs start
 ```
 
@@ -72,11 +73,70 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 
 | 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, `NAVARCH_MAX_SESSIONS` concurrent task sessions. |
+| `register --token <t> --name <n> [--agent claude-code\|codex] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
+| `connect --token <t> --name <n> [--agent claude-code\|codex] [--project <id>] […]` | Connects this machine to one project, saves its local agent choice, and prints the token once. |
+| `start [--agent claude-code\|codex]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
 | `doctor` | Prints resolved config + Docker/registration status; no side effects. |
 
+## Active-task guidance
+
+Guidance added to a task that is already running is delivered on that
+task's next lease heartbeat (every
+`NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS`, five minutes by default). The runtime
+stops the current agent process and starts a **new agent turn** with the
+original task context plus all guidance received so far. This is a turn
+restart, not a new dispatch:
+
+- The task keeps the same session and lease, and lease heartbeats continue.
+- The replacement turn uses the same worktree (and the same sandbox container
+  in Docker mode), so committed and uncommitted changes from the interrupted
+  turn remain available. It should inspect those changes before continuing.
+- The replacement turn is not a resumed Claude Code or Codex conversation.
+  The corrected prompt carries the prior task context and guidance instead.
+- Transcript, token, and cost accounting is cumulative across turns: the
+  upload includes every turn under a separate label, and reported token and
+  cost totals include every turn. The lease is completed only after the
+  corrected turn finishes.
+
+The daemon logs `restarting the agent turn in the same worktree` when it
+delivers guidance. Lowering the lease-heartbeat interval makes guidance arrive
+sooner, but keep it comfortably below the 15-minute lease TTL.
+
+## Safely upgrading and restarting the daemon
+
+The daemon does not currently drain sessions during shutdown: `SIGINT` or
+`SIGTERM` stops new claims and heartbeats, then exits immediately. Stopping it
+with an active session can interrupt the agent before it reports completion;
+the control plane must then wait for the lease to expire and requeue the task.
+Do not use an ordinary daemon restart as a way to deliver guidance.
+
+Use this sequence for an upgrade:
+
+1. Install or build the new runtime without stopping the existing process. For
+   a source checkout, update the checkout and run `npm ci && npm run build`
+   inside `runtime/`. For an npm deployment, select the exact version in the
+   service command, for example
+   `npx --yes @sagentlab/navarch-runtime@<version> start`.
+2. In Navarch's **Fleet** view, wait until this machine shows `Sessions: 0/N`.
+   Check the daemon log once more for a newer `claimed task` message before
+   proceeding. If it claimed another task, let that session finish too.
+3. Stop the old process through its service manager, or send `SIGTERM`/press
+   Ctrl-C. Do not use `SIGKILL` (`kill -9`). Ensure the old process has exited
+   before starting its replacement so two claim loops never run for one
+   machine identity.
+4. Run `doctor` using the same service environment and
+   `NAVARCH_CONFIG_DIR`, then start the new version with that same environment.
+   Do **not** run `register` or `connect` again: the existing `machine.json`
+   contains the machine identity and token needed after the upgrade. Never
+   print, log, or copy the contents of `machine.json` or its token into upgrade
+   commands or diagnostics.
+5. Confirm the startup log reports the expected machine, agent, and API base,
+   then verify that Fleet shows the machine online with a fresh heartbeat.
+
+For a supervised service, make the stop timeout long enough for step 3 to
+observe a normal exit, and keep the service's environment file/config directory
+unchanged across the deployment.
+
 ## Configuration (`NAVARCH_*` env vars)
 
 | Var | Default | Meaning |
@@ -87,27 +147,29 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 | `NAVARCH_ENROLLMENT_TOKEN` | — | Alternative to `register --token` / `connect --token`. |
 | `NAVARCH_PROJECT_ID` | — | Alternative to `connect --project`. |
 | `NAVARCH_CONFIG_DIR` | `~/.navarch` | Where `machine.json` lives. |
-| `NAVARCH_WORKSPACE_ROOT` | `<config dir>/sandboxes` | Per-session working directories (host side; mounted into each container). |
-| `NAVARCH_MAX_SESSIONS` | `3` | Capacity cap — see `src/capacity.cts`. |
-| `NAVARCH_CAPABILITIES` | `docker-sandbox,shell` | Comma list reported at heartbeat/claim time. |
+| `NAVARCH_WORKSPACE_ROOT` | `<config dir>/sandboxes` | Persistent bare repo caches plus isolated per-session worktrees. |
+| `NAVARCH_MAX_SESSIONS` | `5` | Local concurrent-session capacity cap — see `src/capacity.cts`. |
+| `NAVARCH_CAPABILITIES` | `shell` (`docker-sandbox,shell` in Docker mode) | Comma list reported at heartbeat/claim time. |
 | `NAVARCH_OWNER_ZONE` | `sagentlab` | `sagentlab` or `customer-<slug>-premises` (project-plan.md §3.11). |
 | `NAVARCH_POLL_INTERVAL_MS` | `5000` | Claim-loop poll interval. |
 | `NAVARCH_HEARTBEAT_INTERVAL_MS` | `60000` | Machine-level heartbeat interval. |
 | `NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS` | `300000` | Per-lease heartbeat interval; must stay well under the 15-minute lease TTL (schema-design.md §4). |
 | `NAVARCH_SESSION_TIMEOUT_MS` | `2700000` (45 min) | Hard kill timeout for a single session. |
-| `NAVARCH_SANDBOX_MODE` | `docker` | `docker` or `host` (host mode skips the container — dev/debug only, no isolation). |
+| `NAVARCH_SANDBOX_MODE` | `host` | `host` uses the resources already available to the agent process. Set `docker` explicitly for container isolation. |
 | `NAVARCH_DOCKER_IMAGE` | `node:20-slim` | Image used for the per-session container. |
-| `NAVARCH_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. |
+| `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent CLI: `claude-code` or `codex`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
 | `NAVARCH_CLAUDE_BIN` | `claude` | Path/name of the Claude Code CLI binary. |
 | `NAVARCH_CLAUDE_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `--mcp-config` (Claude Code). |
 | `NAVARCH_CODEX_BIN` | `codex` | Path/name of the Codex CLI binary. |
-| `NAVARCH_CODEX_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `--mcp-config`/`--json` (Codex). |
+| `NAVARCH_CODEX_EXTRA_ARGS` | — | Comma list of extra CLI args appended after the generated MCP `-c` overrides and `--json` (Codex). |
 | `NAVARCH_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
-`NAVARCH_AGENT`:
+Each machine chooses its own agent CLI. Pass `--agent` while connecting to
+persist the choice in local `machine.json`, override it for one daemon start
+with `start --agent`, or set `NAVARCH_AGENT` in the machine's service
+environment:
 
 ```sh
 # Claude Code (default) — requires the `claude` CLI installed and
@@ -120,6 +182,9 @@ export NAVARCH_AGENT=claude-code
 export NAVARCH_AGENT=codex
 ```
 
+Priority is `start --agent` → `NAVARCH_AGENT` → the locally saved choice →
+`claude-code`. The control plane does not choose the adapter.
+
 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
@@ -127,15 +192,20 @@ 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.
+The control plane also resolves the project's model and the task's execution
+profile on every claim. The runtime passes those values as per-session CLI
+overrides (`codex exec --model ... -c model_reasoning_effort=...` or
+`claude -p --model ... --effort ...`) and records the effective model, profile,
+and effort on completion. Machine-wide extra arguments still configure other
+CLI behavior; project/task policy wins for model and effort.
+
+The Codex CLI invocation was verified against `codex-cli 0.144.1` on
+2026-07-18. The runtime uses `codex exec "<prompt>" --json` and translates
+the existing per-session MCP JSON into one-off `-c mcp_servers.*` overrides.
+Machine and lease credentials are referenced through environment variables,
+not placed in argv. The JSONL parser accepts the verified top-level
+`item.completed` / `turn.completed` shape and retains the older `msg`
+envelope as a compatibility fallback.
 
 ## Architecture
 
@@ -149,16 +219,19 @@ cli.cts
           └─ runSession (session.cts), one per claimed lease, run concurrently up to NAVARCH_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)
+               3. fetch the project's bare repository cache and create a
+                  unique git worktree for this session; optionally mount it
+                  into Docker when NAVARCH_SANDBOX_MODE=docker
                4. selectAdapter(config.agentType) (adapters/index.cts) picks one AgentAdapter
                   (adapters/types.cts) by NAVARCH_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)
+                    - codexAdapter      (adapters/codex.cts)  — `codex exec <prompt> --json -c mcp_servers.*=...`
                   heartbeating the lease every NAVARCH_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)
+               7. sandbox.wipe() when present; remove the session workspace
+                  unconditionally (finally block)
 ```
 
 `adapter.cts` (top-level) is now a backward-compat re-export of
@@ -186,43 +259,28 @@ package talks to `fetch` directly for control-plane traffic.
   (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)
+## Control-plane contracts
 
-`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`):
+`schema-design.md` §7 and the matching control-plane routes define every HTTP
+contract used by `api.cts`, including:
 
-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.
+1. **`POST /api/machines/register`** — global machine registration via the
+   operator-configured enrollment secret.
 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.
+   Supabase Storage upload URL for the session's redacted transcript.
 
-`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.
+`POST /api/machines/connect` is the project-scoped alternative: it redeems a
+single-use token minted by an owner through the onboarding or Fleet UI.
 
 ## 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:
+Most runtime behavior is covered offline. The Codex host adapter was also
+probed against a real authenticated `codex-cli 0.144.1`; Docker and the full
+production control-plane lifecycle still require live verification. Unit
+tests cover:
 
 - `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,
@@ -261,48 +319,19 @@ secrets absent from disk after exit"):
   `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
-    `NAVARCH_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.
+- A full Codex task that initializes the production MCP server, edits a
+  worktree, pushes a branch, opens a PR, and completes its lease. The CLI
+  flags, per-run MCP override keys, stdin behavior, and JSONL event/usage
+  shape are now verified locally; the next dogfood run covers their
+  production composition.
+- Whether Docker-mode Codex should opt into
+  `--dangerously-bypass-approvals-and-sandbox`. It is intentionally not a
+  default: host mode is not an external sandbox, and silently disabling
+  Codex's protections there would be unsafe. Operators can still add the
+  flag explicitly through `NAVARCH_CODEX_EXTRA_ARGS` on an isolated machine.
 - 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
@@ -340,13 +369,3 @@ 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/dist/adapters/claude.cjs

@@ -37,7 +37,19 @@ async function runClaudeCodeAdapter(options) {
         args.push("--output-format", "json");
     }
     args.push(...options.extraArgs);
-    const raw = options.dockerExec ? await runViaDocker(options, args) : await runOnHost(options, args);
+    // Project/task policy is appended after machine-wide extra arguments so a
+    // dispatched session consistently uses the settings recorded by Navarch.
+    if (options.model)
+        args.push("--model", options.model);
+    if (options.reasoningEffort)
+        args.push("--effort", options.reasoningEffort);
+    const runOptions = options.reasoningEffort
+        ? {
+            ...options,
+            env: { ...options.env, CLAUDE_CODE_EFFORT_LEVEL: options.reasoningEffort },
+        }
+        : options;
+    const raw = runOptions.dockerExec ? await runViaDocker(runOptions, args) : await runOnHost(runOptions, 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). */

package/dist/adapters/codex.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.codexAdapter = void 0;
 exports.runCodexAdapter = runCodexAdapter;
 const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
 const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
 /**
  * Headless OpenAI Codex CLI adapter — the Codex sibling of claude.cts's
@@ -13,31 +14,21 @@ const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
  * timeout/AbortSignal handling, same "attach best-effort usage onto the raw
  * result" shape — only the CLI invocation and output parsing differ.
  *
- * ASSUMED — EVERYTHING BELOW ABOUT THE REAL `codex` BINARY MUST BE CONFIRMED
- * AGAINST A REAL INSTALL. There is no `codex` binary available in this
- * offline build environment, so (mirroring how claude.cts documents its own
- * `claude -p --output-format json` assumption) this adapter is a best-effort
- * implementation against the Codex CLI's publicly documented shape, not a
- * verified one:
+ * Verified against codex-cli 0.144.1 on 2026-07-18:
  *
- *   codex exec "<prompt>" --json [--mcp-config <path>] [...extraArgs]
+ *   codex exec "<prompt>" --json [-c mcp_servers.<name>.<key>=<value>] [...extraArgs]
  *
  * - `exec <prompt>` — ASSUMED to be Codex CLI's non-interactive/headless
  *   subcommand (the `codex exec` "automation mode" analog of `claude -p`):
  *   runs the prompt to completion without the interactive TUI and exits,
  *   printing its result to stdout.
- * - `--json` — ASSUMED to switch Codex CLI's output to newline-delimited
- *   JSON ("JSONL") event objects rather than a single JSON result object
- *   like Claude Code's `--output-format json`. See exit-conditions.cts's
- *   parseCodexJsonEvents doc comment for the exact assumed event shape and
- *   what happens when this guess is wrong (graceful degradation, never a
- *   thrown error).
- * - `--mcp-config <path>` — ASSUMED by analogy with the Claude adapter; there
- *   is no confirmed Codex CLI flag of this name. Codex CLI is documented
- *   elsewhere to configure MCP servers via a `~/.codex/config.toml`
- *   `mcp_servers` table rather than a per-invocation flag, so this flag may
- *   need to become "write a config.toml fragment into the sandbox before
- *   exec" instead once a real binary is available to test against.
+ * - `--json` emits top-level `thread.started`, `turn.started`,
+ *   `item.completed`, and `turn.completed` JSONL events. See
+ *   exit-conditions.cts for the tolerant parser.
+ * - Codex has no `--mcp-config` flag. The runtime's existing Claude-shaped
+ *   per-session JSON is translated into one-off `-c mcp_servers.*` overrides.
+ *   Authentication and custom-header values are passed through environment
+ *   variables so machine/lease credentials never appear in argv.
  * - Sandboxing/approvals: a real `codex exec` may prompt for
  *   approval/sandbox-escalation on some actions by default; because this
  *   runtime already isolates the session in its own Docker container (or,
@@ -55,17 +46,65 @@ const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
  */
 async function runCodexAdapter(options) {
     const args = ["exec", options.prompt];
-    if (options.mcpConfigPath) {
-        // ASSUMED flag/support — see module doc comment above.
-        args.push("--mcp-config", options.mcpConfigPath);
-    }
+    const env = { ...options.env };
+    if (options.mcpConfigPath)
+        args.push(...(await codexMcpArgs(options.mcpConfigPath, env)));
     if (!options.extraArgs.includes("--json")) {
         args.push("--json");
     }
     args.push(...options.extraArgs);
-    const raw = options.dockerExec ? await runViaDocker(options, args) : await runOnHost(options, args);
+    if (options.model)
+        args.push("--model", options.model);
+    if (options.reasoningEffort) {
+        args.push("-c", `model_reasoning_effort=${tomlString(options.reasoningEffort)}`);
+    }
+    const runOptions = { ...options, env };
+    const raw = runOptions.dockerExec
+        ? await runViaDocker(runOptions, args)
+        : await runOnHost(runOptions, args);
     return attachUsage(raw);
 }
+/** Convert Claude's per-session MCP JSON into Codex one-off TOML overrides. */
+async function codexMcpArgs(path, env) {
+    const parsed = JSON.parse(await node_fs_1.promises.readFile(path, "utf8"));
+    const args = [];
+    for (const [name, server] of Object.entries(parsed.mcpServers ?? {})) {
+        if (!server.url)
+            continue;
+        const key = tomlKey(name);
+        args.push("-c", `mcp_servers.${key}.url=${tomlString(server.url)}`);
+        args.push("-c", `mcp_servers.${key}.required=true`);
+        const envHeaders = {};
+        let headerIndex = 0;
+        for (const [header, value] of Object.entries(server.headers ?? {})) {
+            const envName = `NAVARCH_CODEX_MCP_${safeEnvSegment(name)}_${headerIndex++}`;
+            if (header.toLowerCase() === "authorization" && value.startsWith("Bearer ")) {
+                env[envName] = value.slice("Bearer ".length);
+                args.push("-c", `mcp_servers.${key}.bearer_token_env_var=${tomlString(envName)}`);
+            }
+            else {
+                env[envName] = value;
+                envHeaders[header] = envName;
+            }
+        }
+        if (Object.keys(envHeaders).length > 0) {
+            const table = Object.entries(envHeaders)
+                .map(([header, envName]) => `${tomlString(header)}=${tomlString(envName)}`)
+                .join(",");
+            args.push("-c", `mcp_servers.${key}.env_http_headers={${table}}`);
+        }
+    }
+    return args;
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function tomlKey(value) {
+    return /^[A-Za-z0-9_-]+$/.test(value) ? value : tomlString(value);
+}
+function safeEnvSegment(value) {
+    return value.toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+}
 /** Parses stdout for `codex exec --json` usage/final-message events and folds them onto the raw result (best-effort; leaves tokensIn/tokensOut/costUsd/reportText unset when nothing parses — see exit-conditions.cts#parseCodexJsonEvents). */
 function attachUsage(result) {
     const events = (0, exit_conditions_cjs_1.parseCodexJsonEvents)(result.stdout);
@@ -91,6 +130,10 @@ async function runOnHost(options, args) {
             cwd: options.cwd,
             env: { ...process.env, ...options.env },
         });
+        // `codex exec` appends piped stdin to the prompt. The spawned process gets
+        // a pipe by default, so close it immediately or it can wait forever for
+        // input even though the full prompt was supplied as an argument.
+        child.stdin?.end();
         const timer = setTimeout(() => {
             timedOut = true;
             child.kill("SIGKILL");
@@ -133,8 +176,13 @@ async function runViaDocker(options, args) {
     };
     options.signal?.addEventListener("abort", onAbort, { once: true });
     try {
-        const result = await runner.run("docker", ["exec", containerName, "sh", "-c", command], {
+        // Forward values through the docker CLI process environment and put only
+        // variable names in argv. This keeps generated MCP bearer/header values
+        // out of `ps` while making the host and Docker paths equivalent.
+        const forwardedEnv = Object.keys(options.env).flatMap((name) => ["--env", name]);
+        const result = await runner.run("docker", ["exec", ...forwardedEnv, containerName, "sh", "-c", command], {
             timeoutMs: options.timeoutMs,
+            env: { ...process.env, ...options.env },
         });
         return {
             exitCode: result.code,

package/dist/api.cjs

@@ -15,13 +15,8 @@ exports.NavarchApiError = NavarchApiError;
 /**
  * Typed client for the Navarch control-plane API surface WP-07 depends on:
  * dispatch/claim, per-lease heartbeat, complete, and broker/issue
- * (schema-design.md §7, quoted verbatim in the method docs below), plus the
- * machine-registration / machine-heartbeat / transcript-upload-url routes
- * this package assumes (see types.cts doc comments — flagged "ASSUMED").
- *
- * Every request path lives in exactly one method here so wiring up the real
- * deployment, once WP-01/WP-04/WP-05 land, is a base URL + token (and at most
- * a one-line path fix for the assumed routes) — not a rewrite.
+ * (schema-design.md §7), plus machine registration, machine heartbeat, and
+ * transcript upload. Every request path lives in exactly one method here.
  */
 class NavarchApiClient {
     baseUrl;
@@ -65,7 +60,7 @@ class NavarchApiClient {
             return null;
         return parsed;
     }
-    /** ASSUMED endpoint — see types.cts RegisterMachineRequest doc comment. */
+    /** Global machine registration using the operator-configured enrollment secret. */
     async registerMachine(req) {
         const result = await this.request("POST", "/api/machines/register", req, { auth: false });
         if (!result)
@@ -87,7 +82,7 @@ class NavarchApiClient {
             throw new Error("connectMachine: empty response from control plane.");
         return result;
     }
-    /** ASSUMED endpoint — see types.cts MachineHeartbeatRequest doc comment. */
+    /** Machine-level capacity heartbeat, independent of lease heartbeats. */
     async machineHeartbeat(machineId, req) {
         const result = await this.request("POST", `/api/machines/${encodeURIComponent(machineId)}/heartbeat`, req);
         if (!result)
@@ -102,8 +97,8 @@ class NavarchApiClient {
         return result;
     }
     /** schema-design.md §7 — `POST /api/dispatch/:leaseId/heartbeat`. */
-    async heartbeatLease(leaseId) {
-        const result = await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/heartbeat`, {});
+    async heartbeatLease(leaseId, req = {}) {
+        const result = await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/heartbeat`, req);
         if (!result)
             throw new Error("heartbeatLease: empty response from control plane.");
         return result;
@@ -121,7 +116,7 @@ class NavarchApiClient {
             throw new Error("issueSecrets: empty response from control plane.");
         return result;
     }
-    /** ASSUMED endpoint — see types.cts TranscriptUploadUrlResult doc comment. */
+    /** Create a signed upload target for this lease's redacted transcript. */
     async getTranscriptUploadUrl(leaseId) {
         const result = await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/transcript-upload-url`, {});
         if (!result)

package/dist/claim-loop.cjs

@@ -19,6 +19,7 @@ class ClaimLoop {
     runSession;
     timer = null;
     stopped = false;
+    claimInFlight = false;
     constructor(api, config, capacity, runSession) {
         this.api = api;
         this.config = config;
@@ -37,8 +38,9 @@ class ClaimLoop {
         this.timer = null;
     }
     async tick() {
-        if (this.stopped || !this.capacity.hasCapacity())
+        if (this.stopped || this.claimInFlight || !this.capacity.hasCapacity())
             return;
+        this.claimInFlight = true;
         try {
             // Pre-allocate the session id BEFORE claiming (author-exclusion timing):
             // the dispatcher records it on the lease and excludes it from review
@@ -47,6 +49,7 @@ class ClaimLoop {
             const claimed = await this.api.claim({
                 available_capacity: this.capacity.available(),
                 capabilities: this.config.capabilities,
+                agent_type: this.config.agentType,
                 session_id: sessionId,
             });
             if (!claimed)
@@ -70,6 +73,9 @@ class ClaimLoop {
                 log.warn(`claim failed: ${String(err)}`);
             }
         }
+        finally {
+            this.claimInFlight = false;
+        }
     }
 }
 exports.ClaimLoop = ClaimLoop;