@sagentlab/navarch-runtime 0.1.5 → 0.1.7

package/README.md

@@ -24,7 +24,7 @@ git clone <this repo> && cd sagentlab/runtime
 ./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
+node bin/navarch.cjs supervise
 ```
 
 Or, once dependencies are installed:
@@ -32,7 +32,7 @@ Or, once dependencies are installed:
 ```sh
 npm run build
 NAVARCH_API_BASE=https://navarch.example.com npm run register -- --token <enrollment-token> --name my-machine-1
-npm start
+npm run supervise
 ```
 
 `register` is the one command that prints the machine's auth token — exactly
@@ -61,7 +61,7 @@ project only (it will never be dispatched work from any other project).
 ```sh
 npx @sagentlab/navarch-runtime connect --token flmt_<...> --project <project-id> \
     --name my-agent-1 --agent codex --api-base https://navarch.example.com
-node bin/navarch.cjs start
+npx @sagentlab/navarch-runtime supervise
 ```
 
 (`@sagentlab/navarch-runtime` is published to npm, so `npx
@@ -76,6 +76,7 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 | `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. |
+| `supervise [--agent claude-code\|codex]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
 | `doctor` | Prints resolved config + Docker/registration status; no side effects. |
 
 ## Active-task guidance
@@ -102,13 +103,49 @@ The daemon logs `restarting the agent turn in the same worktree` when it
 delivers guidance. Lowering the lease-heartbeat interval makes guidance arrive
 sooner, but keep it comfortably below the 15-minute lease TTL.
 
-## Safely upgrading and restarting the daemon
-
-The daemon does not currently drain sessions during shutdown: `SIGINT` or
-`SIGTERM` stops new claims and heartbeats, then exits immediately. Stopping it
-with an active session can interrupt the agent before it reports completion;
-the control plane must then wait for the lease to expire and requeue the task.
-Do not use an ordinary daemon restart as a way to deliver guidance.
+## Automatic and manual runtime upgrades
+
+Run long-lived agents with `navarch-runtime supervise`. The worker advertises
+its package version and updater protocol on each machine heartbeat. When the
+control plane assigns an eligible release, it:
+
+1. Downloads the exact `@sagentlab/navarch-runtime@<version>` tarball with npm
+   lifecycle scripts disabled and verifies the control-plane-recorded SHA-512
+   integrity.
+2. Stages it under `$NAVARCH_CONFIG_DIR/versions/<version>` while existing
+   sessions continue.
+3. Stops claiming, reports zero available capacity, and waits for both an
+   in-flight claim and every active session to finish.
+4. Atomically writes `pending-update.json` and exits with the supervisor-only
+   handoff code. The supervisor starts the staged binary with the same config
+   directory and machine identity.
+5. Commits the activation after the replacement completes its first successful
+   heartbeat, persisting `active-runtime.json` so machine restarts keep using
+   the verified release. A crash or two-minute health timeout before then
+   restores the previous binary.
+
+The control plane never supplies a package name, URL, path, or shell command:
+only an exact semver and npm SHA-512 integrity for the fixed package name are
+accepted. Rollouts are assigned by the machine's server-managed `stable` or
+`canary` channel and deterministic rollout percentage. Set
+`NAVARCH_AUTO_UPDATE=off` to keep telemetry but disable automatic activation.
+
+Plain `navarch-runtime start` continues to work and reports available releases,
+but deliberately does not activate them because no parent process would exist
+to perform a safe handoff or rollback.
+
+After publishing a runtime, an operator records the immutable npm metadata in
+`runtime_releases`. Obtain the integrity with
+`npm view @sagentlab/navarch-runtime@<version> dist.integrity`, then insert the
+exact version, returned integrity, release channel, and desired rollout
+percentage. Start with `channel='canary'` or a small `rollout_percent`; raising
+the percentage keeps existing machines in the same deterministic cohort.
+
+### Manual fallback
+
+`SIGINT` or `SIGTERM` now stops new claims and drains active sessions before
+exiting. A second signal forces an immediate exit and can interrupt work, so use
+it only when abandoning the active leases is intentional.
 
 Use this sequence for an upgrade:
 
@@ -158,11 +195,68 @@ unchanged across the deployment.
 | `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_UPDATE_CHANNEL` | `stable` | Release channel advertised by the worker (`stable` or `canary`); the server-managed machine channel remains authoritative. |
