@sagentlab/navarch-runtime 0.1.0 → 0.1.2

package/README.md

@@ -7,21 +7,22 @@ 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 by the local machine via `--agent` or `NAVARCH_AGENT` (default
+`claude-code`) — see
 "Choosing an agent (Claude Code vs. Codex)" below.
 
 See [`docs/agent-platform-project-plan.md`](../docs/agent-platform-project-plan.md)
-§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
 
 ```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
+./install.sh          # checks node, npm install, npm run build
+export NAVARCH_API_BASE=https://navarch.example.com
 node bin/navarch.cjs register --token <enrollment-token> --name my-machine-1
 node bin/navarch.cjs start
 ```
@@ -30,15 +31,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
@@ -48,78 +49,83 @@ availability, and registration status without starting the daemon.
 
 `connect` is the project-scoped sibling of `register` — "Connect an agent to
 a project" (self-hosted-runner style, like a GitHub Actions self-hosted
-runner token): a project **owner** mints a short-lived (60 minute),
-single-use token from the platform UI (the project settings page's "Connect
+runner token): a project **owner** mints a single-use token from the platform
+UI (the project settings page's "Connect
 an agent" panel, or the onboarding wizard's Agent step),
 `POST /api/projects/:id/enrollment-tokens`, and pastes you the ready-to-run
-command. Unlike `register`, no `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 --agent codex --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
 
 | Command | Purpose |
 |---|---|
-| `register --token <t> --name <n> [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]` | Registers this machine (global enrollment secret), prints the token once. |
-| `connect --token <t> --name <n> [--project <id>] [--capabilities a,b] [--max-sessions N] [--api-base url]` | Connects this machine to exactly one project (project-scoped enrollment token), prints the token once. |
-| `start` | Runs the daemon: machine heartbeat loop + claim loop, `FLOTILLA_MAX_SESSIONS` concurrent task sessions. |
+| `register --token <t> --name <n> [--agent claude-code\|codex] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
+| `connect --token <t> --name <n> [--agent claude-code\|codex] [--project <id>] […]` | Connects this machine to one project, saves its local agent choice, and prints the token once. |
+| `start [--agent claude-code\|codex]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
 | `doctor` | Prints resolved config + Docker/registration status; no side effects. |
 
-## 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` | Persistent bare repo caches plus isolated per-session worktrees. |
+| `NAVARCH_MAX_SESSIONS` | `5` | Local concurrent-session capacity cap — see `src/capacity.cts`. |
+| `NAVARCH_CAPABILITIES` | `shell` (`docker-sandbox,shell` in Docker mode) | Comma list reported at heartbeat/claim time. |
+| `NAVARCH_OWNER_ZONE` | `sagentlab` | `sagentlab` or `customer-<slug>-premises` (project-plan.md §3.11). |
+| `NAVARCH_POLL_INTERVAL_MS` | `5000` | Claim-loop poll interval. |
+| `NAVARCH_HEARTBEAT_INTERVAL_MS` | `60000` | Machine-level heartbeat interval. |
+| `NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS` | `300000` | Per-lease heartbeat interval; must stay well under the 15-minute lease TTL (schema-design.md §4). |
+| `NAVARCH_SESSION_TIMEOUT_MS` | `2700000` (45 min) | Hard kill timeout for a single session. |
+| `NAVARCH_SANDBOX_MODE` | `host` | `host` uses the resources already available to the agent process. Set `docker` explicitly for container isolation. |
+| `NAVARCH_DOCKER_IMAGE` | `node:20-slim` | Image used for the per-session container. |
+| `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent CLI: `claude-code` or `codex`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
+| `NAVARCH_CLAUDE_BIN` | `claude` | Path/name of the Claude Code CLI binary. |
+| `NAVARCH_CLAUDE_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `--mcp-config` (Claude Code). |
+| `NAVARCH_CODEX_BIN` | `codex` | Path/name of the Codex CLI binary. |
+| `NAVARCH_CODEX_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `--mcp-config`/`--json` (Codex). |
+| `NAVARCH_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`:
+Each machine chooses its own agent CLI. Pass `--agent` while connecting to
+persist the choice in local `machine.json`, override it for one daemon start
+with `start --agent`, or set `NAVARCH_AGENT` in the machine's service
+environment:
 
 ```sh
 # Claude Code (default) — requires the `claude` CLI installed and
-# 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
 ```
 
+Priority is `start --agent` → `NAVARCH_AGENT` → the locally saved choice →
+`claude-code`. The control plane does not choose the adapter.
+
 Both adapters implement the same `AgentAdapter` interface
 (`src/adapters/types.cts`) and run either directly on the host or via
 `docker exec` in the session's sandbox container, exactly like the Claude
@@ -144,21 +150,24 @@ 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)
+               3. fetch the project's bare repository cache and create a
+                  unique git worktree for this session; optionally mount it
+                  into Docker when NAVARCH_SANDBOX_MODE=docker
                4. selectAdapter(config.agentType) (adapters/index.cts) picks one AgentAdapter
-                  (adapters/types.cts) by 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
-               7. sandbox.wipe() unconditionally (finally block)
+               7. sandbox.wipe() when present; remove the session workspace
+                  unconditionally (finally block)
 ```
 
 `adapter.cts` (top-level) is now a backward-compat re-export of
@@ -229,13 +238,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 +296,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 +324,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");
 /**
@@ -46,6 +47,7 @@ class ClaimLoop {
             const claimed = await this.api.claim({
                 available_capacity: this.capacity.available(),
                 capabilities: this.config.capabilities,
+                agent_type: this.config.agentType,
                 session_id: sessionId,
             });
             if (!claimed)
@@ -57,7 +59,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,33 @@ 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 agentFromFlag(flags) {
+    const value = flags.agent;
+    if (value === undefined)
+        return undefined;
+    if (!(0, config_cjs_1.isRuntimeAgentType)(value)) {
+        throw new Error("--agent must be either 'claude-code' or 'codex'.");
+    }
+    return value;
+}
 function parseArgs(argv) {
     const [command, ...rest] = argv;
     const flags = {};
@@ -38,13 +65,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(","))
@@ -52,6 +79,7 @@ async function registerCommand(flags) {
         .map((s) => s.trim())
         .filter(Boolean);
     const ownerZone = flags["owner-zone"] ?? config.ownerZone;
+    const agentType = agentFromFlag(flags) ?? config.agentType;
     const client = new api_cjs_1.NavarchApiClient({ baseUrl: apiBase });
     const result = await client.registerMachine({
         enrollment_token: enrollmentToken,
@@ -65,39 +93,41 @@ async function registerCommand(flags) {
         token: result.token,
         name,
         api_base: apiBase,
+        agent_type: agentType,
     });
     // Printed exactly once. Never logged or echoed again after this point.
     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
- * style). The project-scoped sibling of `register`: redeems a short-lived,
- * single-use enrollment token a project owner minted from the platform UI
+ * (docs/navarch/schema-design.md §7 "Agent connect"; self-hosted-runner
+ * style). The project-scoped sibling of `register`: redeems a 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(","))
         .split(",")
         .map((s) => s.trim())
         .filter(Boolean);
+    const agentType = agentFromFlag(flags) ?? config.agentType;
     const client = new api_cjs_1.NavarchApiClient({ baseUrl: apiBase });
     const result = await client.connectMachine({
         enrollment_token: enrollmentToken,
@@ -111,23 +141,30 @@ async function connectCommand(flags) {
         token: result.token,
         name,
         api_base: apiBase,
+        agent_type: agentType,
     });
     // Printed exactly once. Never logged or echoed again after this point.
     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)();
-    const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(config.configDir, config.apiBase);
+async function startCommand(flags) {
+    const baseConfig = (0, config_cjs_1.loadRuntimeConfig)();
+    const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(baseConfig.configDir, baseConfig.apiBase);
+    // Adapter selection belongs to the local machine: an explicit start flag
+    // wins, followed by NAVARCH_AGENT, the choice saved at connect/register
+    // time, and finally the backwards-compatible Claude Code default.
+    const agentType = agentFromFlag(flags) ??
+        (process.env.NAVARCH_AGENT ? baseConfig.agentType : identity.agent_type ?? baseConfig.agentType);
+    const config = { ...baseConfig, agentType };
     const api = new api_cjs_1.NavarchApiClient({ baseUrl: identity.api_base, token: identity.token });
     const capacity = new capacity_cjs_1.CapacityTracker(config.maxSessions);
     const heartbeat = new heartbeat_loop_cjs_1.MachineHeartbeatLoop(api, identity.machine_id, config, capacity);
     const claimLoop = new claim_loop_cjs_1.ClaimLoop(api, config, capacity, (claimed, sessionId) => (0, session_cjs_1.runSession)({ api, config }, claimed, sessionId));
     heartbeat.start();
     claimLoop.start();
-    log.info(`navarch-runtime started: machine=${identity.name} max_sessions=${config.maxSessions} api_base=${identity.api_base}`);
+    log.info(`navarch-runtime started: machine=${identity.name} agent=${config.agentType} max_sessions=${config.maxSessions} api_base=${identity.api_base}`);
     const shutdown = () => {
         log.info("shutting down...");
         heartbeat.stop();
@@ -137,7 +174,7 @@ async function startCommand() {
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
 }
-async function doctorCommand() {
+async function doctorCommand(flags) {
     const config = (0, config_cjs_1.loadRuntimeConfig)();
     const dockerOk = await (0, sandbox_cjs_1.isDockerAvailable)();
     console.log(`api_base:        ${config.apiBase}`);
@@ -147,26 +184,31 @@ async function doctorCommand() {
     console.log(`capabilities:    ${config.capabilities.join(", ")}`);
     console.log(`sandbox_mode:    ${config.sandboxMode}`);
     console.log(`docker:          ${dockerOk ? "available" : "NOT AVAILABLE (docker-backed sessions will fail)"}`);
+    let identity;
     try {
-        const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(config.configDir, config.apiBase);
-        console.log(`machine:         ${identity.name} (${identity.machine_id})`);
+        identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(config.configDir, config.apiBase);
     }
     catch {
-        console.log("machine:         not registered — run `navarch-runtime register`");
+        console.log(`machine:         not registered — run \`${invocation("register")}\``);
+        return;
     }
+    const agentType = agentFromFlag(flags) ??
+        (process.env.NAVARCH_AGENT ? config.agentType : identity.agent_type ?? config.agentType);
+    console.log(`machine:         ${identity.name} (${identity.machine_id})`);
+    console.log(`agent:           ${agentType}`);
 }
 function helpText() {
     return `navarch-runtime — Navarch machine-side session manager
 
 Usage:
   navarch-runtime register --token <enrollment-token> --name <machine-name> \\
-      [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
+      [--agent claude-code|codex] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
   navarch-runtime connect --token <enrollment-token> --name <machine-name> \\
-      [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
-  navarch-runtime start
+      [--agent claude-code|codex] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
+  navarch-runtime start [--agent claude-code|codex]
   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)) {
@@ -180,10 +222,10 @@ async function main(argv = process.argv.slice(2)) {
                 await connectCommand(flags);
                 break;
             case "start":
-                await startCommand();
+                await startCommand(flags);
                 break;
             case "doctor":
-                await doctorCommand();
+                await doctorCommand(flags);
                 break;
             case "help":
             case "--help":

package/dist/config.cjs

@@ -3,9 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRuntimeAgentType = isRuntimeAgentType;
 exports.loadRuntimeConfig = loadRuntimeConfig;
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+function isRuntimeAgentType(value) {
+    return value === "claude-code" || value === "codex";
+}
 function envInt(env, name, fallback) {
     const raw = env[name];
     if (!raw)
@@ -23,33 +27,38 @@ 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);
+    // Run the agent with the resources already available on its machine by
+    // default. Docker isolation is an explicit operator opt-in, not a
+    // prerequisite for claiming ordinary shell work.
+    const sandboxMode = env.NAVARCH_SANDBOX_MODE === "docker" ? "docker" : "host";
+    const defaultCapabilities = sandboxMode === "docker" ? ["docker-sandbox", "shell"] : ["shell"];
     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", 5),
+        capabilities: envList(env, "NAVARCH_CAPABILITIES", defaultCapabilities),
+        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: isRuntimeAgentType(env.NAVARCH_AGENT) ? env.NAVARCH_AGENT : "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,
+        dockerImage: env.NAVARCH_DOCKER_IMAGE ?? "node:20-slim",
     };
 }

package/dist/git-worktree.cjs

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitWorktree = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const sandbox_cjs_1 = require("./sandbox.cjs");
+const repositoryLocks = new Map();
+/**
+ * Maintains one bare repository cache per project and checks out each session
+ * into its own uniquely named worktree. The cache avoids N full clones while
+ * git's worktree metadata keeps concurrent agents from sharing an index or
+ * working directory.
+ */
+class GitWorktree {
+    sessionRoot;
+    worktreePath;
+    repositoryPath;
+    branch;
+    runner;
+    cloneUrl;
+    githubToken;
+    constructor(options) {
+        const projectKey = safePathSegment(options.projectId);
+        const sessionKey = safePathSegment(options.sessionId);
+        this.sessionRoot = node_path_1.default.join(options.workspaceRoot, "sessions", sessionKey);
+        this.worktreePath = node_path_1.default.join(this.sessionRoot, "repo");
+        this.repositoryPath = node_path_1.default.join(options.workspaceRoot, "repositories", `${projectKey}.git`);
+        this.branch = `navarch/${safePathSegment(options.taskId).slice(0, 32)}-${sessionKey.slice(0, 12)}`;
+        this.runner = options.runner ?? sandbox_cjs_1.nodeCommandRunner;
+        this.cloneUrl = options.cloneUrl;
+        this.githubToken = options.githubToken;
+    }
+    async prepare() {
+        await node_fs_1.promises.mkdir(node_path_1.default.dirname(this.repositoryPath), { recursive: true });
+        await node_fs_1.promises.mkdir(this.sessionRoot, { recursive: true });
+        await withRepositoryLock(this.repositoryPath, async () => {
+            if (!(await pathExists(node_path_1.default.join(this.repositoryPath, "HEAD")))) {
+                await this.runGit(["clone", "--bare", this.cloneUrl, this.repositoryPath], true);
+            }
+            else {
+                const origin = await this.runGit(["--git-dir", this.repositoryPath, "remote", "get-url", "origin"], false);
+                if (normalizeCloneUrl(origin.stdout) !== normalizeCloneUrl(this.cloneUrl)) {
+                    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";
+            await this.runGit([
+                "--git-dir",
+                this.repositoryPath,
+                "fetch",
+                "--prune",
+                "origin",
+                "+refs/heads/*:refs/heads/*",
+            ], true);
+            await this.runGit([
+                "--git-dir",
+                this.repositoryPath,
+                "worktree",
+                "add",
+                "-b",
+                this.branch,
+                this.worktreePath,
+                startRef,
+            ], false);
+        });
+    }
+    async cleanup() {
+        await withRepositoryLock(this.repositoryPath, async () => {
+            await this.runner
+                .run("git", ["--git-dir", this.repositoryPath, "worktree", "remove", "--force", this.worktreePath])
+                .catch(() => undefined);
+            await this.runner
+                .run("git", ["--git-dir", this.repositoryPath, "branch", "-D", this.branch])
+                .catch(() => undefined);
+            await this.runner
+                .run("git", ["--git-dir", this.repositoryPath, "worktree", "prune"])
+                .catch(() => undefined);
+        });
+    }
+    async runGit(args, authenticated) {
+        const credentialArgs = authenticated && this.githubToken
+            ? [
+                "-c",
+                'credential.helper=!f() { echo username=x-access-token; echo "password=$GITHUB_TOKEN"; }; f',
+            ]
+            : [];
+        const result = await this.runner.run("git", [...credentialArgs, ...args], {
+            env: this.githubToken
+                ? { ...process.env, GITHUB_TOKEN: this.githubToken, GIT_TERMINAL_PROMPT: "0" }
+                : { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        });
+        if (result.code !== 0) {
+            throw new Error(`git ${args[0] ?? "command"} failed: ${result.stderr || result.stdout}`);
+        }
+        return result;
+    }
+}
+exports.GitWorktree = GitWorktree;
+async function withRepositoryLock(key, work) {
+    const previous = repositoryLocks.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    const queued = previous.then(() => current);
+    repositoryLocks.set(key, queued);
+    await previous;
+    try {
+        return await work();
+    }
+    finally {
+        release();
+        if (repositoryLocks.get(key) === queued)
+            repositoryLocks.delete(key);
+    }
+}
+async function pathExists(value) {
+    try {
+        await node_fs_1.promises.access(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safePathSegment(value) {
+    const safe = value.replace(/[^A-Za-z0-9_.-]/g, "-").replace(/^-+|-+$/g, "");
+    if (!safe)
+        throw new Error("Cannot create a git worktree without a valid project/session identifier.");
+    return safe;
+}
+function normalizeCloneUrl(value) {
+    return value.trim().replace(/\.git$/, "").replace(/\/+$/, "").toLowerCase();
+}
+function parseRemoteHead(output) {
+    const match = output.match(/^ref:\s+(refs\/heads\/[A-Za-z0-9._/-]+)\s+HEAD$/m);
+    return match?.[1] ?? null;
+}

package/dist/machine-store.cjs

@@ -40,19 +40,22 @@ 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,
+            agent_type: process.env.NAVARCH_AGENT === "codex" || process.env.NAVARCH_AGENT === "claude-code"
+                ? process.env.NAVARCH_AGENT
+                : undefined,
         };
     }
     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,9 +9,20 @@ exports.renderPrompt = renderPrompt;
  * WP-07 "write prompt file".
  */
 function renderPrompt(task, bundle) {
+    if (bundle.task_context) {
+        const repositoryContext = bundle.repository
+            ? `Repository: ${bundle.repository.full_name} (${bundle.repository.url})\nLocal checkout: this session's isolated git worktree (current working directory).`
+            : null;
+        return [repositoryContext, 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}`);
+    if (bundle.repository) {
+        sections.push(`Repository URL: ${bundle.repository.url}\nLocal checkout: this session's isolated git worktree (current working directory).`);
+    }
     if (task.github_issue_url) {
         sections.push(`GitHub issue: ${task.github_issue_url}`);
     }

package/dist/sandbox.cjs

@@ -15,7 +15,7 @@ exports.SandboxUnavailableError = SandboxUnavailableError;
 exports.nodeCommandRunner = {
     run(cmd, args, opts = {}) {
         return new Promise((resolve, reject) => {
-            const child = (0, node_child_process_1.spawn)(cmd, args, { cwd: opts.cwd });
+            const child = (0, node_child_process_1.spawn)(cmd, args, { cwd: opts.cwd, env: opts.env });
             let stdout = "";
             let stderr = "";
             let settled = false;
@@ -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:
@@ -91,14 +91,27 @@ class DockerSandbox {
     runner;
     workDir;
     image;
+    containerWorkDir;
+    sharedGitDir;
     constructor(opts) {
         this.name = containerName(opts.sessionId);
         this.runner = opts.runner ?? exports.nodeCommandRunner;
         this.workDir = node_path_1.default.join(opts.workspaceRoot, opts.sessionId);
         this.image = opts.image;
+        this.containerWorkDir = opts.containerWorkDir ?? null;
+        this.sharedGitDir = opts.sharedGitDir ?? null;
     }
     async create() {
         await node_fs_1.promises.mkdir(this.workDir, { recursive: true });
+        const mounts = this.containerWorkDir
+            ? [
+                "-v",
+                `${this.workDir}:${this.workDir}`,
+                ...(this.sharedGitDir ? ["-v", `${this.sharedGitDir}:${this.sharedGitDir}`] : []),
+                "-w",
+                this.containerWorkDir,
+            ]
+            : ["-v", `${this.workDir}:/workspace`, "-w", "/workspace"];
         const result = await this.runner.run("docker", [
             "run",
             "-d",
@@ -110,10 +123,7 @@ class DockerSandbox {
             "/tmp",
             "--tmpfs",
             "/run",
-            "-v",
-            `${this.workDir}:/workspace`,
-            "-w",
-            "/workspace",
+            ...mounts,
             this.image,
             "tail",
             "-f",
@@ -156,9 +166,13 @@ class DockerSandbox {
     }
     /** Force-removes the container and the host-side workspace mount. Best-effort: never throws. */
     async wipe() {
-        await this.runner.run("docker", ["rm", "-f", this.name]).catch(() => undefined);
+        await this.stop();
         await node_fs_1.promises.rm(this.workDir, { recursive: true, force: true }).catch(() => undefined);
     }
+    /** Stops/removes only the container; the session orchestrator owns worktree cleanup. */
+    async stop() {
+        await this.runner.run("docker", ["rm", "-f", this.name]).catch(() => undefined);
+    }
 }
 exports.DockerSandbox = DockerSandbox;
 function shellQuote(value) {

package/dist/session.cjs

@@ -14,26 +14,27 @@ const upload_cjs_1 = require("./upload.cjs");
 const prompt_cjs_1 = require("./prompt.cjs");
 const mcp_config_cjs_1 = require("./mcp-config.cjs");
 const logger_cjs_1 = require("./logger.cjs");
-/** Filename the generated platform MCP config is written under, inside the session's workDir (host-side; also /workspace inside the Docker sandbox -- see sandbox.cts's bind mount). */
+const git_worktree_cjs_1 = require("./git-worktree.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");
 /**
  * Runs one claimed task end to end (implementation-plan.md WP-07):
  *   1. write the prompt file
  *   2. fetch secrets from the broker once, at session start
- *   3. stand up a Docker sandbox, clone the repo, inject env vars
+ *   3. optionally stand up a Docker sandbox when explicitly configured
  *   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)
  *   6. wipe the sandbox unconditionally
  *
- * NEEDS LIVE VERIFICATION: the full path requires a real Docker daemon, a
- * real `claude` (or `codex`) binary, and a live control-plane API — none of
- * which are available in this offline build environment. Unit tests exercise
- * each collaborator (api.cts, sandbox.cts, exit-conditions.cts, redact.cts,
- * adapters/*.cts) in isolation instead; see runtime/README.md.
+ * NEEDS LIVE VERIFICATION: the full path requires a real `claude` (or
+ * `codex`) binary and a live control-plane API; Docker-backed execution also
+ * requires a real Docker daemon. Unit tests exercise each collaborator
+ * (api.cts, sandbox.cts, exit-conditions.cts, redact.cts, adapters/*.cts) in
+ * isolation instead; see runtime/README.md.
  */
 async function runSession(deps, claimed, sessionId) {
     const { api, config } = deps;
@@ -41,7 +42,7 @@ async function runSession(deps, claimed, sessionId) {
     // 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.
-    const workDir = node_path_1.default.join(config.workspaceRoot, sessionId);
+    const workDir = node_path_1.default.join(config.workspaceRoot, "sessions", sessionId);
     await node_fs_1.promises.mkdir(workDir, { recursive: true });
     const promptText = (0, prompt_cjs_1.renderPrompt)(task, bundle);
     await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), promptText, "utf8");
@@ -56,6 +57,31 @@ async function runSession(deps, claimed, sessionId) {
         secrets = issued.secrets;
         registry.registerAll(secrets);
     }
+    const cloneUrl = bundle.repository?.clone_url ??
+        (task.repo ? `https://github.com/${task.repo.replace(/\.git$/, "")}.git` : null);
+    if (!cloneUrl) {
+        const failureSummary = `Project ${task.project_id} has no GitHub repository URL. Set it in Project settings before dispatching work.`;
+        await api.completeLease(leaseId, {
+            status: "failed",
+            report: failureSummary,
+            failure_summary: failureSummary,
+            evidence_urls: [],
+            cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
+            exit_status: "crashed",
+            agent_type: config.agentType,
+        });
+        secrets = {};
+        await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+        return;
+    }
+    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"],
+    });
     const abortController = new AbortController();
     let leaseLost = false;
     const heartbeatTimer = setInterval(() => {
@@ -73,25 +99,34 @@ async function runSession(deps, claimed, sessionId) {
             .completeLease(leaseId, {
             status: "failed",
             report: "Docker sandbox unavailable on this machine.",
+            failure_summary: "Docker sandbox unavailable on this machine.",
             evidence_urls: [],
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
             agent_type: config.agentType,
         })
             .catch((err) => log.warn(`complete() after docker-unavailable also failed: ${String(err)}`));
+        secrets = {};
+        await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
         return;
     }
     const sandbox = dockerAvailable
-        ? new sandbox_cjs_1.DockerSandbox({ sessionId, workspaceRoot: config.workspaceRoot, image: config.dockerImage })
+        ? new sandbox_cjs_1.DockerSandbox({
+            sessionId,
+            workspaceRoot: node_path_1.default.join(config.workspaceRoot, "sessions"),
+            image: config.dockerImage,
+            containerWorkDir: gitWorktree.worktreePath,
+            sharedGitDir: gitWorktree.repositoryPath,
+        })
         : null;
     // 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) --
+    // workDir (host path), which Docker mode mounts at that same absolute path
+    // so worktree .git pointers and this config path remain valid --
     // the selected adapter (adapters/claude.cts or adapters/codex.cts) needs a
     // path valid in whichever environment it actually runs.
     let mcpConfigPath = config.mcpConfigPath;
@@ -102,15 +137,15 @@ async function runSession(deps, claimed, sessionId) {
             leaseId,
         });
         await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, MCP_CONFIG_FILENAME), JSON.stringify(mcpConfig, null, 2), "utf8");
-        mcpConfigPath = sandbox ? `/workspace/${MCP_CONFIG_FILENAME}` : node_path_1.default.join(workDir, MCP_CONFIG_FILENAME);
+        mcpConfigPath = node_path_1.default.join(workDir, MCP_CONFIG_FILENAME);
     }
     try {
+        await gitWorktree.prepare();
         if (sandbox) {
             await sandbox.create();
             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
@@ -124,8 +159,8 @@ async function runSession(deps, claimed, sessionId) {
             bin,
             extraArgs,
             timeoutMs: config.sessionTimeoutMs,
-            env: secrets,
-            cwd: sandbox ? undefined : workDir,
+            env: toEnvMap(secrets),
+            cwd: sandbox ? undefined : gitWorktree.worktreePath,
             dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
             signal: abortController.signal,
         });
@@ -164,10 +199,12 @@ async function runSession(deps, claimed, sessionId) {
     }
     catch (err) {
         log.error(`session ${leaseId} threw before completing: ${String(err)}`);
+        const failureSummary = (0, redact_cjs_1.redactText)(`Session crashed: ${String(err)}`, registry.list());
         await api
             .completeLease(leaseId, {
             status: "failed",
-            report: (0, redact_cjs_1.redactText)(`Session crashed: ${String(err)}`, registry.list()),
+            report: failureSummary,
+            failure_summary: failureSummary,
             evidence_urls: [],
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
@@ -179,7 +216,8 @@ async function runSession(deps, claimed, sessionId) {
         clearInterval(heartbeatTimer);
         secrets = {};
         if (sandbox)
-            await sandbox.wipe();
+            await sandbox.stop();
+        await gitWorktree.cleanup();
         await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
     }
 }
@@ -191,6 +229,14 @@ function toEnvMap(secrets) {
     }
     if (secrets["github-pat"] && !out.GITHUB_TOKEN) {
         out.GITHUB_TOKEN = secrets["github-pat"];
+        // Make ordinary `git push` calls from the agent use the in-memory token.
+        // The helper contains only an env-var reference; the token itself never
+        // lands in argv, git config, or the worktree.
+        out.GIT_CONFIG_COUNT = "1";
+        out.GIT_CONFIG_KEY_0 = "credential.helper";
+        out.GIT_CONFIG_VALUE_0 =
+            '!f() { echo username=x-access-token; echo "password=$GITHUB_TOKEN"; }; f';
+        out.GIT_TERMINAL_PROMPT = "0";
     }
     return out;
 }

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,7 +1,7 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.0",
-  "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.",
+  "version": "0.1.2",
+  "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",
   "repository": {
@@ -45,6 +45,6 @@
   "devDependencies": {
     "@types/node": "^20.14.0",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.10"
   }
 }