@sagentlab/navarch-runtime 0.1.2 → 0.1.3

package/README.md

@@ -78,6 +78,65 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 | `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 |
@@ -102,7 +161,7 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 | `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)
@@ -133,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
 
@@ -161,7 +225,7 @@ cli.cts
                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
@@ -195,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,
@@ -270,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
@@ -349,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
@@ -71,6 +73,9 @@ class ClaimLoop {
                 log.warn(`claim failed: ${String(err)}`);
             }
         }
+        finally {
+            this.claimInFlight = false;
+        }
     }
 }
 exports.ClaimLoop = ClaimLoop;

package/dist/exit-conditions.cjs

@@ -1,17 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractPrUrl = extractPrUrl;
 exports.parseClaudeJsonResult = parseClaudeJsonResult;
 exports.extractUsageFromClaudeJson = extractUsageFromClaudeJson;
 exports.parseCodexJsonEvents = parseCodexJsonEvents;
 exports.extractUsageFromCodexEvents = extractUsageFromCodexEvents;
 exports.extractFinalMessageFromCodexEvents = extractFinalMessageFromCodexEvents;
 exports.mapExitCondition = mapExitCondition;
-const PR_URL_PATTERN = /https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+/;
-function extractPrUrl(text) {
-    const match = text.match(PR_URL_PATTERN);
-    return match ? match[0] : null;
-}
 /**
  * Best-effort parse of `claude -p --output-format json` stdout into the
  * assumed result shape above. Tries the whole trimmed stdout first (the
@@ -69,10 +63,9 @@ function extractUsageFromClaudeJson(parsed) {
 }
 /**
  * Best-effort line-by-line parse of `codex exec --json` stdout into the
- * assumed JSONL event shape above. Silently skips any line that isn't a JSON
- * object carrying a `msg` field (blank lines, stray log lines, a shape that
- * doesn't match the guess) rather than throwing; returns an empty array (not
- * null) when nothing parses, since a run can legitimately emit zero events.
+ * verified JSONL event shape above. Silently skips any line that isn't a
+ * recognized JSON event (blank lines, stray log lines, unrelated objects)
+ * rather than throwing; returns an empty array when nothing parses.
  */
 function parseCodexJsonEvents(stdout) {
     const events = [];
@@ -83,8 +76,10 @@ function parseCodexJsonEvents(stdout) {
     for (const line of lines) {
         try {
             const parsed = JSON.parse(line);
-            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) && "msg" in parsed) {
-                events.push(parsed);
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                const event = parsed;
+                if (typeof event.type === "string" || event.msg !== undefined)
+                    events.push(event);
             }
         }
         catch {
@@ -94,17 +89,20 @@ function parseCodexJsonEvents(stdout) {
     return events;
 }
 /**
- * Extracts token/cost usage from parsed `codex exec --json` events. Assumes
- * each `token_count` event reports the run's cumulative totals so far (like
- * Claude Code's running usage updates), so the *last* such event wins rather
- * than summing across events; if that assumption is wrong (incremental
- * per-turn deltas instead), this under- or over-counts until reconciled here.
+ * Extracts token/cost usage from parsed `codex exec --json` events. The last
+ * `turn.completed` event wins. Legacy `token_count` events remain supported.
  */
 function extractUsageFromCodexEvents(events) {
     let tokensIn = 0;
     let tokensOut = 0;
     let costUsd = 0;
     for (const event of events) {
+        if (event.type === "turn.completed" && event.usage) {
+            tokensIn = event.usage.input_tokens ?? 0;
+            tokensOut = event.usage.output_tokens ?? 0;
+            if (typeof event.usage.total_cost_usd === "number")
+                costUsd = event.usage.total_cost_usd;
+        }
         if (event.msg?.type === "token_count") {
             tokensIn = (event.msg.input_tokens ?? 0) + (event.msg.cached_input_tokens ?? 0);
             tokensOut = event.msg.output_tokens ?? 0;
@@ -115,9 +113,15 @@ function extractUsageFromCodexEvents(events) {
     }
     return { tokensIn, tokensOut, costUsd };
 }
-/** The last `agent_message` event's text — assumed to be the run's final agent-visible output, mirroring Claude JSON result's `result` field. Returns null when no such event parsed (see parseCodexJsonEvents doc comment). */
+/** The last completed agent message, with legacy `msg.agent_message` fallback. */
 function extractFinalMessageFromCodexEvents(events) {
     for (let i = events.length - 1; i >= 0; i--) {
+        const item = events[i]?.item;
+        if (events[i]?.type === "item.completed" &&
+            item?.type === "agent_message" &&
+            typeof item.text === "string") {
+            return item.text;
+        }
         const msg = events[i]?.msg;
         if (msg?.type === "agent_message" && typeof msg.message === "string")
             return msg.message;
@@ -139,8 +143,11 @@ function summarize(text, maxLen = 500) {
  * exit > clean exit.
  */
 function mapExitCondition(result) {
-    const prUrl = extractPrUrl(result.stdout) ?? extractPrUrl(result.stderr);
-    const evidenceUrls = prUrl ? [prUrl] : [];
+    // Agent output is untrusted evidence, including the final completion
+    // message. session.cts resolves PR evidence independently through GitHub
+    // using this session's exact repository and worktree head branch.
+    const parsedJson = parseClaudeJsonResult(result.stdout);
+    const evidenceUrls = [];
     if (result.killedByLeaseLoss) {
         return {
             leaseOutcome: "failed",
@@ -179,9 +186,20 @@ function mapExitCondition(result) {
     // json` blob so report_summary doesn't end up being a dumped JSON object;
     // falls back to raw stdout when neither is available (see
     // parseClaudeJsonResult's doc comment).
-    const parsedJson = parseClaudeJsonResult(result.stdout);
     const reportText = result.reportText ?? parsedJson?.result ?? result.stdout;
     const reportSummary = summarize(reportText) || "Adapter completed with no report text.";
+    // Headless agent CLIs normally exit 0 after producing a final response,
+    // including when that response says the task could not start. Treat an
+    // explicit leading blocked verdict as a failed lease so the dispatcher can
+    // retry/escalate it instead of falsely moving unfinished work to Done.
+    if (/^blocked(?:\s|:|$)/i.test(reportText.trim())) {
+        return {
+            leaseOutcome: "failed",
+            exitStatus: "failed",
+            reportSummary,
+            evidenceUrls,
+        };
+    }
     return {
         leaseOutcome: "completed",
         exitStatus: "completed",

package/dist/git-worktree.cjs

@@ -46,15 +46,18 @@ class GitWorktree {
                     await this.runGit(["--git-dir", this.repositoryPath, "remote", "set-url", "origin", this.cloneUrl], false);
                 }
             }
-            const remoteHead = await this.runGit(["ls-remote", "--symref", "origin", "HEAD"], true);
-            const startRef = parseRemoteHead(remoteHead.stdout) ?? "HEAD";
+            const remoteHead = await this.runGit(["--git-dir", this.repositoryPath, "ls-remote", "--symref", "origin", "HEAD"], true);
+            const defaultBranch = parseRemoteHead(remoteHead.stdout);
+            const startRef = defaultBranch
+                ? defaultBranch.replace(/^refs\/heads\//, "refs/remotes/origin/")
+                : "HEAD";
             await this.runGit([
                 "--git-dir",
                 this.repositoryPath,
                 "fetch",
                 "--prune",
                 "origin",
-                "+refs/heads/*:refs/heads/*",
+                "+refs/heads/*:refs/remotes/origin/*",
             ], true);
             await this.runGit([
                 "--git-dir",

package/dist/github-pr.cjs

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findHeadBranchPullRequestUrl = findHeadBranchPullRequestUrl;
+const sandbox_cjs_1 = require("./sandbox.cjs");
+async function readHostGhToken() {
+    // Keep the credential in memory and out of shell parsing, argv, and logs.
+    const result = await sandbox_cjs_1.nodeCommandRunner.run("gh", ["auth", "token", "--hostname", "github.com"], { timeoutMs: 5_000 });
+    if (result.code !== 0)
+        return undefined;
+    const token = result.stdout.trim();
+    return token && !/\s/.test(token) ? token : undefined;
+}
+async function resolveGitHubToken(options) {
+    if (options.githubToken)
+        return options.githubToken;
+    try {
+        // Resolution is intentionally best-effort so public-repository lookup can
+        // still proceed when gh is absent or has no authenticated host account.
+        return await (options.hostTokenProvider ?? readHostGhToken)();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Finds the PR opened from this session's exact same-repository head branch.
+ * GitHub's head filter narrows the response, and the response is checked again
+ * before its URL is trusted so another repository or branch can never be
+ * attached as completion evidence.
+ */
+async function findHeadBranchPullRequestUrl(options) {
+    const [owner, name, ...extra] = options.repository.split("/");
+    if (!owner || !name || extra.length > 0) {
+        throw new Error(`Invalid GitHub repository name: ${options.repository}`);
+    }
+    const url = new URL(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/pulls`);
+    url.searchParams.set("state", "all");
+    url.searchParams.set("head", `${owner}:${options.headBranch}`);
+    url.searchParams.set("per_page", "10");
+    const headers = {
+        accept: "application/vnd.github+json",
+        "user-agent": "navarch-runtime",
+        "x-github-api-version": "2022-11-28",
+    };
+    const githubToken = await resolveGitHubToken(options);
+    if (githubToken)
+        headers.authorization = `Bearer ${githubToken}`;
+    const response = await (options.fetchImpl ?? fetch)(url, { headers });
+    if (!response.ok) {
+        throw new Error(`GitHub pull request lookup failed with HTTP ${response.status}`);
+    }
+    const body = await response.json();
+    if (!Array.isArray(body)) {
+        throw new Error("GitHub pull request lookup returned a non-array response");
+    }
+    const normalizedRepository = options.repository.toLowerCase();
+    for (const candidate of body) {
+        if (candidate.head?.ref !== options.headBranch)
+            continue;
+        const headRepository = candidate.head.repo?.full_name;
+        if (typeof headRepository !== "string")
+            continue;
+        if (headRepository.toLowerCase() !== normalizedRepository)
+            continue;
+        if (typeof candidate.html_url !== "string")
+            continue;
+        if (!isPullRequestUrlForRepository(candidate.html_url, normalizedRepository))
+            continue;
+        return candidate.html_url;
+    }
+    return null;
+}
+function isPullRequestUrlForRepository(value, repository) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" || url.hostname.toLowerCase() !== "github.com")
+            return false;
+        const parts = url.pathname.split("/").filter(Boolean);
+        return (parts.length === 4 &&
+            `${parts[0]}/${parts[1]}`.toLowerCase() === repository &&
+            parts[2] === "pull" &&
+            /^\d+$/.test(parts[3] ?? ""));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/prompt.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderPrompt = renderPrompt;
+exports.renderGuidanceCorrectionPrompt = renderGuidanceCorrectionPrompt;
 /**
  * Renders the four-layer context bundle (project-plan.md §3.8: steering docs,
  * task itself, task-type playbook, depends_on reports) into the single prompt
@@ -42,3 +43,20 @@ function renderPrompt(task, bundle) {
     sections.push(bundle.playbook);
     return sections.join("\n\n");
 }
+/**
+ * Builds a fresh agent turn after a human steers an active task. The runtime
+ * keeps the same worktree, so the replacement turn can inspect and continue
+ * partial edits instead of discarding mid-flight work.
+ */
+function renderGuidanceCorrectionPrompt(originalPrompt, guidance) {
+    const corrections = guidance.map((entry) => `- **${entry.given_at}**: ${entry.content}`);
+    return [
+        originalPrompt.trim(),
+        "## Mid-flight human guidance",
+        "",
+        "The task was actively steered while you were working. Human guidance takes precedence over earlier context. Continue in the same worktree: inspect the current changes, correct course, and then finish the task.",
+        "",
+        ...corrections,
+        "",
+    ].join("\n");
+}

package/dist/session.cjs

@@ -15,6 +15,7 @@ const prompt_cjs_1 = require("./prompt.cjs");
 const mcp_config_cjs_1 = require("./mcp-config.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const git_worktree_cjs_1 = require("./git-worktree.cjs");
+const github_pr_cjs_1 = require("./github-pr.cjs");
 /** Filename the generated platform MCP config is written under inside the session metadata directory. */
 const MCP_CONFIG_FILENAME = "mcp-config.json";
 const log = (0, logger_cjs_1.createLogger)("session");
@@ -39,6 +40,16 @@ const log = (0, logger_cjs_1.createLogger)("session");
 async function runSession(deps, claimed, sessionId) {
     const { api, config } = deps;
     const { lease_id: leaseId, task, context_bundle: bundle } = claimed;
+    const execution = bundle.execution ?? {
+        profile: task.execution_profile ?? "standard",
+        model: config.agentType === "codex" ? "gpt-5.6" : "best",
+        reasoning_effort: "medium",
+    };
+    const executionReport = {
+        model: execution.model,
+        execution_profile: execution.profile,
+        reasoning_effort: execution.reasoning_effort,
+    };
     // The session's identity is the pre-allocated session id sent at claim time
     // (recorded on the lease by the dispatcher). Lease-scoped API calls
     // (heartbeat/complete/issue/transcript) still key on leaseId.
@@ -69,28 +80,60 @@ async function runSession(deps, claimed, sessionId) {
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
             agent_type: config.agentType,
+            ...executionReport,
         });
         secrets = {};
         await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
         return;
     }
+    const githubToken = secrets[bundle.repository?.credential_secret_name ?? "github-pat"];
     const gitWorktree = new git_worktree_cjs_1.GitWorktree({
         workspaceRoot: config.workspaceRoot,
         projectId: task.project_id,
         taskId: task.id,
         sessionId,
         cloneUrl,
-        githubToken: secrets[bundle.repository?.credential_secret_name ?? "github-pat"],
+        githubToken,
     });
-    const abortController = new AbortController();
+    const knownGuidanceIds = new Set((bundle.guidance ?? []).map((entry) => entry.id));
+    const deliveredGuidance = [...(bundle.guidance ?? [])];
+    let guidanceCursor = bundle.guidance_cursor ?? null;
+    let pendingGuidance = [];
+    let activeAbortController = null;
     let leaseLost = false;
-    const heartbeatTimer = setInterval(() => {
-        api.heartbeatLease(leaseId).catch((err) => {
+    let heartbeatInFlight = null;
+    const pollLease = () => {
+        if (heartbeatInFlight)
+            return heartbeatInFlight;
+        const request = api
+            .heartbeatLease(leaseId, { guidance_after: guidanceCursor })
+            .then((heartbeat) => {
+            guidanceCursor = heartbeat.guidance_cursor ?? guidanceCursor;
+            const fresh = (heartbeat.guidance ?? []).filter((entry) => {
+                if (knownGuidanceIds.has(entry.id))
+                    return false;
+                knownGuidanceIds.add(entry.id);
+                return true;
+            });
+            if (fresh.length > 0) {
+                pendingGuidance.push(...fresh);
+                deliveredGuidance.push(...fresh);
+                log.info(`received ${fresh.length} guidance update${fresh.length === 1 ? "" : "s"} for ${leaseId}; restarting the agent turn in the same worktree.`);
+                activeAbortController?.abort();
+            }
+        })
+            .catch((err) => {
             log.warn(`lease heartbeat failed for ${leaseId}: ${String(err)} — killing session.`);
             leaseLost = true;
-            abortController.abort();
+            activeAbortController?.abort();
+        })
+            .finally(() => {
+            heartbeatInFlight = null;
         });
-    }, config.leaseHeartbeatIntervalMs);
+        heartbeatInFlight = request;
+        return request;
+    };
+    const heartbeatTimer = setInterval(() => void pollLease(), config.leaseHeartbeatIntervalMs);
     const dockerAvailable = config.sandboxMode === "docker" && (await (0, sandbox_cjs_1.isDockerAvailable)());
     if (config.sandboxMode === "docker" && !dockerAvailable) {
         clearInterval(heartbeatTimer);
@@ -104,6 +147,7 @@ async function runSession(deps, claimed, sessionId) {
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
             agent_type: config.agentType,
+            ...executionReport,
         })
             .catch((err) => log.warn(`complete() after docker-unavailable also failed: ${String(err)}`));
         secrets = {};
@@ -153,27 +197,78 @@ async function runSession(deps, claimed, sessionId) {
         const adapter = (0, index_cjs_1.selectAdapter)(config.agentType);
         const bin = config.agentType === "codex" ? config.codexBin : config.claudeBin;
         const extraArgs = config.agentType === "codex" ? config.codexExtraArgs : config.claudeExtraArgs;
-        const result = await adapter.run({
-            prompt: promptText,
-            mcpConfigPath,
-            bin,
-            extraArgs,
-            timeoutMs: config.sessionTimeoutMs,
-            env: toEnvMap(secrets),
-            cwd: sandbox ? undefined : gitWorktree.worktreePath,
-            dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
-            signal: abortController.signal,
-        });
+        const attempts = [];
+        let result;
+        while (true) {
+            // Guidance can arrive while the worktree/sandbox is being prepared.
+            // It is already included in deliveredGuidance, so clear the pending
+            // notification and start the first turn with the corrected prompt.
+            pendingGuidance = [];
+            activeAbortController = new AbortController();
+            if (leaseLost)
+                activeAbortController.abort();
+            const runPrompt = deliveredGuidance.length > (bundle.guidance?.length ?? 0)
+                ? (0, prompt_cjs_1.renderGuidanceCorrectionPrompt)(promptText, deliveredGuidance)
+                : promptText;
+            await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), runPrompt, "utf8");
+            const turnResult = await adapter.run({
+                prompt: runPrompt,
+                mcpConfigPath,
+                bin,
+                extraArgs,
+                model: execution.model,
+                reasoningEffort: execution.reasoning_effort,
+                timeoutMs: config.sessionTimeoutMs,
+                env: toEnvMap(secrets),
+                cwd: sandbox ? undefined : gitWorktree.worktreePath,
+                dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
+                signal: activeAbortController.signal,
+            });
+            activeAbortController = null;
+            attempts.push(turnResult);
+            // Close the small race between a naturally completed turn and the next
+            // scheduled heartbeat. If guidance landed, run another turn before the
+            // lease can be completed.
+            await pollLease();
+            if (!leaseLost && pendingGuidance.length > 0)
+                continue;
+            result = {
+                ...turnResult,
+                tokensIn: attempts.reduce((sum, attempt) => sum + (attempt.tokensIn ?? 0), 0),
+                tokensOut: attempts.reduce((sum, attempt) => sum + (attempt.tokensOut ?? 0), 0),
+                costUsd: attempts.reduce((sum, attempt) => sum + (attempt.costUsd ?? 0), 0),
+            };
+            break;
+        }
         const mapping = (0, exit_conditions_cjs_1.mapExitCondition)({ ...result, killedByLeaseLoss: leaseLost || result.killedByLeaseLoss });
+        try {
+            const prUrl = await (0, github_pr_cjs_1.findHeadBranchPullRequestUrl)({
+                repository: bundle.repository?.full_name ?? task.repo,
+                headBranch: gitWorktree.branch,
+                githubToken,
+            });
+            if (prUrl)
+                mapping.evidenceUrls.push(prUrl);
+        }
+        catch (err) {
+            // Evidence discovery is best-effort: a GitHub outage or token scope
+            // mismatch must not turn an otherwise valid completion into a crash.
+            log.warn(`head-branch PR lookup failed for ${leaseId}: ${String(err)}`);
+        }
         const knownSecrets = registry.list();
-        const transcript = [
-            "# stdout",
-            (0, redact_cjs_1.redactText)(result.stdout, knownSecrets),
+        if (mapping.leaseOutcome === "failed") {
+            log.warn(`adapter failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(mapping.reportSummary, knownSecrets)}`);
+        }
+        const transcript = attempts
+            .flatMap((attempt, index) => [
+            `# agent turn ${index + 1} stdout`,
+            (0, redact_cjs_1.redactText)(attempt.stdout, knownSecrets),
             "",
-            "# stderr",
-            (0, redact_cjs_1.redactText)(result.stderr, knownSecrets),
+            `# agent turn ${index + 1} stderr`,
+            (0, redact_cjs_1.redactText)(attempt.stderr, knownSecrets),
             "",
-        ].join("\n");
+        ])
+            .join("\n");
         let transcriptUrl;
         try {
             const { upload_url, public_url } = await api.getTranscriptUploadUrl(leaseId);
@@ -195,6 +290,7 @@ async function runSession(deps, claimed, sessionId) {
             transcript_url: transcriptUrl,
             exit_status: mapping.exitStatus,
             agent_type: config.agentType,
+            ...executionReport,
         });
     }
     catch (err) {
@@ -209,11 +305,13 @@ async function runSession(deps, claimed, sessionId) {
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
             agent_type: config.agentType,
+            ...executionReport,
         })
             .catch((completeErr) => log.warn(`complete() after crash also failed: ${String(completeErr)}`));
     }
     finally {
         clearInterval(heartbeatTimer);
+        activeAbortController?.abort();
         secrets = {};
         if (sandbox)
             await sandbox.stop();

package/dist/types.cjs

@@ -6,14 +6,7 @@
 //   - docs/navarch/implementation-plan.md  (WP-07 behavioral contract)
 //   - docs/agent-platform-project-plan.md   (§3.8 dispatch/§3.9 adapter contract)
 //
-// The control-plane API is being built in parallel (WP-01/WP-04/WP-05) in
-// other worktrees this agent cannot see. Fields/endpoints marked "ASSUMED"
-// are not pinned down by an explicit route contract in the docs as written
-// and were inferred from the closest analogous shape; see the WP-07 report
-// for the full list of assumptions to confirm once those WPs land. Everything
-// else is quoted close to verbatim from schema-design.md.
-//
-// runtime/src/api.cts is the ONLY place that turns these types into HTTP
-// calls, so reconciling an assumption against the real contract is a
-// same-file edit, not a rewrite.
+// These contracts are implemented by the matching app/api routes and are
+// documented in schema-design.md §7. runtime/src/api.cts is the only place
+// that turns them into HTTP calls.
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Navarch machine-side session manager: registers a machine, claims tasks from the control-plane dispatcher, runs them via the Claude Code or Codex adapter, and reports results back.",
   "type": "commonjs",
   "license": "MIT",
@@ -37,10 +37,10 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build && npm test",
-    "start": "node dist/cli.cjs start",
-    "register": "node dist/cli.cjs register",
-    "connect": "node dist/cli.cjs connect",
-    "doctor": "node dist/cli.cjs doctor"
+    "start": "node bin/navarch.cjs start",
+    "register": "node bin/navarch.cjs register",
+    "connect": "node bin/navarch.cjs connect",
+    "doctor": "node bin/navarch.cjs doctor"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",