+| `NAVARCH_AUTO_UPDATE` | on under `supervise` | Set `off`, `false`, or `0` to report releases without staging or activating them. Automatic activation is always off under plain `start`. |
 | `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_CLAUDE_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `--mcp-config` (Claude Code). `--allowedTools`/`--disallowedTools` layer rules onto auto mode; an explicit `--permission-mode`, `--permission-prompt-tool`, or bypass flag replaces the unattended default `--permission-mode auto`. |
 | `NAVARCH_CODEX_BIN` | `codex` | Path/name of the Codex CLI binary. |
 | `NAVARCH_CODEX_EXTRA_ARGS` | — | Comma list of extra CLI args appended after the generated MCP `-c` overrides and `--json` (Codex). |
 | `NAVARCH_MCP_CONFIG_PATH` | — | Path to the platform MCP config passed as `--mcp-config`. |
+| `NAVARCH_WORKTREE_GUARD` | on | Host-mode Claude and Codex sessions get a per-session worktree boundary guard (see below). Set `off` to disable. |
+| `NAVARCH_GUARD_EXTRA_ROOTS` | — | `path.delimiter`-separated (`:` on POSIX) extra directories the worktree guard allows beyond the session worktree, shared bare repo, and temp dirs. |
+
+## Worktree boundary guard (host mode)
+
+A machine typically runs several sessions concurrently (`NAVARCH_MAX_SESSIONS`),
+each in its own git worktree. The runtime enforces the same boundary for both
+supported coding agents, using each CLI's native enforcement point:
+
+- **Claude Code:** the runtime uses `--permission-mode auto`, which sends
+  approval decisions through Claude Code's background safety classifier. It
+  does not blanket-preapprove the lease-scoped Navarch MCP tools. A generated
+  settings file (`src/worktree-guard.cts`, passed as `--settings`) also installs
+  `bin/worktree-guard-hook.cjs` as a fail-closed `PreToolUse` boundary hook.
+- **Codex:** the runtime passes a one-off native permission profile with
+  `approval_policy="on-request"` and `approvals_reviewer="auto_review"`.
+  Codex's OS sandbox grants read/write access only to the allowed roots and
+  denies the surrounding multi-session workspace, while eligible escalations
+  are decided by the automatic reviewer rather than waiting for human input.
+  `--ignore-user-config` and an untrusted project-config override prevent a
+  user or checked-in legacy `sandbox_mode` from silently disabling the
+  generated profile; Codex authentication still comes from `CODEX_HOME`, and
+  repository instructions such as `AGENTS.md` still load.
+
+The resulting boundary is:
+
+- **File tools** (`Read`/`Write`/`Edit`/`Glob`/`Grep`/...) may only touch the
+  session worktree, the project's shared bare repo, temp dirs, and any
+  `NAVARCH_GUARD_EXTRA_ROOTS`. Read-only tools may additionally read standard
+  system prefixes (`/usr`, `/etc`, ...). Symlinks are resolved before the
+  containment check.
+- **Bash commands** are screened lexically: absolute, `~`/`$HOME`, and
+  `..`-traversal path references must land inside the allowed roots or the
+  system prefixes.
+- The **rest of the workspace root** — sibling sessions' worktrees, other
+  projects' bare repos, and the session's own metadata dir (lease-scoped MCP
+  config, the guard files themselves) — is denied outright, so an agent can
+  neither read another agent's checkout nor rewrite its own guard policy.
+
+The Claude hook is a strong guardrail rather than a hard security boundary
+because shell paths are screened lexically. Codex's permission profile is
+enforced by its OS sandbox. For container-grade whole-process isolation use
+`NAVARCH_SANDBOX_MODE=docker`; neither host guard is installed in Docker mode.
+An operator-supplied `--settings` in `NAVARCH_CLAUDE_EXTRA_ARGS`, or an
+explicit Codex permission/sandbox option in `NAVARCH_CODEX_EXTRA_ARGS`, takes
+precedence over the generated policy.
+
+Claude auto mode requires Claude Code 2.1.83 or later and an eligible account,
+model, and first-party Anthropic API provider. If those requirements are not
+met, Claude Code rejects auto mode instead of silently bypassing checks.
+
+The auto-review launch paths were verified live on 2026-07-20 with Claude Code
+2.1.214 (`--permission-mode auto`) and Codex CLI 0.144.1 (the generated
+permission profile plus `approvals_reviewer="auto_review"`). Both completed an
+unattended smoke task successfully.
 
 ## Choosing an agent (Claude Code vs. Codex)
 
@@ -213,7 +307,7 @@ envelope as a compatibility fallback.
 cli.cts
  ├─ register            → api.registerMachine()      → machine-store.cts (writes machine.json once)
  ├─ connect             → api.connectMachine()       → machine-store.cts (writes machine.json once)
- └─ start
+ ├─ start
      ├─ 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:
@@ -232,6 +326,10 @@ cli.cts
                6. api.completeLease(), reporting agent_type: config.agentType
                7. sandbox.wipe() when present; remove the session workspace
                   unconditionally (finally block)
+ └─ supervise                  → supervisor.cts starts the worker with IPC
+      └─ update directive      → update-installer.cts stages exact npm release
+           └─ drain + exit 75  → supervisor activates candidate, waits for
+                                 healthy heartbeat, or rolls back
 ```
 
 `adapter.cts` (top-level) is now a backward-compat re-export of
