@sagentlab/navarch-runtime 0.1.49 → 0.1.51

package/README.md

@@ -360,6 +360,7 @@ unchanged across the deployment.
 | `NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS` | `300000` | Per-lease heartbeat interval; must stay well under the 60-minute lease TTL (schema-design.md §4). |
 | `NAVARCH_SESSION_TIMEOUT_MS` | `0` (disabled) | Optional absolute runtime budget across agent turns in a claimed session. |
 | `NAVARCH_SESSION_IDLE_TIMEOUT_MS` | `2700000` (45 min) | Stop after a continuously observed window with no stdout/stderr or process-tree CPU activity. `0` disables idle detection. |
+| `NAVARCH_OPENCODE_STARTUP_TIMEOUT_MS` | `120000` (2 min) | Stop OpenCode when it produces no stdout/stderr during startup. This catches provider auth/quota failures that leave its CLI process alive. `0` disables the startup deadline. |
 | `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. |
@@ -837,3 +838,13 @@ Each invocation rebuilds from Git blobs at the requested commit, avoiding stale
 persistent indexes. Bounds are 2,000 files, 10 MB total source, 500 KB per file,
 100 returned nodes and 300 edges. A later persistent index can optimize large
 repositories without changing the query format.
+
+### Pinning a connection model
+
+`connect --agent codex --model gpt-6-astra` saves the model alongside the local
+machine identity. `start` and `supervise` reuse that model, including after worker
+restarts. Their optional `--model` flag overrides the saved choice. The pin wins
+over the project's session model for the selected adapter only; switching agent
+types does not reuse another adapter's pin. Reconnect without `--model` to return
+to project-controlled model selection. Older identities without a model keep
+using the control-plane execution policy.

package/dist/activity-watchdog.cjs

@@ -16,6 +16,7 @@ class ActivityWatchdog {
     stopped = false;
     polling = false;
     pollTimer;
+    startupTimer;
     hardTimer;
     constructor(options) {
         this.options = options;
@@ -24,16 +25,23 @@ class ActivityWatchdog {
         if (options.idleTimeoutMs > 0) {
             this.pollTimer = setInterval(() => void this.poll(), Math.min(30_000, options.idleTimeoutMs / 4));
         }
+        if ((options.startupTimeoutMs ?? 0) > 0) {
+            this.startupTimer = setTimeout(() => this.expire("startup"), options.startupTimeoutMs);
+        }
         if (options.timeoutMs > 0)
             this.armHardLimit();
     }
     activity() {
-        if (!this.stopped)
+        if (!this.stopped) {
             this.lastActivity = this.now();
+            clearTimeout(this.startupTimer);
+            this.startupTimer = undefined;
+        }
     }
     stop() {
         this.stopped = true;
         clearInterval(this.pollTimer);
+        clearTimeout(this.startupTimer);
         clearTimeout(this.hardTimer);
     }
     armHardLimit() {
@@ -61,8 +69,11 @@ class ActivityWatchdog {
                 this.observed = false;
                 return;
             }
+            // Process-tree activity keeps the ordinary idle window alive, but only
+            // actual adapter output proves that a CLI got through startup. Some
+            // providers leave a quiet process behind after an auth/quota failure.
             if (!this.observed || signature !== this.signature)
-                this.activity();
+                this.lastActivity = this.now();
             this.signature = signature;
             this.observed = true;
             if (this.now() - this.lastActivity >= this.options.idleTimeoutMs)
@@ -79,15 +90,15 @@ class ActivityWatchdog {
 }
 exports.ActivityWatchdog = ActivityWatchdog;
 /** No command arguments or environment values are collected from other jobs. */
-async function processActivity(pid, containerName) {
+async function processActivity(pid, containerName, ignoreRootCpu = false) {
     if (!containerName && pid === undefined)
         return null;
     const output = await new Promise((resolve) => {
         (0, node_child_process_1.execFile)(containerName ? "docker" : "ps", containerName ? ["top", containerName, "-eo", "pid=,ppid=,time="] : ["-e", "-o", "pid=,ppid=,time="], { timeout: 5_000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout) => resolve(error ? null : stdout));
     });
-    return output === null ? null : processTreeSignature(output, containerName ? undefined : pid);
+    return output === null ? null : processTreeSignature(output, containerName ? undefined : pid, ignoreRootCpu);
 }
-function processTreeSignature(output, rootPid) {
+function processTreeSignature(output, rootPid, ignoreRootCpu = false) {
     const rows = output.split("\n").flatMap((line) => {
         const match = /^\s*(\d+)\s+(\d+)\s+([\d:.\-]+)\s*$/.exec(line);
         return match ? [{ pid: Number(match[1]), parent: Number(match[2]), cpu: match[3] }] : [];
@@ -106,5 +117,5 @@ function processTreeSignature(output, rootPid) {
         }
     }
     return rows.filter((row) => included.has(row.pid)).sort((a, b) => a.pid - b.pid)
-        .map((row) => `${row.pid}:${row.cpu}`).join(",");
+        .map((row) => `${row.pid}:${ignoreRootCpu && row.pid === rootPid ? "root" : row.cpu}`).join(",");
 }

package/dist/adapter-watchdog.cjs

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runWithActivityWatchdog = runWithActivityWatchdog;
 const activity_watchdog_cjs_1 = require("./activity-watchdog.cjs");
 /** Shared policy for every host/Docker/ACP adapter; adapters still own cancellation. */
-async function runWithActivityWatchdog(adapter, options, idleTimeoutMs) {
+async function runWithActivityWatchdog(adapter, options, idleTimeoutMs, startupTimeoutMs = 0) {
     const controller = new AbortController();
     const onAbort = () => controller.abort();
     options.signal?.addEventListener("abort", onAbort, { once: true });
@@ -13,8 +13,11 @@ async function runWithActivityWatchdog(adapter, options, idleTimeoutMs) {
     let timeoutReason;
     const watchdog = new activity_watchdog_cjs_1.ActivityWatchdog({
         idleTimeoutMs,
+        startupTimeoutMs,
         timeoutMs: options.timeoutMs,
-        probe: () => (0, activity_watchdog_cjs_1.processActivity)(pid, options.dockerExec?.containerName),
+        // OpenCode keeps doing root-process housekeeping after provider failures.
+        // Descendant work and stdout/stderr still count, but that churn does not.
+        probe: () => (0, activity_watchdog_cjs_1.processActivity)(pid, options.dockerExec?.containerName, adapter.agentType === "opencode" && !options.dockerExec),
         onTimeout: (reason) => {
             timeoutReason = reason;
             controller.abort();

package/dist/cli.cjs

@@ -76,6 +76,14 @@ function agentFromFlag(flags) {
     }
     return value;
 }
+/** Saved pins only apply to the adapter they were selected for. */
+function modelFromFlags(flags, agentType, identity) {
+    const model = flags.model ?? (identity?.agent_type === agentType ? identity.model : undefined);
+    if (model !== undefined && (!model.trim() || model === "true" || /\s/.test(model))) {
+        throw new Error("--model requires a non-empty model reference without whitespace.");
+    }
+    return model;
+}
 function parseArgs(argv) {
     const [command, ...rest] = argv;
     const flags = {};
@@ -118,6 +126,7 @@ async function registerCommand(flags) {
         .filter(Boolean);
     const ownerZone = flags["owner-zone"] ?? config.ownerZone;
     const agentType = agentFromFlag(flags) ?? config.agentType;
+    modelFromFlags(flags, agentType); // Validate before consuming an enrollment token.
     const client = new api_cjs_1.NavarchApiClient({ baseUrl: apiBase });
     const result = await client.registerMachine({
         enrollment_token: enrollmentToken,
@@ -132,6 +141,7 @@ async function registerCommand(flags) {
         name,
         api_base: apiBase,
         agent_type: agentType,
+        model: modelFromFlags(flags, agentType),
     });
     // Printed exactly once. Never logged or echoed again after this point.
     console.log("Machine registered.");
@@ -166,6 +176,7 @@ async function connectCommand(flags) {
         .map((s) => s.trim())
         .filter(Boolean);
     const agentType = agentFromFlag(flags) ?? config.agentType;
+    modelFromFlags(flags, agentType); // Validate before consuming an enrollment token.
     const client = new api_cjs_1.NavarchApiClient({ baseUrl: apiBase });
     const result = await client.connectMachine({
         enrollment_token: enrollmentToken,
@@ -180,6 +191,7 @@ async function connectCommand(flags) {
         name,
         api_base: apiBase,
         agent_type: agentType,
+        model: modelFromFlags(flags, agentType),
     });
     // Printed exactly once. Never logged or echoed again after this point.
     console.log("Machine connected.");
@@ -195,9 +207,10 @@ async function startCommand(flags) {
     // 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 config = { ...baseConfig, agentType, model: modelFromFlags(flags, agentType, identity) };
     const api = new api_cjs_1.NavarchApiClient({ baseUrl: identity.api_base, token: identity.token });
     const capacity = new capacity_cjs_1.CapacityTracker(config.maxSessions);
+    const runtimeShutdown = new AbortController();
     const activeSessionIds = new Set();
     const worktreeJanitor = new worktree_janitor_cjs_1.WorktreeJanitor({
         workspaceRoot: config.workspaceRoot,
@@ -207,7 +220,7 @@ async function startCommand(flags) {
     });
     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)
+        return (0, session_cjs_1.runSession)({ api, config, shutdownSignal: runtimeShutdown.signal }, claimed, sessionId)
             .finally(() => activeSessionIds.delete(sessionId));
     });
     const bootId = (0, node_crypto_1.randomUUID)();
@@ -231,8 +244,11 @@ async function startCommand(flags) {
             : `machine credentials for ${identity.name} were rejected by ${identity.api_base}; it can no longer claim tasks.`);
         log.error(`Re-enroll this machine with a fresh "Connect an agent" token, then run ` +
             `\`${superviseInvocation(config.configDir)}\` again.`);
