@sagentlab/navarch-runtime 0.1.0 → 0.1.1

package/README.md

@@ -7,13 +7,13 @@ 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 `FLOTILLA_AGENT` (default `claude-code`) — see
+selected per machine via `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)
-§3.8/§3.9/§3.11 and [`docs/flotilla/implementation-plan.md`](../docs/flotilla/implementation-plan.md)
+§3.8/§3.9/§3.11 and [`docs/navarch/implementation-plan.md`](../docs/navarch/implementation-plan.md)
 WP-07 for the design this implements, and
-[`docs/flotilla/schema-design.md`](../docs/flotilla/schema-design.md) §7 for
+[`docs/navarch/schema-design.md`](../docs/navarch/schema-design.md) §7 for
 the API contract.
 
 ## Quick start on a fresh machine
@@ -21,7 +21,7 @@ the API contract.
 ```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
+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
 ```
@@ -30,15 +30,15 @@ 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
+NAVARCH_API_BASE=https://navarch.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
+once, to stdout. It is stored at `$NAVARCH_CONFIG_DIR/machine.json` (default
+`~/.navarch/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`
+skip `register` and set `NAVARCH_MACHINE_TOKEN` + `NAVARCH_MACHINE_ID`
 directly.
 
 Run `node bin/navarch.cjs doctor` any time to print resolved config, Docker
@@ -52,21 +52,21 @@ 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
+command. Unlike `register`, no `NAVARCH_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
+    --name my-agent-1 --api-base https://navarch.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.)
+(`@sagentlab/navarch-runtime` is published to npm, so `npx
+@sagentlab/navarch-runtime <cmd>` works on a fresh machine with no clone.
+The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
+<cmd>` — remains available for local development.)
 
 ## Commands
 
@@ -74,50 +74,50 @@ above.)
 |---|---|
 | `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. |
+| `start` | Runs the daemon: machine heartbeat loop + claim loop, `NAVARCH_MAX_SESSIONS` concurrent task sessions. |
 | `doctor` | Prints resolved config + Docker/registration status; no side effects. |
 
-## Configuration (`FLOTILLA_*` env vars)
+## Configuration (`NAVARCH_*` 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`. |
+| `NAVARCH_API_BASE` | `http://localhost:3000` | Control-plane base URL. |
+| `NAVARCH_MACHINE_TOKEN` / `NAVARCH_MACHINE_ID` | — | Skip `register`/the config file; twelve-factor auth. |
+| `NAVARCH_MACHINE_NAME` | — | Used by `register`. |
+| `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_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_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_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_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`:
+`NAVARCH_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
+# authenticated on this machine (or NAVARCH_CLAUDE_BIN pointing at it).
+export NAVARCH_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
+# this machine (or NAVARCH_CODEX_BIN pointing at it), analogous to the
 # Claude Code prerequisite above.
-export FLOTILLA_AGENT=codex
+export NAVARCH_AGENT=codex
 ```
 
 Both adapters implement the same `AgentAdapter` interface
@@ -144,17 +144,17 @@ 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:
+     ├─ MachineHeartbeatLoop   (heartbeat-loop.cts)   → api.machineHeartbeat()   [every NAVARCH_HEARTBEAT_INTERVAL_MS]
+     └─ ClaimLoop              (claim-loop.cts)        → api.claim()             [every NAVARCH_POLL_INTERVAL_MS, gated by CapacityTracker]
+          └─ 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)
                4. selectAdapter(config.agentType) (adapters/index.cts) picks one AgentAdapter
-                  (adapters/types.cts) by FLOTILLA_AGENT, then .run(...):
+                  (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)
-                  heartbeating the lease every FLOTILLA_LEASE_HEARTBEAT_INTERVAL_MS throughout either;
+                  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
@@ -229,13 +229,13 @@ everything that can be verified without those:
   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`).
+- `config.cts` — env var parsing and defaults, including `NAVARCH_AGENT`/
+  `NAVARCH_CODEX_BIN`/`NAVARCH_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
+  `NAVARCH_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
@@ -287,7 +287,7 @@ secrets absent from disk after exit"):
     `--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