@@ -298,6 +396,12 @@ tests cover:
 - `adapters/codex.cts` — arg construction on both the host path (mocked `spawn`)
   and the docker-exec path (fake `CommandRunner`), and usage/report-text
   attachment from fixed JSONL fixtures (`tests/adapters/codex.test.cts`).
+- `worktree-guard.cts` + `bin/worktree-guard-hook.cjs` — generated settings/
+  config shape, native Codex permission-profile construction, and the hook's
+  containment verdicts (in-worktree vs. sibling session vs. home dir, symlink
+  escapes, Bash path screening, the fail-closed exit-2 protocol run as a real
+  subprocess) (`tests/worktree-guard.test.cts`,
+  `tests/worktree-guard-hook.test.cts`).
 
 Not exercised by unit tests, and needing a real machine per the WP-07 DoD
 ("on a real machine: register → claim a seeded docs task → session runs

package/bin/worktree-guard-hook.cjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Navarch worktree guard — the PreToolUse hook installed by
+ * src/worktree-guard.cts into every host-mode Claude Code session.
+ *
+ * Multiple sessions run concurrently on one machine (claim-loop.cts), each
+ * confined by convention to its own git worktree
+ * (`<workspaceRoot>/sessions/<sessionId>/repo` — git-worktree.cts). The
+ * adapter launches Claude in auto permission mode (adapters/claude.cts).
+ * Claude Code runs PreToolUse hooks in every permission mode, so this script
+ * is the enforcement point that keeps an agent from reading or writing
+ * another session's worktree, the operator's home directory, or anything
+ * else unrelated to its task.
+ *
+ * Protocol (Claude Code hooks): the hook receives {tool_name, tool_input,
+ * cwd, ...} as JSON on stdin. Exit 0 allows the tool call; exit 2 blocks it
+ * and feeds stderr back to the model as the reason. Any internal failure
+ * exits 2 as well — a safety harness must fail closed.
+ *
+ * Policy:
+ *  - File tools (Read/Write/Edit/...) may only touch the allowed roots (the
+ *    session worktree, the project's shared bare repo, temp dirs, plus any
+ *    NAVARCH_GUARD_EXTRA_ROOTS). Read-only tools may additionally read
+ *    standard system prefixes (/usr, /etc, ...) so toolchains keep working.
+ *  - Bash commands are screened lexically: absolute, `~`/$HOME, and
+ *    `..`-traversal path references must land inside the allowed roots or
+ *    the system prefixes. This cannot catch every obfuscated escape (shell
+ *    is Turing-complete) — it is a strong guardrail, not a security
+ *    boundary. Operators needing a hard boundary should use
+ *    NAVARCH_SANDBOX_MODE=docker (sandbox.cts).
+ *  - Symlinks are resolved (realpath of the longest existing prefix) before
+ *    the containment check, so `ln -s $HOME escape` doesn't work either.
+ *
+ * This file is plain CommonJS (not .cts) on purpose: it must be runnable by
+ * a bare `node` from both the published package (dist has compiled .cjs
+ * next to bin/) and the source tree (vitest imports it directly), without
+ * depending on the TypeScript build. Node stdlib only.
+ */
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+/**
+ * Prefixes shell commands may reference freely (and read-only file tools may
+ * read): OS/toolchain locations plus shared temp. Everything here is either
+ * world-readable system state or scratch space that no Navarch session owns.
+ * Deliberately absent: /Users, /home, /root, /var (beyond tmp), and the
+ * workspace root — those are exactly what the guard exists to protect.
+ */
+const DEFAULT_SYSTEM_PREFIXES = [
+  "/bin",
+  "/sbin",
+  "/usr",
+  "/lib",
+  "/lib32",
+  "/lib64",
+  "/libx32",
+  "/opt",
+  "/etc",
+  "/private/etc",
+  "/dev",
+  "/proc",
+  "/sys",
+  "/run",
+  // Deliberately NOT the whole /System: /System/Volumes/Data firmlinks the
+  // entire macOS data volume (including /Users), which would be an escape.
+  "/System/Library",
+  "/System/Applications",
+  "/Applications",
+  "/Library/Developer",
+  "/tmp",
+  "/private/tmp",
+  "/var/tmp",
+  "/var/folders",
+  "/private/var/folders",
+  "/nix",
+  "/snap",
+];
+
+/** Path-carrying input fields per guarded file tool (Claude Code tool schemas). */
+const FILE_TOOL_PATH_FIELDS = {
+  Read: ["file_path"],
+  Write: ["file_path"],
+  Edit: ["file_path"],
+  MultiEdit: ["file_path"],
+  NotebookEdit: ["notebook_path"],
+  Glob: ["path"],
+  Grep: ["path"],
+  LS: ["path"],
+};
+
+/** File tools that only read — these may also touch the system prefixes. */
+const READ_ONLY_FILE_TOOLS = new Set(["Read", "Glob", "Grep", "LS"]);
+
+/**
+ * Loads the per-session guard config written by src/worktree-guard.cts:
+ * `{ allowedRoots: string[], deniedRoots?: string[], systemPrefixes?:
+ * string[] }`. Temp roots are appended here (not persisted) so the config
+ * stays portable across OSes.
+ *
+ * Precedence (checkPath below): allowedRoots (this session's own dirs) win,
+ * then deniedRoots (the whole multi-session workspace root — so sibling
+ * sessions and other projects' bare repos stay off-limits even when the
+ * workspace happens to live under a temp or system prefix), then the broad
+ * temp/system allowances.
+ */
+function loadGuardConfig(configPath) {
+  const raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  if (!raw || !Array.isArray(raw.allowedRoots) || raw.allowedRoots.length === 0) {
+    throw new Error(`guard config ${configPath} does not declare allowedRoots`);
+  }
+  const canonicalize = (root) => resolveWithRealpath(path.resolve(root));
+  return {
+    allowedRoots: [...new Set(raw.allowedRoots.map(canonicalize))],
+    deniedRoots: [...new Set((raw.deniedRoots ?? []).map(canonicalize))],
+    tempRoots: [...new Set([os.tmpdir(), "/tmp", "/var/tmp"].map(canonicalize))],
+    systemPrefixes:
+      Array.isArray(raw.systemPrefixes) && raw.systemPrefixes.length > 0
+        ? raw.systemPrefixes
+        : DEFAULT_SYSTEM_PREFIXES,
+  };
+}
+
+/**
+ * Containment verdict for one canonicalized absolute path.
+ * `allowSystemPrefixes` is true for read-only file tools and for Bash (whose
+ * commands must keep reaching toolchains under /usr, /etc, ...).
+ */
+function checkPath(resolved, config, allowSystemPrefixes) {
+  if (config.allowedRoots.some((root) => isWithin(root, resolved))) return true;
+  if (config.deniedRoots.some((root) => isWithin(root, resolved))) return false;
+  if (config.tempRoots.some((root) => isWithin(root, resolved))) return true;
+  if (allowSystemPrefixes && config.systemPrefixes.some((root) => isWithin(root, resolved))) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Canonicalizes an absolute path: realpath of the longest existing ancestor
+ * with the non-existent tail re-appended. Resolving through the existing
+ * portion is what defeats symlink escapes; keeping the tail lets the guard
+ * judge not-yet-created files (Write) by where they would actually land.
+ */
+function resolveWithRealpath(absolutePath) {
+  let current = path.normalize(absolutePath);
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync(current);
+      return tail.length > 0 ? path.join(real, ...tail.reverse()) : real;
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return path.normalize(absolutePath);
+      tail.push(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+function isWithin(root, candidate) {
+  return candidate === root || candidate.startsWith(root + path.sep);
+}
+
+/** Expands leading `~`, `~/`, `$HOME`, and `${HOME}` to the real home directory. */
+function expandHome(value) {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
+  if (/^\$\{?HOME\}?($|\/)/.test(value)) return value.replace(/^\$\{?HOME\}?/, os.homedir());
+  return value;
+}
+
+/**
+ * Pulls path-like references out of a shell command: absolute paths,
+ * home-anchored paths (`~...`, `$HOME/...`), and relative `..` traversals.
+ * Lexical by design — see the file header for why this is a guardrail, not
+ * a parser. URLs survive untouched (the char before `//` in `https://` is
+ * `:`, which is not a path delimiter here).
+ */
+function extractBashPathCandidates(command) {
+  const candidates = [];
+  const seen = new Set();
+  const add = (raw) => {
+    const cleaned = raw.replace(/[)\]}"'`,]+$/, "");
+    if (!cleaned || seen.has(cleaned)) return;
+    seen.add(cleaned);
+    candidates.push(cleaned);
+  };
+
+  const absoluteRe = /(?:^|[\s'"`=(<>;|&])(\/[^\s'"`<>;|&)]*)/g;
+  const homeRe = /(?:^|[\s'"`=(<>;|&])((?:~|\$\{?HOME\}?)[^\s'"`<>;|&)]*)/g;
+  let match;
+  while ((match = absoluteRe.exec(command))) add(match[1]);
+  while ((match = homeRe.exec(command))) add(match[1]);
+
+  for (const token of command.split(/[\s'"`;|&<>()]+/)) {
+    if (!token || token.startsWith("-") || token.startsWith("/") || token.startsWith("~")) continue;
+    if (token === ".." || token.startsWith("../") || token.includes("/../") || token.endsWith("/..")) {
+      add(token);
+    }
+  }
+  return candidates;
+}
+
+function denyMessage(toolName, rawPath, resolvedPath, config) {
+  const resolvedNote =
+    resolvedPath && resolvedPath !== rawPath ? ` (resolves to "${resolvedPath}")` : "";
+  return (
+    `Navarch worktree guard blocked this ${toolName} call: "${rawPath}"${resolvedNote} is outside ` +
+    `this session's workspace. This machine runs multiple isolated agent sessions; work only under: ` +
+    `${config.allowedRoots.join(", ")}. Standard system paths (/usr, /etc, /tmp, ...) stay available ` +
+    `to shell commands. Do not attempt to bypass this boundary — if the task genuinely requires that ` +
+    `path, state the limitation in your report instead.`
+  );
+}
+
+/** Screens one Bash command. Returns {allowed} or {allowed:false, reason}. */
+function evaluateBashCommand(command, cwd, config) {
+  // A bare `cd` (or `cd -`) jumps to $HOME / an unknowable previous
+  // directory — both outside the worktree by construction.
+  for (const segment of command.split(/[;&|]+/)) {
+    const trimmed = segment.trim();
+    if (trimmed === "cd" || trimmed === "cd -") {
+      return { allowed: false, reason: denyMessage("Bash", trimmed, os.homedir(), config) };
+    }
+  }
+
+  for (const raw of extractBashPathCandidates(command)) {
+    // `~otheruser/...` — another account's home; nothing there is in scope.
+    if (/^~[^/]/.test(raw)) {
+      return { allowed: false, reason: denyMessage("Bash", raw, "", config) };
+    }
+    const resolved = resolveWithRealpath(path.resolve(cwd, expandHome(raw)));
+    if (!checkPath(resolved, config, true)) {
+      return { allowed: false, reason: denyMessage("Bash", raw, resolved, config) };
+    }
+  }
+  return { allowed: true };
+}
+
+/**
+ * Evaluates one PreToolUse payload. Guarded file tools and Bash are checked;
+ * every other tool (MCP platform tools, WebFetch, Task, ...) is allowed —
+ * the settings matcher (src/worktree-guard.cts) shouldn't even route them
+ * here, so this is belt-and-braces.
+ */
+function evaluateToolUse(input, config) {
+  const toolName = typeof input.tool_name === "string" ? input.tool_name : "";
+  const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+  const toolInput = input.tool_input && typeof input.tool_input === "object" ? input.tool_input : {};
+
+  const pathFields = FILE_TOOL_PATH_FIELDS[toolName];
+  if (pathFields) {
+    const candidates = [];
+    for (const field of pathFields) {
+      const value = toolInput[field];
+      if (typeof value === "string" && value) candidates.push(value);
+    }
+    // No explicit path (e.g. Glob/Grep default to cwd): judge cwd itself.
+    if (candidates.length === 0) candidates.push(cwd);
+
+    for (const candidate of candidates) {
+      const resolved = resolveWithRealpath(path.resolve(cwd, expandHome(candidate)));
+      if (!checkPath(resolved, config, READ_ONLY_FILE_TOOLS.has(toolName))) {
+        return { allowed: false, reason: denyMessage(toolName, candidate, resolved, config) };
+      }
+    }
+    return { allowed: true };
+  }
+
+  if (toolName === "Bash") {
+    const command = toolInput.command;
+    if (typeof command !== "string" || !command) return { allowed: true };
+    return evaluateBashCommand(command, cwd, config);
+  }
+
+  return { allowed: true };
+}
+
+function main() {
+  try {
+    const configPath = process.argv[2];
+    if (!configPath) throw new Error("usage: worktree-guard-hook.cjs <guard-config.json>");
+    const config = loadGuardConfig(configPath);
+    const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+    const verdict = evaluateToolUse(input, config);
+    if (verdict.allowed) process.exit(0);
+    process.stderr.write(verdict.reason);
+    process.exit(2);
+  } catch (err) {
+    // Fail closed: a guard that cannot evaluate must not wave the call through.
+    process.stderr.write(`Navarch worktree guard failed closed: ${String(err)}`);
+    process.exit(2);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  DEFAULT_SYSTEM_PREFIXES,
+  evaluateBashCommand,
+  evaluateToolUse,
+  expandHome,
+  extractBashPathCandidates,
+  isWithin,
+  loadGuardConfig,
+  resolveWithRealpath,
+};

package/dist/adapters/claude.cjs

@@ -4,17 +4,6 @@ exports.claudeCodeAdapter = void 0;
 exports.runClaudeCodeAdapter = runClaudeCodeAdapter;
 const node_child_process_1 = require("node:child_process");
 const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
-const NAVARCH_MCP_ALLOWED_TOOLS = [
-    "mcp__navarch__task_comment",
-    "mcp__navarch__record_decision",
-    "mcp__navarch__request_approval",
-    "mcp__navarch__register_resource",
-    "mcp__navarch__create_task",
-    "mcp__navarch__list_triage_tasks",
-    "mcp__navarch__groom_triage_task",
-    "mcp__navarch__defer_triage_task",
-    "mcp__navarch__file_pr_review",
-];
 /**
  * Headless Claude Code adapter (project-plan.md §3.9 / implementation-plan.md
  * WP-07): `claude -p "<context bundle>" --mcp-config platform-mcp.json
@@ -37,16 +26,28 @@ const NAVARCH_MCP_ALLOWED_TOOLS = [
  */
 async function runClaudeCodeAdapter(options) {
     const args = ["-p", options.prompt];
+    const hasExplicitPermissionMode = options.extraArgs.some((arg) => ["--permission-mode", "--permission-prompt-tool", "--dangerously-skip-permissions"].some((flag) => arg === flag || arg.startsWith(`${flag}=`)));
+    // Navarch sessions are unattended, so route permission decisions through
+    // Claude Code's native auto-mode classifier instead of prompting a human or
+    // bypassing checks. Operators can replace this with a different permission
+    // policy through NAVARCH_CLAUDE_EXTRA_ARGS.
+    if (!hasExplicitPermissionMode) {
+        args.push("--permission-mode", "auto");
+    }
+    // The worktree-guard settings file (worktree-guard.cts) installs the
+    // PreToolUse boundary hook. Hooks run in auto mode, so this remains a
+    // fail-closed boundary around each worktree on a machine running several
+    // agents. An operator-supplied --settings (via
+    // NAVARCH_CLAUDE_EXTRA_ARGS) wins — two --settings flags on one invocation
+    // would be ambiguous, and session.cts logs the guard as skipped.
+    if (options.settingsPath && !options.extraArgs.includes("--settings")) {
+        args.push("--settings", options.settingsPath);
+    }
     if (options.mcpConfigPath) {
         args.push("--mcp-config", options.mcpConfigPath);
-        // Headless Claude cannot pause for an interactive permission prompt. The
-        // Navarch server already scopes every call to the authenticated lease and
-        // enforces task/project authorization, so pre-approve exactly its known
-        // tools instead of bypassing Claude permissions globally.
-        if (!options.extraArgs.includes("--allowedTools") &&
-            !options.extraArgs.includes("--allowed-tools")) {
-            args.push("--allowedTools", NAVARCH_MCP_ALLOWED_TOOLS.join(","));
-        }
+        // Do not blanket-preapprove Navarch MCP tools: auto mode should review
+        // their side effects too. Operators can still add an explicit
+        // --allowedTools policy through NAVARCH_CLAUDE_EXTRA_ARGS.
     }
     // Only append the default when the caller hasn't already asked for a
     // specific --output-format (extraArgs wins so an operator can opt back

package/dist/adapters/codex.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.codexAdapter = void 0;
 exports.runCodexAdapter = runCodexAdapter;
+exports.hasExplicitPermissionPolicy = hasExplicitPermissionPolicy;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
@@ -29,16 +30,13 @@ const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
  *   per-session JSON is translated into one-off `-c mcp_servers.*` overrides.
  *   Authentication and custom-header values are passed through environment
  *   variables so machine/lease credentials never appear in argv.
- * - Sandboxing/approvals: a real `codex exec` may prompt for
- *   approval/sandbox-escalation on some actions by default; because this
- *   runtime already isolates the session in its own Docker container (or,
- *   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 NAVARCH_CODEX_EXTRA_ARGS until confirmed.
+ * - Host-mode sessions use a generated native Codex permission profile that
+ *   denies reads and writes outside the session worktree, shared Git dir,
+ *   temp dirs, and operator-approved extra roots. Interactive approval
+ *   requests use `approval_policy="on-request"` with the native automatic
+ *   reviewer, so unattended sessions retain safety review without waiting for
+ *   human input. Explicit permission-policy arguments in
+ *   NAVARCH_CODEX_EXTRA_ARGS replace that generated profile.
  * - `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
@@ -52,6 +50,9 @@ async function runCodexAdapter(options) {
     if (!options.extraArgs.includes("--json")) {
         args.push("--json");
     }
+    if (options.codexGuardArgs && !hasExplicitPermissionPolicy(options.extraArgs)) {
+        args.push(...options.codexGuardArgs);
+    }
     args.push(...options.extraArgs);
     if (options.model)
         args.push("--model", options.model);
@@ -64,6 +65,36 @@ async function runCodexAdapter(options) {
         : await runOnHost(runOptions, args);
     return attachUsage(raw);
 }
+/** Operator policy wins over Navarch's generated host-mode profile. */
+function hasExplicitPermissionPolicy(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if ([
+            "--sandbox",
+            "-s",
+            "--dangerously-bypass-approvals-and-sandbox",
+            "--profile",
+            "-p",
+            "--ignore-user-config",
+        ].includes(arg) ||
+            arg.startsWith("--sandbox=") ||
+            arg.startsWith("-s=")) {
+            return true;
+        }
+        if (arg === "-c" || arg === "--config") {
+            const override = args[index + 1] ?? "";
+            if (/^(sandbox_mode|default_permissions|permissions)(\.|=)/.test(override))
+                return true;
+            index += 1;
+        }
+        else if (arg.startsWith("--config=")) {
+            const override = arg.slice("--config=".length);
+            if (/^(sandbox_mode|default_permissions|permissions)(\.|=)/.test(override))
+                return true;
+        }
+    }
+    return false;
+}
 /** Convert Claude's per-session MCP JSON into Codex one-off TOML overrides. */
 async function codexMcpArgs(path, env) {
     const parsed = JSON.parse(await node_fs_1.promises.readFile(path, "utf8"));

package/dist/capacity.cjs

@@ -14,6 +14,7 @@ function computeAvailableCapacity(maxSessions, activeSessions) {
 class CapacityTracker {
     maxSessions;
     active = new Set();
+    idleWaiters = new Set();
     constructor(maxSessions) {
         this.maxSessions = maxSessions;
     }
@@ -36,6 +37,17 @@ class CapacityTracker {
     }
     release(sessionId) {
         this.active.delete(sessionId);
+        if (this.active.size === 0) {
+            for (const resolve of this.idleWaiters)
+                resolve();
+            this.idleWaiters.clear();
+        }
+    }
+    /** Resolves once every acquired lease has finished and released its slot. */
+    waitForIdle() {
+        if (this.active.size === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => this.idleWaiters.add(resolve));
     }
 }
 exports.CapacityTracker = CapacityTracker;