-        // Active sessions keep running to completion; exiting mid-task would
-        // strand a worktree the control plane can no longer hear about either.
+        // Removal/revocation is terminal: stop detached agent process groups so
+        // a provider-side hang cannot keep consuming local resources forever.
+        // runSession checkpoints or retains the worktree before releasing its
+        // capacity slot.
+        runtimeShutdown.abort();
         void capacity.waitForIdle().then(() => process.exit(CREDENTIALS_REJECTED_EXIT_CODE));
     });
     updateCoordinatorRef.current = new update_coordinator_cjs_1.RuntimeUpdateCoordinator({
@@ -277,6 +293,9 @@ async function superviseCommand(flags) {
     const agentType = agentFromFlag(flags) ??
         (process.env.NAVARCH_AGENT ? config.agentType : identity.agent_type ?? config.agentType);
     const workerArgs = ["--agent", agentType];
+    const model = modelFromFlags(flags, agentType, identity);
+    if (model)
+        workerArgs.push("--model", model);
     // Pin the identity for this supervisor's lifetime. Without this snapshot, a
     // replacement worker rereads machine.json after an automatic update and can
     // silently become a different machine if another terminal reused the same
@@ -332,11 +351,11 @@ function helpText() {
 
 Usage:
   navarch-runtime register --token <enrollment-token> --name <machine-name> \\
-      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
+      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--model <model>] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
   navarch-runtime connect --token <enrollment-token> --name <machine-name> \\
-      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
-  navarch-runtime start [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp]
-  navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp]
+      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--model <model>] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
+  navarch-runtime start [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--model <model>]
+  navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--model <model>]
   navarch-runtime doctor [--config-dir <path>]
   navarch-runtime code-graph --query <symbol-or-file> [--mode search|callers|callees|impact] [--commit HEAD] [--depth 1..5] [--repo <path>]
 