+    `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
@@ -315,13 +315,14 @@ secrets absent from disk after exit"):
   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
+  (`lib/navarch/__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` is 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 ...`).
+  `ConnectAgentPanel`) resolves the published package directly; the
+  from-source flow (`git clone` + `./install.sh` + `node bin/navarch.cjs
+  connect ...`) is an equivalent local-development alternative.
 
 ## A note on `.cts` instead of `.ts`
 

package/dist/adapter.cjs

@@ -7,7 +7,7 @@ exports.claudeCodeAdapter = exports.runClaudeCodeAdapter = void 0;
  * 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
+ * sibling — session.cts picks between the two via NAVARCH_AGENT
  * (config.cts's `agentType`) through adapters/index.cts#selectAdapter.
  *
  * This file is kept, unchanged in its exported names, so any existing

package/dist/adapters/claude.cjs

@@ -14,7 +14,7 @@ const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
  *
  * 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`).
+ * session.cts picks between via NAVARCH_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
@@ -128,7 +128,7 @@ async function runViaDocker(options, args) {
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-/** The AgentAdapter (adapters/types.cts) wrapper session.cts selects via FLOTILLA_AGENT=claude-code (the default). */
+/** The AgentAdapter (adapters/types.cts) wrapper session.cts selects via NAVARCH_AGENT=claude-code (the default). */
 exports.claudeCodeAdapter = {
     agentType: "claude-code",
     run: runClaudeCodeAdapter,

package/dist/adapters/codex.cjs

@@ -8,7 +8,7 @@ const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
  * Headless OpenAI Codex CLI adapter — the Codex sibling of claude.cts's
  * `runClaudeCodeAdapter`, implementing the same AgentAdapter interface
  * (adapters/types.cts) so session.cts can pick either one at runtime via
- * FLOTILLA_AGENT (config.cts's `agentType`). Structurally this mirrors
+ * NAVARCH_AGENT (config.cts's `agentType`). Structurally this mirrors
  * claude.cts exactly: same host-vs-docker-exec split, same
  * timeout/AbortSignal handling, same "attach best-effort usage onto the raw
  * result" shape — only the CLI invocation and output parsing differ.
@@ -41,14 +41,14 @@ const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
  * - 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,
- *   in `FLOTILLA_SANDBOX_MODE=host`, trusts the host), the intent is to pass
+ *   in `NAVARCH_SANDBOX_MODE=host`, trusts the host), the intent is to pass
  *   whatever flag disables Codex's own approval gate for a fully
  *   non-interactive run (something like `--full-auto` or
  *   `--dangerously-bypass-approvals-and-sandbox` in published Codex CLI
  *   documentation) — deliberately NOT hardcoded here since getting an
  *   unverified flag wrong could silently change sandboxing behavior; left to
- *   be supplied via FLOTILLA_CODEX_EXTRA_ARGS until confirmed.
- * - `FLOTILLA_CODEX_EXTRA_ARGS` (`extraArgs`) wins over the default `--json`
+ *   be supplied via NAVARCH_CODEX_EXTRA_ARGS until confirmed.
+ * - `NAVARCH_CODEX_EXTRA_ARGS` (`extraArgs`) wins over the default `--json`
  *   exactly like the Claude adapter's `--output-format` opt-out, so an
  *   operator can fall back to plain-text output (or add the real
  *   approval-bypass flag) without an adapter code change.
@@ -160,7 +160,7 @@ async function runViaDocker(options, args) {
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-/** The AgentAdapter (adapters/types.cts) wrapper session.cts selects via FLOTILLA_AGENT=codex. */
+/** The AgentAdapter (adapters/types.cts) wrapper session.cts selects via NAVARCH_AGENT=codex. */
 exports.codexAdapter = {
     agentType: "codex",
     run: runCodexAdapter,

package/dist/adapters/index.cjs

@@ -10,7 +10,7 @@ Object.defineProperty(exports, "codexAdapter", { enumerable: true, get: function
 Object.defineProperty(exports, "runCodexAdapter", { enumerable: true, get: function () { return codex_cjs_1.runCodexAdapter; } });
 /**
  * Picks the AgentAdapter (adapters/types.cts) session.cts should run a
- * session with, keyed off config.cts's `agentType` (FLOTILLA_AGENT). This is
+ * session with, keyed off config.cts's `agentType` (NAVARCH_AGENT). This is
  * the one place agent-type branching happens outside config loading itself —
  * session.cts calls the returned adapter's `run()` uniformly regardless of
  * which one it got.

package/dist/api.cjs

@@ -74,11 +74,11 @@ class NavarchApiClient {
     }
     /**
      * `POST /api/machines/connect` — "Connect an agent to a project"
-     * (docs/flotilla/schema-design.md §7 "Agent connect"). CONFIRMED endpoint,
+     * (docs/navarch/schema-design.md §7 "Agent connect"). CONFIRMED endpoint,
      * the project-scoped sibling of {@link registerMachine}: redeems a
      * single-use, project-scoped enrollment token a project owner minted
      * (POST /api/projects/:id/enrollment-tokens) instead of the global
-     * FLOTILLA_ENROLLMENT_SECRET. Unauthenticated like registerMachine — the
+     * NAVARCH_ENROLLMENT_SECRET. Unauthenticated like registerMachine — the
      * enrollment token in the body is the auth.
      */
     async connectMachine(req) {

package/dist/capacity.cjs

@@ -9,7 +9,7 @@ function computeAvailableCapacity(maxSessions, activeSessions) {
 /**
  * Tracks which session (lease) ids currently occupy a slot on this machine so
  * the heartbeat loop reports accurate available_capacity and the claim loop
- * never over-claims beyond FLOTILLA_MAX_SESSIONS.
+ * never over-claims beyond NAVARCH_MAX_SESSIONS.
  */
 class CapacityTracker {
     maxSessions;

package/dist/claim-loop.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClaimLoop = void 0;
 const node_crypto_1 = require("node:crypto");
+const api_cjs_1 = require("./api.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const log = (0, logger_cjs_1.createLogger)("claim");
 /**
@@ -57,7 +58,17 @@ class ClaimLoop {
                 .finally(() => this.capacity.release(claimed.lease_id));
         }
         catch (err) {
-            log.warn(`claim failed: ${String(err)}`);
+            // NavarchApiError's message is only the status line ("… failed with
+            // 500"); the control plane's actual error text lives in `.body`. Log it
+            // so a server-side claim failure is diagnosable from the runtime alone
+            // instead of an opaque bare status.
+            if (err instanceof api_cjs_1.NavarchApiError) {
+                const detail = typeof err.body === "string" ? err.body : JSON.stringify(err.body);
+                log.warn(`claim failed: ${err.message}${detail ? ` — ${detail}` : ""}`);
+            }
+            else {
+                log.warn(`claim failed: ${String(err)}`);
+            }
         }
     }
 }

package/dist/cli.cjs

@@ -11,6 +11,24 @@ const session_cjs_1 = require("./session.cjs");
 const sandbox_cjs_1 = require("./sandbox.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const log = (0, logger_cjs_1.createLogger)("cli");
+const PACKAGE_NAME = "@sagentlab/navarch-runtime";
+/**
+ * How to tell the user to re-invoke this CLI, matching however THEY launched
+ * it. The bare `navarch-runtime` bin only exists on PATH after a global install
+ * (`npm i -g`) or `npm link`; the documented onboarding path is `npx
+ * @sagentlab/navarch-runtime …`, where the bare name is NOT on PATH. Printing
+ * `navarch-runtime start` to someone who ran us via npx sends them straight
+ * into `command not found`, so detect that case and echo the form that works.
+ */
+function invocation(subcommand) {
+    const scriptPath = process.argv[1] ?? "";
+    const viaNpx = scriptPath.includes("/_npx/") ||
+        scriptPath.includes("\\_npx\\") ||
+        process.env.npm_command === "exec" ||
+        process.env.npm_lifecycle_event === "npx";
+    const prefix = viaNpx ? `npx ${PACKAGE_NAME}` : "navarch-runtime";
+    return `${prefix} ${subcommand}`;
+}
 function parseArgs(argv) {
     const [command, ...rest] = argv;
     const flags = {};
@@ -38,13 +56,13 @@ function parseArgs(argv) {
 async function registerCommand(flags) {
     const config = (0, config_cjs_1.loadRuntimeConfig)();
     const apiBase = flags["api-base"] ?? config.apiBase;
-    const enrollmentToken = flags.token ?? process.env.FLOTILLA_ENROLLMENT_TOKEN;
-    const name = flags.name ?? process.env.FLOTILLA_MACHINE_NAME;
+    const enrollmentToken = flags.token ?? process.env.NAVARCH_ENROLLMENT_TOKEN;
+    const name = flags.name ?? process.env.NAVARCH_MACHINE_NAME;
     if (!enrollmentToken) {
-        throw new Error("Missing --token (or FLOTILLA_ENROLLMENT_TOKEN) — get one from the admin console.");
+        throw new Error("Missing --token (or NAVARCH_ENROLLMENT_TOKEN) — get one from the admin console.");
     }
     if (!name) {
-        throw new Error("Missing --name (or FLOTILLA_MACHINE_NAME) for this machine.");
+        throw new Error("Missing --name (or NAVARCH_MACHINE_NAME) for this machine.");
     }
     const maxSessions = Number(flags["max-sessions"] ?? config.maxSessions);
     const capabilities = (flags.capabilities ?? config.capabilities.join(","))
@@ -70,28 +88,28 @@ async function registerCommand(flags) {
     console.log("Machine registered.");
     console.log(`  machine_id: ${result.machine_id}`);
     console.log(`  token:      ${result.token}`);
-    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`navarch-runtime start\` to begin serving tasks.`);
+    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`${invocation("start")}\` to begin serving tasks.`);
 }
 /**
  * `navarch-runtime connect` — "Connect an agent to a project"
- * (docs/flotilla/schema-design.md §7 "Agent connect"; self-hosted-runner
+ * (docs/navarch/schema-design.md §7 "Agent connect"; self-hosted-runner
  * style). The project-scoped sibling of `register`: redeems a short-lived,
  * single-use enrollment token a project owner minted from the platform UI
  * (ConnectAgentPanel → POST /api/projects/:id/enrollment-tokens) instead of
- * the global FLOTILLA_ENROLLMENT_SECRET `register` needs. Prints the
+ * the global NAVARCH_ENROLLMENT_SECRET `register` needs. Prints the
  * machine token exactly once, same discipline as `register`.
  */
 async function connectCommand(flags) {
     const config = (0, config_cjs_1.loadRuntimeConfig)();
     const apiBase = flags["api-base"] ?? config.apiBase;
-    const enrollmentToken = flags.token ?? process.env.FLOTILLA_ENROLLMENT_TOKEN;
-    const name = flags.name ?? process.env.FLOTILLA_MACHINE_NAME;
-    const projectId = flags.project ?? process.env.FLOTILLA_PROJECT_ID;
+    const enrollmentToken = flags.token ?? process.env.NAVARCH_ENROLLMENT_TOKEN;
+    const name = flags.name ?? process.env.NAVARCH_MACHINE_NAME;
+    const projectId = flags.project ?? process.env.NAVARCH_PROJECT_ID;
     if (!enrollmentToken) {
-        throw new Error("Missing --token (or FLOTILLA_ENROLLMENT_TOKEN) — get one from a project owner's \"Connect an agent\" panel.");
+        throw new Error("Missing --token (or NAVARCH_ENROLLMENT_TOKEN) — get one from a project owner's \"Connect an agent\" panel.");
     }
     if (!name) {
-        throw new Error("Missing --name (or FLOTILLA_MACHINE_NAME) for this machine.");
+        throw new Error("Missing --name (or NAVARCH_MACHINE_NAME) for this machine.");
     }
     const maxSessions = Number(flags["max-sessions"] ?? config.maxSessions);
     const capabilities = (flags.capabilities ?? config.capabilities.join(","))
@@ -116,7 +134,7 @@ async function connectCommand(flags) {
     console.log("Machine connected.");
     console.log(`  machine_id: ${result.machine_id}`);
     console.log(`  token:      ${result.token}`);
-    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`navarch-runtime start\` to begin serving tasks.`);
+    console.log(`\nStored in ${config.configDir}/machine.json (mode 0600). Run \`${invocation("start")}\` to begin serving tasks.`);
 }
 async function startCommand() {
     const config = (0, config_cjs_1.loadRuntimeConfig)();
@@ -152,7 +170,7 @@ async function doctorCommand() {
         console.log(`machine:         ${identity.name} (${identity.machine_id})`);
     }
     catch {
-        console.log("machine:         not registered — run `navarch-runtime register`");
+        console.log(`machine:         not registered — run \`${invocation("register")}\``);
     }
 }
 function helpText() {
@@ -166,7 +184,7 @@ Usage:
   navarch-runtime start
   navarch-runtime doctor
 
-Configuration is via FLOTILLA_* environment variables; see runtime/README.md.
+Configuration is via NAVARCH_* environment variables; see runtime/README.md.
 `;
 }
 async function main(argv = process.argv.slice(2)) {

package/dist/config.cjs

@@ -23,33 +23,33 @@ function envList(env, name, fallback) {
         .filter(Boolean);
 }
 /**
- * Loads runtime config from FLOTILLA_* env vars, with sane defaults for a
+ * Loads runtime config from NAVARCH_* env vars, with sane defaults for a
  * fresh machine. Accepts an explicit env map (defaulting to process.env) so
  * it is trivially unit-testable without mutating global state.
  */
 function loadRuntimeConfig(env = process.env) {
-    const configDir = env.FLOTILLA_CONFIG_DIR ?? node_path_1.default.join(node_os_1.default.homedir(), ".flotilla");
-    const leaseHeartbeatIntervalMs = envInt(env, "FLOTILLA_LEASE_HEARTBEAT_INTERVAL_MS", 5 * 60 * 1000);
+    const configDir = env.NAVARCH_CONFIG_DIR ?? node_path_1.default.join(node_os_1.default.homedir(), ".navarch");
+    const leaseHeartbeatIntervalMs = envInt(env, "NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS", 5 * 60 * 1000);
     return {
-        apiBase: env.FLOTILLA_API_BASE ?? "http://localhost:3000",
-        workspaceRoot: env.FLOTILLA_WORKSPACE_ROOT ?? node_path_1.default.join(configDir, "sandboxes"),
+        apiBase: env.NAVARCH_API_BASE ?? "http://localhost:3000",
+        workspaceRoot: env.NAVARCH_WORKSPACE_ROOT ?? node_path_1.default.join(configDir, "sandboxes"),
         configDir,
-        maxSessions: envInt(env, "FLOTILLA_MAX_SESSIONS", 3),
-        capabilities: envList(env, "FLOTILLA_CAPABILITIES", ["docker-sandbox", "shell"]),
-        ownerZone: env.FLOTILLA_OWNER_ZONE ?? "sagentlab",
-        pollIntervalMs: envInt(env, "FLOTILLA_POLL_INTERVAL_MS", 5000),
-        machineHeartbeatIntervalMs: envInt(env, "FLOTILLA_HEARTBEAT_INTERVAL_MS", 60_000),
+        maxSessions: envInt(env, "NAVARCH_MAX_SESSIONS", 3),
+        capabilities: envList(env, "NAVARCH_CAPABILITIES", ["docker-sandbox", "shell"]),
+        ownerZone: env.NAVARCH_OWNER_ZONE ?? "sagentlab",
+        pollIntervalMs: envInt(env, "NAVARCH_POLL_INTERVAL_MS", 5000),
+        machineHeartbeatIntervalMs: envInt(env, "NAVARCH_HEARTBEAT_INTERVAL_MS", 60_000),
         // leases.expires_at = claimed_at + 15 min (schema-design.md §4) — default renewal
         // interval must stay comfortably under that TTL.
         leaseHeartbeatIntervalMs,
-        sessionTimeoutMs: envInt(env, "FLOTILLA_SESSION_TIMEOUT_MS", 45 * 60 * 1000),
-        agentType: env.FLOTILLA_AGENT === "codex" ? "codex" : "claude-code",
-        claudeBin: env.FLOTILLA_CLAUDE_BIN ?? "claude",
-        claudeExtraArgs: envList(env, "FLOTILLA_CLAUDE_EXTRA_ARGS", []),
-        codexBin: env.FLOTILLA_CODEX_BIN ?? "codex",
-        codexExtraArgs: envList(env, "FLOTILLA_CODEX_EXTRA_ARGS", []),
-        mcpConfigPath: env.FLOTILLA_MCP_CONFIG_PATH ?? null,
-        sandboxMode: env.FLOTILLA_SANDBOX_MODE === "host" ? "host" : "docker",
-        dockerImage: env.FLOTILLA_DOCKER_IMAGE ?? "node:20-slim",
+        sessionTimeoutMs: envInt(env, "NAVARCH_SESSION_TIMEOUT_MS", 45 * 60 * 1000),
+        agentType: env.NAVARCH_AGENT === "codex" ? "codex" : "claude-code",
+        claudeBin: env.NAVARCH_CLAUDE_BIN ?? "claude",
+        claudeExtraArgs: envList(env, "NAVARCH_CLAUDE_EXTRA_ARGS", []),
+        codexBin: env.NAVARCH_CODEX_BIN ?? "codex",
+        codexExtraArgs: envList(env, "NAVARCH_CODEX_EXTRA_ARGS", []),
+        mcpConfigPath: env.NAVARCH_MCP_CONFIG_PATH ?? null,
+        sandboxMode: env.NAVARCH_SANDBOX_MODE === "host" ? "host" : "docker",
+        dockerImage: env.NAVARCH_DOCKER_IMAGE ?? "node:20-slim",
     };
 }

package/dist/machine-store.cjs

@@ -40,19 +40,19 @@ async function loadMachineIdentity(configDir) {
  * per-task broker-issued secrets, handled entirely in session.cts/sandbox.cts.
  */
 async function resolveMachineIdentity(configDir, apiBaseFallback) {
-    const envToken = process.env.FLOTILLA_MACHINE_TOKEN;
-    const envId = process.env.FLOTILLA_MACHINE_ID;
+    const envToken = process.env.NAVARCH_MACHINE_TOKEN;
+    const envId = process.env.NAVARCH_MACHINE_ID;
     if (envToken && envId) {
         return {
             machine_id: envId,
             token: envToken,
-            name: process.env.FLOTILLA_MACHINE_NAME ?? envId,
-            api_base: process.env.FLOTILLA_API_BASE ?? apiBaseFallback,
+            name: process.env.NAVARCH_MACHINE_NAME ?? envId,
+            api_base: process.env.NAVARCH_API_BASE ?? apiBaseFallback,
         };
     }
     const stored = await loadMachineIdentity(configDir);
     if (stored)
         return stored;
     throw new Error("No machine identity found. Run `navarch-runtime register` first, or set " +
-        "FLOTILLA_MACHINE_TOKEN + FLOTILLA_MACHINE_ID for a twelve-factor deployment.");
+        "NAVARCH_MACHINE_TOKEN + NAVARCH_MACHINE_ID for a twelve-factor deployment.");
 }

package/dist/mcp-config.cjs

@@ -5,27 +5,27 @@
 // platform MCP server".
 //
 // Previously `mcpConfigPath` was just a static, operator-supplied path
-// (config.cts's `FLOTILLA_MCP_CONFIG_PATH`) with nothing that ever wrote a
+// (config.cts's `NAVARCH_MCP_CONFIG_PATH`) with nothing that ever wrote a
 // real config file -- there was no way for a session to actually reach the
 // platform MCP server with the auth it needs. This module is the fix: one
 // config, generated fresh per session, carrying the machine's bearer token
 // and this session's lease id (the same two-layer auth app/api/mcp/route.ts
-// requires -- see lib/flotilla/mcp/context.ts).
+// requires -- see lib/navarch/mcp/context.ts).
 //
 // Pure and side-effect free (no filesystem access) so it's trivially unit
 // testable; session.cts is the only caller that writes the result to disk.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FLOTILLA_LEASE_HEADER = void 0;
+exports.NAVARCH_LEASE_HEADER = void 0;
 exports.buildNavarchMcpConfig = buildNavarchMcpConfig;
-/** The header app/api/mcp/route.ts's lib/flotilla/mcp/context.ts reads to identify which lease is calling. */
-exports.FLOTILLA_LEASE_HEADER = "X-Navarch-Lease-Id";
+/** The header app/api/mcp/route.ts's lib/navarch/mcp/context.ts reads to identify which lease is calling. */
+exports.NAVARCH_LEASE_HEADER = "X-Navarch-Lease-Id";
 /**
  * Builds the `.mcp.json`-shaped config object Claude Code's `--mcp-config`
  * flag expects: a remote "http" (streamable HTTP) server entry with the
  * bearer token and lease id as request headers.
  */
 function buildNavarchMcpConfig(opts) {
-    const serverName = opts.serverName ?? "flotilla";
+    const serverName = opts.serverName ?? "navarch";
     return {
         mcpServers: {
             [serverName]: {
@@ -33,7 +33,7 @@ function buildNavarchMcpConfig(opts) {
                 url: `${opts.apiBase.replace(/\/+$/, "")}/api/mcp`,
                 headers: {
                     Authorization: `Bearer ${opts.machineToken}`,
-                    [exports.FLOTILLA_LEASE_HEADER]: opts.leaseId,
+                    [exports.NAVARCH_LEASE_HEADER]: opts.leaseId,
                 },
             },
         },

package/dist/prompt.cjs

@@ -9,6 +9,11 @@ exports.renderPrompt = renderPrompt;
  * WP-07 "write prompt file".
  */
 function renderPrompt(task, bundle) {
+    if (bundle.task_context) {
+        return [bundle.task_context.trim(), bundle.retry_context?.trim()]
+            .filter((section) => Boolean(section))
+            .join("\n\n") + "\n";
+    }
     const sections = [];
     sections.push(`# Task: ${task.summary}`);
     sections.push(`Type: ${task.task_type} | Repo: ${task.repo} | Environment: ${task.environment_scope}`);

package/dist/sandbox.cjs

@@ -69,7 +69,7 @@ async function isDockerAvailable(runner = exports.nodeCommandRunner) {
     }
 }
 function containerName(sessionId) {
-    return `flotilla-${sessionId}`;
+    return `navarch-${sessionId}`;
 }
 /**
  * One Docker container per session (implementation-plan.md WP-07 "Sandbox:

package/dist/session.cjs

@@ -23,7 +23,7 @@ const log = (0, logger_cjs_1.createLogger)("session");
  *   2. fetch secrets from the broker once, at session start
  *   3. stand up a Docker sandbox, clone the repo, inject env vars
  *   4. run the configured agent adapter (Claude Code or Codex, per
- *      FLOTILLA_AGENT — adapters/index.cts#selectAdapter), heartbeating the
+ *      NAVARCH_AGENT — adapters/index.cts#selectAdapter), heartbeating the
  *      lease throughout
  *   5. redact + upload the transcript, map the exit condition, complete the
  *      lease (recording which agent_type ran it)
@@ -87,8 +87,8 @@ async function runSession(deps, claimed, sessionId) {
     // Platform MCP config (implementation-plan.md WP-07: "--mcp-config
     // pointing at the platform MCP server"): generated fresh per session,
     // carrying this machine's bearer token and this session's lease id (the
-    // auth app/api/mcp/route.ts requires -- see lib/flotilla/mcp/context.ts),
-    // unless the operator pinned a static override via FLOTILLA_MCP_CONFIG_PATH
+    // auth app/api/mcp/route.ts requires -- see lib/navarch/mcp/context.ts),
+    // unless the operator pinned a static override via NAVARCH_MCP_CONFIG_PATH
     // (e.g. pointing at a fake MCP server in local testing). Written to
     // workDir (host path) so it also lands at /workspace/mcp-config.json
     // inside the Docker sandbox (sandbox.cts binds workDir at /workspace) --
@@ -110,7 +110,7 @@ async function runSession(deps, claimed, sessionId) {
             await sandbox.injectEnv(toEnvMap(secrets));
             await sandbox.cloneRepo(task.repo, Boolean(secrets["github-pat"]));
         }
-        // Picks the Claude Code or Codex adapter per FLOTILLA_AGENT
+        // Picks the Claude Code or Codex adapter per NAVARCH_AGENT
         // (config.cts's `agentType`) — see adapters/index.cts#selectAdapter.
         // Both adapters implement the same AgentAdapter.run() shape
         // (adapters/types.cts), so nothing else in this function branches on

package/dist/types.cjs

@@ -2,8 +2,8 @@
 // Navarch runtime — shared wire types.
 //
 // These interfaces mirror the JSON shapes described in:
-//   - docs/flotilla/schema-design.md        (table columns => API field names, esp. §4, §5, §7)
-//   - docs/flotilla/implementation-plan.md  (WP-07 behavioral contract)
+//   - docs/navarch/schema-design.md        (table columns => API field names, esp. §4, §5, §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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Navarch machine-side session manager: registers a machine, claims tasks from the control-plane dispatcher, runs them in a Docker sandbox via the Claude Code or Codex adapter, and reports results back.",
   "type": "commonjs",
   "license": "MIT",
@@ -45,6 +45,6 @@
   "devDependencies": {
     "@types/node": "^20.14.0",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.10"
   }
 }