@sagentlab/navarch-runtime 0.1.12 → 0.1.14

package/README.md

@@ -252,15 +252,17 @@ unchanged across the deployment.
 | `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_WORKTREE_CLEANUP_INTERVAL_MS` | `3600000` (1 hour) | How often the runtime scans for session worktrees abandoned by a hard exit or host restart. |
+| `NAVARCH_WORKTREE_STALE_AFTER_MS` | `86400000` (24 hours) | Minimum inactivity age before an abandoned session worktree is removed. Active sessions are always protected. |
 | `NAVARCH_GIT_AUTHOR_NAME` / `NAVARCH_GIT_AUTHOR_EMAIL` | `sagentlab` / `z@sagentlab.com` | Git identity forced into session commits so host-level personal config is not inherited; override both for a project-authorized bot. |
 | `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. The image must contain the selected agent CLI, Git, Node.js 20+, and project build/test tools; the default is only a low-level runtime fallback and is not sufficient for BYO-key sandbox sessions ([issue #229](https://github.com/sagentlab/navarch/issues/229)). |
+| `NAVARCH_DOCKER_IMAGE` | `ghcr.io/sagentlab/navarch-sandbox-agent:0.1.0` | Version-pinned per-session image with Node 20, git, GitHub CLI, ripgrep, jq, SSH, and Claude Code 2.1.218. Override with an image tag or digest you control. |
 | `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent CLI: `claude-code`, `codex`, or `gemini`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
 | `NAVARCH_RUNTIMES` | selected `NAVARCH_AGENT` | Comma list of installed/authenticated adapters advertised to dispatch. The control plane chooses among these per project/task. |
 | `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). `--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_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`. Runtime sessions default to an empty `--setting-sources` list so machine/user/project hooks cannot leak into temporary checkouts. The generated host-mode settings retain only the user-level `apiKeyHelper` needed for authentication; supply `--setting-sources=<sources>` here to opt into other settings deliberately. |
 | `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_GEMINI_BIN` | `gemini` | Path/name of the Google Gemini CLI binary. |
@@ -280,6 +282,10 @@ supported coding agents, using each CLI's native enforcement point:
   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.
+  User, project, and local settings sources are disabled by default, preventing
+  host-only hooks and plugins from leaking into unattended sessions; the
+  explicit generated settings file remains active and carries forward only a
+  user-level `apiKeyHelper` when the machine uses one for authentication.
 - **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

package/dist/adapter-capacity.cjs

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectAdapterCapacityLimit = detectAdapterCapacityLimit;
+const exit_conditions_cjs_1 = require("./exit-conditions.cjs");
+const DEFAULT_CAPACITY_COOLDOWN_MS = 15 * 60 * 1000;
+const RESET_GRACE_MS = 30 * 1000;
+const MAX_RESET_SEARCH_MINUTES = 48 * 60;
+/**
+ * Detects a provider-side capacity response that applies beyond one task
+ * lease. Claude Code reports account session exhaustion as a successful CLI
+ * process containing a structured 429 result, so process exit status alone
+ * cannot distinguish it from an ordinary failed task.
+ */
+function detectAdapterCapacityLimit(result, nowMs = Date.now()) {
+    const parsed = (0, exit_conditions_cjs_1.parseClaudeJsonResult)(result.stdout) ??
+        (0, exit_conditions_cjs_1.parseClaudeJsonResult)(result.stderr);
+    if (parsed?.api_error_status !== 429)
+        return null;
+    const detail = parsed.result ?? "";
+    if (!/\b(?:session|usage|rate)\s+limit\b|\btoo many requests\b/i.test(detail)) {
+        return null;
+    }
+    return {
+        retryAtMs: parseResetTime(detail, nowMs) ??
+            nowMs + DEFAULT_CAPACITY_COOLDOWN_MS,
+    };
+}
+/**
+ * Resolves messages such as "resets 9:50pm (America/New_York)" without
+ * assuming the runtime host uses the provider's timezone. Searching minute
+ * boundaries also handles UTC offsets and daylight-saving transitions using
+ * the platform's IANA timezone database.
+ */
+function parseResetTime(detail, nowMs) {
+    const match = detail.match(/\bresets?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)\s*\(([^)]+)\)/i);
+    if (!match)
+        return null;
+    const hour12 = Number(match[1]);
+    const minute = Number(match[2] ?? "0");
+    const meridiem = match[3]?.toLowerCase();
+    const timeZone = match[4]?.trim();
+    if (!Number.isInteger(hour12) ||
+        hour12 < 1 ||
+        hour12 > 12 ||
+        !Number.isInteger(minute) ||
+        minute < 0 ||
+        minute > 59 ||
+        !timeZone) {
+        return null;
+    }
+    const targetHour = hour12 % 12 + (meridiem === "pm" ? 12 : 0);
+    let formatter;
+    try {
+        formatter = new Intl.DateTimeFormat("en-US", {
+            timeZone,
+            hour: "2-digit",
+            minute: "2-digit",
+            hourCycle: "h23",
+        });
+    }
+    catch {
+        return null;
+    }
+    const firstMinuteMs = Math.ceil((nowMs + 1) / 60_000) * 60_000;
+    for (let offset = 0; offset < MAX_RESET_SEARCH_MINUTES; offset += 1) {
+        const candidateMs = firstMinuteMs + offset * 60_000;
+        const parts = formatter.formatToParts(new Date(candidateMs));
+        const hour = Number(parts.find((part) => part.type === "hour")?.value);
+        const candidateMinute = Number(parts.find((part) => part.type === "minute")?.value);
+        if (hour === targetHour && candidateMinute === minute) {
+            return candidateMs + RESET_GRACE_MS;
+        }
+    }
+    return null;
+}

package/dist/adapters/claude.cjs

@@ -26,7 +26,22 @@ const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
  */
 async function runClaudeCodeAdapter(options) {
     const args = ["-p", options.prompt];
+    const hasSettingSources = options.extraArgs.some((arg) => arg === "--setting-sources" || arg.startsWith("--setting-sources="));
     const hasExplicitPermissionMode = options.extraArgs.some((arg) => ["--permission-mode", "--permission-prompt-tool", "--dangerously-skip-permissions"].some((flag) => arg === flag || arg.startsWith(`${flag}=`)));
+    // Runtime sessions must not inherit an operator's personal or project-local
+    // Claude hooks. Apart from making execution machine-dependent, those hooks
+    // commonly reference helper files through CLAUDE_PROJECT_DIR; that variable
+    // points at the temporary session checkout, where a host-only helper does
+    // not exist, and a failing SessionEnd hook turns an otherwise successful
+    // task into an adapter failure.
+    //
+    // An empty source list disables user/project/local settings while preserving
+    // the explicit --settings file below ("flagSettings" in Claude Code), so the
+    // generated worktree-guard hook remains active. Operators can deliberately
+    // opt sources back in through NAVARCH_CLAUDE_EXTRA_ARGS.
+    if (!hasSettingSources) {
+        args.push("--setting-sources", "");
+    }
     // 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

package/dist/adapters/codex.cjs

@@ -149,8 +149,10 @@ function attachUsage(result) {
     const reportText = (0, exit_conditions_cjs_1.extractFinalMessageFromCodexEvents)(events) ?? undefined;
     return {
         ...result,
-        tokensIn: usage.tokensIn,
-        tokensOut: usage.tokensOut,
+        // A run killed before its first usage event has unknown usage, not a
+        // measured zero — leave the fields unset so aggregation skips them.
+        ...(usage.tokensIn !== undefined ? { tokensIn: usage.tokensIn } : {}),
+        ...(usage.tokensOut !== undefined ? { tokensOut: usage.tokensOut } : {}),
         ...(usage.costUsd !== undefined ? { costUsd: usage.costUsd } : {}),
         ...(reportText !== undefined ? { reportText } : {}),
     };

package/dist/claim-loop.cjs

@@ -23,6 +23,7 @@ class ClaimLoop {
     claimInFlight = false;
     consecutiveFailures = 0;
     nextClaimAt = 0;
+    capacityCooldownUntil = 0;
     quiescenceWaiters = new Set();
     constructor(api, config, capacity, runSession) {
         this.api = api;
@@ -60,7 +61,7 @@ class ClaimLoop {
         if (this.stopped ||
             this.claimInFlight ||
             !this.capacity.hasCapacity() ||
-            Date.now() < this.nextClaimAt)
+            Date.now() < Math.max(this.nextClaimAt, this.capacityCooldownUntil))
             return;
         this.claimInFlight = true;
         try {
@@ -85,6 +86,13 @@ class ClaimLoop {
             this.capacity.acquire(claimed.lease_id);
             log.info(`claimed task ${claimed.task.id} (${claimed.task.task_type}) as lease ${claimed.lease_id}, session ${sessionId}`);
             this.runSession(claimed, sessionId)
+                .then((outcome) => {
+                const cooldownUntil = outcome?.claimCooldownUntil;
+                if (!cooldownUntil || cooldownUntil <= Date.now())
+                    return;
+                this.capacityCooldownUntil = Math.max(this.capacityCooldownUntil, cooldownUntil);
+                log.warn(`adapter capacity exhausted; pausing new claims until ${new Date(this.capacityCooldownUntil).toISOString()}`);
+            })
                 .catch((err) => log.error(`session ${sessionId} failed: ${String(err)}`))
                 .finally(() => this.capacity.release(claimed.lease_id));
         }

package/dist/cli.cjs

@@ -17,6 +17,7 @@ const sandbox_cjs_1 = require("./sandbox.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const update_coordinator_cjs_1 = require("./update-coordinator.cjs");
 const supervisor_cjs_1 = require("./supervisor.cjs");
+const worktree_janitor_cjs_1 = require("./worktree-janitor.cjs");
 const log = (0, logger_cjs_1.createLogger)("cli");
 const PACKAGE_NAME = "@sagentlab/navarch-runtime";
 /** Include a control-plane response's safe error detail in top-level CLI failures. */
@@ -191,7 +192,18 @@ async function startCommand(flags) {
     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 claimLoop = new claim_loop_cjs_1.ClaimLoop(api, config, capacity, (claimed, sessionId) => (0, session_cjs_1.runSession)({ api, config }, claimed, sessionId));
+    const activeSessionIds = new Set();
+    const worktreeJanitor = new worktree_janitor_cjs_1.WorktreeJanitor({
+        workspaceRoot: config.workspaceRoot,
+        intervalMs: config.worktreeCleanupIntervalMs,
+        staleAfterMs: config.worktreeStaleAfterMs,
+        isSessionActive: (sessionId) => activeSessionIds.has(sessionId),
+    });
+    const claimLoop = new claim_loop_cjs_1.ClaimLoop(api, config, capacity, (claimed, sessionId) => {
+        activeSessionIds.add(sessionId);
+        return (0, session_cjs_1.runSession)({ api, config }, claimed, sessionId)
+            .finally(() => activeSessionIds.delete(sessionId));
+    });
     const bootId = (0, node_crypto_1.randomUUID)();
     const updateCoordinatorRef = {};
     let readySent = false;
@@ -208,6 +220,7 @@ async function startCommand(flags) {
         heartbeat,
     });
     heartbeat.start();
+    worktreeJanitor.start();
     claimLoop.start();
     log.info(`navarch-runtime started: machine=${identity.name} agent=${config.agentType} max_sessions=${config.maxSessions} api_base=${identity.api_base}`);
     let shuttingDown = false;
@@ -222,6 +235,7 @@ async function startCommand(flags) {
             heartbeat.setUpdateState("draining");
             await claimLoop.drain();
             await capacity.waitForIdle();
+            worktreeJanitor.stop();
             heartbeat.stop();
             log.info("shutdown drain complete");
             process.exit(0);

package/dist/config.cjs

@@ -3,10 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SANDBOX_IMAGE = void 0;
 exports.isRuntimeAgentType = isRuntimeAgentType;
 exports.loadRuntimeConfig = loadRuntimeConfig;
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+/** Published image containing git, GitHub CLI, and the pinned Claude Code CLI. */
+exports.DEFAULT_SANDBOX_IMAGE = "ghcr.io/sagentlab/navarch-sandbox-agent:0.1.0";
 function isRuntimeAgentType(value) {
     return value === "claude-code" || value === "codex" || value === "gemini";
 }
@@ -54,6 +57,8 @@ function loadRuntimeConfig(env = process.env) {
         // interval must stay comfortably under that TTL.
         leaseHeartbeatIntervalMs,
         sessionTimeoutMs: envInt(env, "NAVARCH_SESSION_TIMEOUT_MS", 45 * 60 * 1000),
+        worktreeCleanupIntervalMs: envInt(env, "NAVARCH_WORKTREE_CLEANUP_INTERVAL_MS", 60 * 60 * 1000),
+        worktreeStaleAfterMs: envInt(env, "NAVARCH_WORKTREE_STALE_AFTER_MS", 24 * 60 * 60 * 1000),
         agentType,
         runtimes: runtimes.length > 0 ? runtimes : [agentType],
         claudeBin: env.NAVARCH_CLAUDE_BIN ?? "claude",
@@ -66,7 +71,7 @@ function loadRuntimeConfig(env = process.env) {
         gitAuthorEmail: env.NAVARCH_GIT_AUTHOR_EMAIL ?? "z@sagentlab.com",
         mcpConfigPath: env.NAVARCH_MCP_CONFIG_PATH ?? null,
         sandboxMode,
-        dockerImage: env.NAVARCH_DOCKER_IMAGE ?? "node:20-slim",
+        dockerImage: env.NAVARCH_DOCKER_IMAGE ?? exports.DEFAULT_SANDBOX_IMAGE,
         // Multiple sessions share one machine; keeping each agent inside its own
         // worktree is the safe default, so disabling is the explicit opt-out.
         worktreeGuard: !["off", "false", "0"].includes(env.NAVARCH_WORKTREE_GUARD ?? ""),

package/dist/exit-conditions.cjs

@@ -89,34 +89,48 @@ function parseCodexJsonEvents(stdout) {
     return events;
 }
 /**
- * Extracts token/cost usage from parsed `codex exec --json` events. The last
- * `turn.completed` event wins. Legacy `token_count` events remain supported.
+ * Extracts token/cost usage from parsed `codex exec --json` events.
+ *
+ * `turn.completed.usage` is per-turn (each turn reports only its own tokens),
+ * so multi-turn runs sum every turn's usage — keeping only the last event
+ * would under-report all earlier turns. Legacy `token_count` envelopes carry
+ * cumulative session totals instead, so for those the last event wins; they
+ * are only used when no verified `turn.completed` usage was seen.
+ *
+ * When no usage-bearing event is present at all (e.g. the run was killed
+ * before its first `turn.completed`), every field stays undefined so callers
+ * report usage as unknown rather than a fabricated measured zero.
  */
 function extractUsageFromCodexEvents(events) {
-    let tokensIn = 0;
-    let tokensOut = 0;
+    let turnTokensIn = 0;
+    let turnTokensOut = 0;
+    let sawTurnUsage = false;
+    let legacyTokensIn;
+    let legacyTokensOut;
     let costUsd;
     for (const event of events) {
         if (event.type === "turn.completed" && event.usage) {
-            tokensIn = event.usage.input_tokens ?? 0;
-            tokensOut = event.usage.output_tokens ?? 0;
-            if (typeof event.usage.total_cost_usd === "number")
-                costUsd = event.usage.total_cost_usd;
+            sawTurnUsage = true;
+            turnTokensIn += event.usage.input_tokens ?? 0;
+            turnTokensOut += event.usage.output_tokens ?? 0;
+            if (typeof event.usage.total_cost_usd === "number") {
+                costUsd = (costUsd ?? 0) + event.usage.total_cost_usd;
+            }
         }
         if (event.msg?.type === "token_count") {
             const nested = event.msg.info?.total_token_usage;
-            tokensIn = nested
+            legacyTokensIn = nested
                 ? (nested.input_tokens ?? 0)
                 : (event.msg.input_tokens ?? 0) + (event.msg.cached_input_tokens ?? 0);
-            tokensOut = nested?.output_tokens ?? event.msg.output_tokens ?? 0;
+            legacyTokensOut = nested?.output_tokens ?? event.msg.output_tokens ?? 0;
             if (typeof nested?.total_cost_usd === "number")
                 costUsd = nested.total_cost_usd;
         }
         if (event.type === "event_msg" && event.payload?.type === "token_count") {
             const total = event.payload.info?.total_token_usage;
             if (total) {
-                tokensIn = total.input_tokens ?? 0;
-                tokensOut = total.output_tokens ?? 0;
+                legacyTokensIn = total.input_tokens ?? 0;
+                legacyTokensOut = total.output_tokens ?? 0;
                 if (typeof total.total_cost_usd === "number")
                     costUsd = total.total_cost_usd;
             }
@@ -125,7 +139,9 @@ function extractUsageFromCodexEvents(events) {
             costUsd = event.msg.total_cost_usd;
         }
     }
-    return { tokensIn, tokensOut, costUsd };
+    if (sawTurnUsage)
+        return { tokensIn: turnTokensIn, tokensOut: turnTokensOut, costUsd };
+    return { tokensIn: legacyTokensIn, tokensOut: legacyTokensOut, costUsd };
 }
 /** The last completed agent message, with legacy `msg.agent_message` fallback. */
 function extractFinalMessageFromCodexEvents(events) {
@@ -187,10 +203,26 @@ function mapExitCondition(result) {
         };
     }
     if (result.exitCode !== 0) {
+        // Claude Code returns provider/auth failures as a structured JSON result
+        // on stdout while exiting non-zero. Prefer its human-readable `result`
+        // field over the raw metrics envelope (or incidental stderr warnings).
+        return {
+            leaseOutcome: "failed",
+            exitStatus: "failed",
+            reportSummary: summarize(parsedJson?.result || result.stderr || result.stdout) ||
+                `Adapter exited with code ${result.exitCode}.`,
+            evidenceUrls,
+        };
+    }
+    // Some Claude Code releases exit 0 even when their structured result says
+    // the provider rejected the turn (for example a session-limit 429). Never
+    // report those synthetic zero-token turns as completed work.
+    if (parsedJson?.is_error) {
         return {
             leaseOutcome: "failed",
             exitStatus: "failed",
-            reportSummary: summarize(result.stderr || result.stdout) || `Adapter exited with code ${result.exitCode}.`,
+            reportSummary: summarize(parsedJson.result || result.stderr || result.stdout) ||
+                "Claude Code reported an unsuccessful result.",
             evidenceUrls,
         };
     }

package/dist/session.cjs

@@ -17,8 +17,10 @@ const prompt_cjs_1 = require("./prompt.cjs");
 const mcp_config_cjs_1 = require("./mcp-config.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const git_worktree_cjs_1 = require("./git-worktree.cjs");
+const worktree_janitor_cjs_1 = require("./worktree-janitor.cjs");
 const github_pr_cjs_1 = require("./github-pr.cjs");
 const worktree_guard_cjs_1 = require("./worktree-guard.cjs");
+const adapter_capacity_cjs_1 = require("./adapter-capacity.cjs");
 /** Filename the generated platform MCP config is written under inside the session metadata directory. */
 const MCP_CONFIG_FILENAME = "mcp-config.json";
 const GIT_CREDENTIAL_HELPER_FILENAME = "git-credential-navarch.cjs";
@@ -66,6 +68,7 @@ async function runSession(deps, claimed, sessionId) {
     // (heartbeat/complete/issue/transcript) still key on leaseId.
     const workDir = node_path_1.default.join(config.workspaceRoot, "sessions", sessionId);
     await node_fs_1.promises.mkdir(workDir, { recursive: true });
+    await (0, worktree_janitor_cjs_1.markSessionWorkspaceActive)(workDir);
     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");
     // Secrets: initially fetched once, held only in memory (registry + env map below),
@@ -129,12 +132,14 @@ async function runSession(deps, claimed, sessionId) {
     let leaseLost = false;
     let leaseGone = false;
     let heartbeatInFlight = null;
+    const sessionOutcome = {};
     const pollLease = () => {
         if (heartbeatInFlight)
             return heartbeatInFlight;
         const request = api
             .heartbeatLease(leaseId, { guidance_after: guidanceCursor })
-            .then((heartbeat) => {
+            .then(async (heartbeat) => {
+            await (0, worktree_janitor_cjs_1.markSessionWorkspaceActive)(workDir);
             guidanceCursor = heartbeat.guidance_cursor ?? guidanceCursor;
             const fresh = (heartbeat.guidance ?? []).filter((entry) => {
                 if (knownGuidanceIds.has(entry.id))
@@ -302,6 +307,10 @@ async function runSession(deps, claimed, sessionId) {
             });
             activeAbortController = null;
             attempts.push(turnResult);
+            const capacityLimit = (0, adapter_capacity_cjs_1.detectAdapterCapacityLimit)(turnResult);
+            if (capacityLimit) {
+                sessionOutcome.claimCooldownUntil = Math.max(sessionOutcome.claimCooldownUntil ?? 0, capacityLimit.retryAtMs);
+            }
             // Close the small race between a naturally completed turn and the next
             // scheduled heartbeat. If guidance landed, run another turn before the
             // lease can be completed. A terminal heartbeat response means the
@@ -311,7 +320,7 @@ async function runSession(deps, claimed, sessionId) {
                 await pollLease();
             if (leaseGone) {
                 log.warn(`session ${leaseId} stopped without completion because its lease is no longer active.`);
-                return;
+                return sessionOutcome;
             }
             if (!leaseLost && pendingGuidance.length > 0)
                 continue;
@@ -383,7 +392,7 @@ async function runSession(deps, claimed, sessionId) {
             catch (err) {
                 if (isAlreadyReleasedCompletionError(err)) {
                     log.warn(`completion skipped for ${leaseId}: the lease was already released.`);
-                    return;
+                    return sessionOutcome;
                 }
                 const rejection = mapping.leaseOutcome === "completed" ? completionRemediationMessage(err) : null;
                 if (!rejection)
@@ -432,6 +441,7 @@ async function runSession(deps, claimed, sessionId) {
         await gitWorktree.cleanup();
         await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
     }
+    return sessionOutcome;
 }
 function adapterCommand(config, runtime) {
     switch (runtime) {

package/dist/worktree-guard.cjs

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.guardHookScriptPath = guardHookScriptPath;
+exports.readClaudeApiKeyHelper = readClaudeApiKeyHelper;
 exports.prepareWorktreeGuard = prepareWorktreeGuard;
 exports.codexToolReadRoots = codexToolReadRoots;
 exports.codexWorktreeGuardArgs = codexWorktreeGuardArgs;
@@ -12,6 +13,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = require("node:fs");
 const node_os_1 = __importDefault(require("node:os"));
 const CODEX_GUARD_PROFILE = "navarch-worktree";
+const CLAUDE_USER_SETTINGS_FILENAME = "settings.json";
 /**
  * Tools the hook screens. Everything else — the lease-scoped Navarch MCP
  * tools, WebFetch, Task, ... — carries no direct filesystem path and passes
@@ -26,6 +28,37 @@ const GUARDED_TOOL_MATCHER = "^(Read|Write|Edit|MultiEdit|NotebookEdit|Glob|Grep
 function guardHookScriptPath() {
     return node_path_1.default.join(__dirname, "..", "bin", "worktree-guard-hook.cjs");
 }
+/**
+ * Preserve Claude's authentication helper without inheriting the rest of the
+ * operator's user settings. Runtime sessions deliberately disable the normal
+ * user/project/local setting sources, but apiKeyHelper is a supported auth
+ * source and some unattended machines have no keychain/OAuth fallback.
+ *
+ * Invalid or missing user settings degrade to no helper, matching Claude
+ * print mode's tolerant treatment of invalid settings files.
+ */
+async function readClaudeApiKeyHelper(settingsPath = defaultClaudeUserSettingsPath()) {
+    if (!settingsPath)
+        return undefined;
+    try {
+        const parsed = JSON.parse(await node_fs_1.promises.readFile(settingsPath, "utf8"));
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            !Array.isArray(parsed) &&
+            typeof parsed.apiKeyHelper === "string") {
+            const helper = parsed.apiKeyHelper.trim();
+            return helper || undefined;
+        }
+    }
+    catch {
+        // Missing/invalid user settings are not a runtime startup failure.
+    }
+    return undefined;
+}
+function defaultClaudeUserSettingsPath() {
+    const configDir = process.env.CLAUDE_CONFIG_DIR?.trim() || node_path_1.default.join(node_os_1.default.homedir(), ".claude");
+    return node_path_1.default.join(configDir, CLAUDE_USER_SETTINGS_FILENAME);
+}
 /**
  * Writes the per-session guard config + Claude settings file into workDir and
  * returns their paths. The settings file is passed to the CLI as `--settings`
@@ -45,7 +78,11 @@ async function prepareWorktreeGuard(options) {
     // process.execPath rather than a bare `node`: the hook must run with the
     // same interpreter as the runtime regardless of the agent's PATH.
     const command = [process.execPath, hookScriptPath, configPath].map(shellQuote).join(" ");
+    const apiKeyHelper = await readClaudeApiKeyHelper(options.claudeUserSettingsPath === undefined
+        ? defaultClaudeUserSettingsPath()
+        : options.claudeUserSettingsPath);
     const settings = {
+        ...(apiKeyHelper ? { apiKeyHelper } : {}),
         hooks: {
             PreToolUse: [
                 {

package/dist/worktree-janitor.cjs

@@ -0,0 +1,173 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorktreeJanitor = exports.SESSION_ACTIVITY_FILENAME = void 0;
+exports.markSessionWorkspaceActive = markSessionWorkspaceActive;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const logger_cjs_1 = require("./logger.cjs");
+const sandbox_cjs_1 = require("./sandbox.cjs");
+const log = (0, logger_cjs_1.createLogger)("worktree-janitor");
+exports.SESSION_ACTIVITY_FILENAME = ".navarch-active";
+/**
+ * Refreshes the durable activity marker used by janitors in other runtime
+ * processes that happen to share a workspace root.
+ */
+async function markSessionWorkspaceActive(sessionRoot) {
+    await node_fs_1.promises.mkdir(sessionRoot, { recursive: true });
+    await node_fs_1.promises.writeFile(node_path_1.default.join(sessionRoot, exports.SESSION_ACTIVITY_FILENAME), `${new Date().toISOString()}\n`, "utf8");
+}
+/**
+ * Periodically removes session worktrees left behind by SIGKILL, a host
+ * restart, or another exit that bypassed runSession's finally block.
+ *
+ * The age threshold is deliberately conservative. A directory must be both
+ * absent from this process's active-session registry and stale on disk before
+ * it is eligible. Git worktree metadata is removed before the directory.
+ */
+class WorktreeJanitor {
+    options;
+    runner;
+    now;
+    timer = null;
+    sweepInFlight = null;
+    constructor(options) {
+        this.options = options;
+        this.runner = options.runner ?? sandbox_cjs_1.nodeCommandRunner;
+        this.now = options.now ?? Date.now;
+    }
+    start() {
+        if (this.timer)
+            return;
+        void this.sweepAndLog();
+        this.timer = setInterval(() => void this.sweepAndLog(), this.options.intervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    sweep() {
+        if (this.sweepInFlight)
+            return this.sweepInFlight;
+        this.sweepInFlight = this.runSweep().finally(() => {
+            this.sweepInFlight = null;
+        });
+        return this.sweepInFlight;
+    }
+    async sweepAndLog() {
+        try {
+            const summary = await this.sweep();
+            if (summary.removed > 0 || summary.errors > 0) {
+                log.info(`cleanup complete: scanned=${summary.scanned} removed=${summary.removed} ` +
+                    `active=${summary.skippedActive} fresh=${summary.skippedFresh} errors=${summary.errors}`);
+            }
+        }
+        catch (error) {
+            log.warn(`cleanup sweep failed: ${String(error)}`);
+        }
+    }
+    async runSweep() {
+        const summary = {
+            scanned: 0,
+            removed: 0,
+            skippedActive: 0,
+            skippedFresh: 0,
+            errors: 0,
+        };
+        const sessionsRoot = node_path_1.default.resolve(this.options.workspaceRoot, "sessions");
+        const entries = await node_fs_1.promises.readdir(sessionsRoot, { withFileTypes: true }).catch((error) => {
+            if (isMissing(error))
+                return [];
+            throw error;
+        });
+        for (const entry of entries) {
+            // Do not follow symlinks placed in the sessions directory.
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            summary.scanned += 1;
+            const sessionId = entry.name;
+            const sessionRoot = node_path_1.default.resolve(sessionsRoot, sessionId);
+            if (node_path_1.default.dirname(sessionRoot) !== sessionsRoot) {
+                summary.errors += 1;
+                continue;
+            }
+            if (this.options.isSessionActive?.(sessionId)) {
+                summary.skippedActive += 1;
+                continue;
+            }
+            try {
+                const lastActivity = await this.lastActivityAt(sessionRoot);
+                if (this.now() - lastActivity < this.options.staleAfterMs) {
+                    summary.skippedFresh += 1;
+                    continue;
+                }
+                // Close the in-process race with a session claim that started while
+                // this directory was being inspected.
+                if (this.options.isSessionActive?.(sessionId)) {
+                    summary.skippedActive += 1;
+                    continue;
+                }
+                await this.removeSessionWorktree(sessionRoot);
+                summary.removed += 1;
+            }
+            catch (error) {
+                summary.errors += 1;
+                log.warn(`could not clean abandoned session ${sessionId}: ${String(error)}`);
+            }
+        }
+        return summary;
+    }
+    async lastActivityAt(sessionRoot) {
+        const marker = node_path_1.default.join(sessionRoot, exports.SESSION_ACTIVITY_FILENAME);
+        try {
+            return (await node_fs_1.promises.stat(marker)).mtimeMs;
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+            // Compatibility with worktrees created before activity markers existed.
+            return (await node_fs_1.promises.stat(sessionRoot)).mtimeMs;
+        }
+    }
+    async removeSessionWorktree(sessionRoot) {
+        const worktreePath = node_path_1.default.join(sessionRoot, "repo");
+        const branchResult = await this.runner.run("git", ["-C", worktreePath, "symbolic-ref", "--quiet", "--short", "HEAD"]).catch(() => null);
+        const branch = branchResult?.code === 0 ? branchResult.stdout.trim() : "";
+        const repositoriesRoot = node_path_1.default.resolve(this.options.workspaceRoot, "repositories");
+        const repositories = await node_fs_1.promises.readdir(repositoriesRoot, { withFileTypes: true }).catch((error) => {
+            if (isMissing(error))
+                return [];
+            throw error;
+        });
+        for (const repository of repositories) {
+            if (!repository.isDirectory() || repository.isSymbolicLink())
+                continue;
+            const repositoryPath = node_path_1.default.resolve(repositoriesRoot, repository.name);
+            if (node_path_1.default.dirname(repositoryPath) !== repositoriesRoot)
+                continue;
+            const removal = await this.runner.run("git", ["--git-dir", repositoryPath, "worktree", "remove", "--force", worktreePath]).catch(() => null);
+            if (removal?.code === 0 && branch.startsWith("navarch/")) {
+                await this.runner.run("git", ["--git-dir", repositoryPath, "branch", "-D", branch]).catch(() => undefined);
+            }
+        }
+        await node_fs_1.promises.rm(sessionRoot, { recursive: true, force: true });
+        // If worktree removal failed because stale metadata was already damaged,
+        // pruning after the directory disappears still clears the registration.
+        for (const repository of repositories) {
+            if (!repository.isDirectory() || repository.isSymbolicLink())
+                continue;
+            const repositoryPath = node_path_1.default.resolve(repositoriesRoot, repository.name);
+            if (node_path_1.default.dirname(repositoryPath) !== repositoriesRoot)
+                continue;
+            await this.runner.run("git", ["--git-dir", repositoryPath, "worktree", "prune"]).catch(() => undefined);
+        }
+    }
+}
+exports.WorktreeJanitor = WorktreeJanitor;
+function isMissing(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, or Gemini CLI.",
   "type": "commonjs",
   "license": "MIT",