package/dist/config.cjs

@@ -108,6 +108,7 @@ function loadRuntimeConfig(env = process.env) {
         leaseHeartbeatIntervalMs,
         sessionTimeoutMs: envRuntimeLimit(env, "NAVARCH_SESSION_TIMEOUT_MS", 0),
         sessionIdleTimeoutMs: envRuntimeLimit(env, "NAVARCH_SESSION_IDLE_TIMEOUT_MS", 45 * 60 * 1000),
+        opencodeStartupTimeoutMs: envRuntimeLimit(env, "NAVARCH_OPENCODE_STARTUP_TIMEOUT_MS", 2 * 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,

package/dist/exit-conditions.cjs

@@ -233,9 +233,11 @@ function mapExitCondition(result) {
         return {
             leaseOutcome: "failed",
             exitStatus: "killed",
-            reportSummary: (result.timeoutReason === "idle"
-                ? "Session stopped: no output or process-tree CPU activity within the configured idle window."
-                : "Session killed: exceeded the configured max session duration.") +
+            reportSummary: (result.timeoutReason === "startup"
+                ? "Session stopped: the agent produced no output within the configured startup window."
+                : result.timeoutReason === "idle"
+                    ? "Session stopped: no output or process-tree CPU activity within the configured idle window."
+                    : "Session killed: exceeded the configured max session duration.") +
                 (result.checkpointPath ? ` Local recovery checkpoint: ${result.checkpointPath}` : "") +
                 (result.retainedWorktreePath ? ` Recovery worktree retained: ${result.retainedWorktreePath}` : ""),
             evidenceUrls,

package/dist/session.cjs

@@ -38,6 +38,21 @@ const COMPLETION_REMEDIATION_RETRIES = 2;
  */
 const DELIVERY_CORRECTION_RETRIES = 1;
 const log = (0, logger_cjs_1.createLogger)("session");
+function resolveSessionExecution(config, claimed) {
+    const runtime = claimed.runtime ?? config.agentType;
+    const execution = claimed.context_bundle.execution ?? {
+        profile: claimed.task.execution_profile ?? "standard",
+        model: runtime === "codex" ? "gpt-6-astra"
+            : runtime === "gemini" ? "auto"
+                : runtime === "opencode" || runtime === "acp" ? "default"
+                    : "claude-opus-5",
+        reasoning_effort: "medium",
+    };
+    return {
+        ...execution,
+        ...(runtime === config.agentType && config.model ? { model: config.model } : {}),
+    };
+}
 /**
  * Runs one claimed task end to end (implementation-plan.md WP-07):
  *   1. write the prompt file
@@ -70,19 +85,9 @@ async function runSession(deps, claimed, sessionId) {
         // explicit pre-start signal. Otherwise it waits for expiry and bypasses
         // the repeat/backoff policy entirely.
         const { api, config } = deps;
-        const { lease_id: leaseId, task, context_bundle: bundle } = claimed;
+        const { lease_id: leaseId, task } = claimed;
         const runtime = claimed.runtime ?? config.agentType;
-        const execution = bundle.execution ?? {
-            profile: task.execution_profile ?? "standard",
-            model: runtime === "codex"
-                ? "gpt-6-astra"
-                : runtime === "gemini"
-                    ? "auto"
-                    : runtime === "opencode" || runtime === "acp"
-                        ? "default"
-                        : "claude-opus-5",
-            reasoning_effort: "medium",
-        };
+        const execution = resolveSessionExecution(config, claimed);
         const crashDetail = describeCompletionError(err).slice(0, 1800);
         const failureSummary = `Session crashed: ${crashDetail}`;
         log.error(`session ${leaseId} threw before adapter start: ${crashDetail}`);
@@ -110,17 +115,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     const { api, config } = deps;
     const { lease_id: leaseId, task, context_bundle: bundle } = claimed;
     const runtime = claimed.runtime ?? config.agentType;
-    const execution = bundle.execution ?? {
-        profile: task.execution_profile ?? "standard",
-        model: runtime === "codex"
-            ? "gpt-6-astra"
-            : runtime === "gemini"
-                ? "auto"
-                : runtime === "opencode" || runtime === "acp"
-                    ? "default"
-                    : "claude-opus-5",
-        reasoning_effort: "medium",
-    };
+    const execution = resolveSessionExecution(config, claimed);
     // Isolation posture reported on every completion so `sessions` records what
     // a run actually executed under (#660). Derived from config alone, so the
     // pre-start failure paths below can stamp it too. Host mode records
@@ -216,6 +211,14 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     let activeAbortController = null;
     let leaseLost = false;
     let leaseGone = false;
+    const abortForRuntimeShutdown = () => {
+        // Machine removal/revocation also makes lease completion impossible.
+        // Treat it like a terminal lease loss so the worktree is checkpointed
+        // and no remediation turn or authenticated API call is attempted.
+        leaseLost = true;
+        leaseGone = true;
+        activeAbortController?.abort();
+    };
     let sessionClosing = false;
     let retainWorktree = false;
     let heartbeatInFlight = null;
@@ -397,6 +400,9 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         activeAbortController?.abort();
     });
     const heartbeatTimer = setInterval(() => void pollLease(), config.leaseHeartbeatIntervalMs);
+    deps.shutdownSignal?.addEventListener("abort", abortForRuntimeShutdown);
+    if (deps.shutdownSignal?.aborted)
+        abortForRuntimeShutdown();
     lifecycle.enteredMainSessionTry = true;
     try {
         await gitWorktree.prepare();
@@ -432,7 +438,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             // notification and start the first turn with the corrected prompt.
             pendingGuidance = [];
             activeAbortController = new AbortController();
-            if (leaseLost)
+            if (leaseLost || deps.shutdownSignal?.aborted)
                 activeAbortController.abort();
             const runPrompt = nextPrompt ??
                 (deliveredGuidance.length > (bundle.guidance?.length ?? 0)
@@ -464,7 +470,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                     cwd: gitWorktree.worktreePath,
                     dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
                     signal: activeAbortController.signal,
-                }, task.idle_timeout_ms ?? config.sessionIdleTimeoutMs ?? 45 * 60_000);
+                }, task.idle_timeout_ms ?? config.sessionIdleTimeoutMs ?? 45 * 60_000, runtime === "opencode" ? config.opencodeStartupTimeoutMs : 0);
             activeAbortController = null;
             if (turnResult.timedOut || leaseLost)
                 await checkpointForRecovery(turnResult);
@@ -716,6 +722,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             .catch((completeErr) => log.warn(`complete() after crash also failed: ${String(completeErr)}`));
     }
     finally {
+        deps.shutdownSignal?.removeEventListener("abort", abortForRuntimeShutdown);
         sessionClosing = true;
         clearInterval(heartbeatTimer);
         heartbeatGuard.stop();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",