@sagentlab/navarch-runtime 0.1.42 → 0.1.44

package/README.md

@@ -326,7 +326,7 @@ unchanged across the deployment.
 | `NAVARCH_ACP_BIN` | `dsh` | Path/name of an Agent Client Protocol v1 stdio server. DeepSeek Harness is the default implementation. |
 | `NAVARCH_ACP_EXTRA_ARGS` | `--profile,acp` | Comma list of arguments used to start the ACP server. Override this together with `NAVARCH_ACP_BIN` for another ACP-compatible coding agent. |
 | `NAVARCH_MCP_CONFIG_PATH` | — | Path to the platform MCP config passed as `--mcp-config`. |
-| `NAVARCH_WORKTREE_GUARD` | on | Host-mode sessions get an adapter-native per-session worktree boundary guard (see below). Set `off` to disable. |
+| `NAVARCH_WORKTREE_GUARD` | on | Host-mode sessions get an adapter-native per-session worktree boundary guard (see below). Set `off` to disable it for every runtime on the machine — required to run OpenCode on the host. |
 | `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)
@@ -378,10 +378,13 @@ as an explicit read-only mount.
   Docker-mode sessions disable Gemini's implicit YOLO sandbox to avoid nesting
   it inside Navarch's already isolated session container.
 - **OpenCode:** the CLI cannot currently express a host-side boundary for all
-  shell side effects. With the guard enabled, host launches therefore fail
-  closed before the CLI starts. Run OpenCode in Docker with an operator-owned
-  image that contains an authenticated `opencode` binary, or set
-  `NAVARCH_WORKTREE_GUARD=off` only when the whole machine is already isolated.
+  shell side effects, so with the guard enabled it is resolved out of the
+  machine's advertised runtimes at startup — and a machine that offers only
+  OpenCode there refuses to start rather than claim tasks it can only fail.
+  Run OpenCode in Docker with an operator-owned image that contains an
+  authenticated `opencode` binary, or set `NAVARCH_WORKTREE_GUARD=off` only
+  when the whole machine is already isolated (the opt-out is machine-wide:
+  every runtime on it loses the boundary).
   OpenCode receives a private, per-session config, project config discovery is
   disabled, and lease MCP headers are referenced through child-only environment
   variables instead of being copied into its config file or argv.
@@ -445,15 +448,18 @@ export NAVARCH_AGENT=codex
 export NAVARCH_AGENT=gemini
 
 # OpenCode — requires an authenticated `opencode` CLI (or
-# NAVARCH_OPENCODE_BIN pointing at it). The guarded host path fails closed;
-# use a Docker image containing OpenCode for the normal isolated path.
+# NAVARCH_OPENCODE_BIN pointing at it). A guarded host refuses to start with
+# only this runtime; use a Docker image containing OpenCode for the normal
+# isolated path, or NAVARCH_WORKTREE_GUARD=off on an isolated machine.
 export NAVARCH_AGENT=opencode
 
 # Agent Client Protocol — defaults to DeepSeek Harness `dsh --profile acp`.
 # Override NAVARCH_ACP_BIN / NAVARCH_ACP_EXTRA_ARGS for another ACP v1 server.
 export NAVARCH_AGENT=acp
 
-# Advanced compatibility mode: advertise every installed adapter.
+# Advanced compatibility mode: advertise every installed adapter. On a guarded
+# host, `opencode` is dropped from this list (see the boundary notes above);
+# the rest are advertised as written.
 export NAVARCH_RUNTIMES=claude-code,codex,gemini,opencode,acp
 ```
 
@@ -624,6 +630,20 @@ contract used by `api.cts`, including:
 `POST /api/machines/connect` is the project-scoped alternative: it redeems a
 single-use token minted by an owner through the onboarding or Fleet UI.
 
+Machine-authenticated routes answer a rejected identity in three distinct
+ways, and the runtime treats them differently:
+
+- **503** — the control plane could not complete the token lookup. Transient;
+  retried like any other failure. (Before this split a failed lookup came back
+  as 401, so one database blip looked exactly like a revoked token.)
+- **401** — the token is not recognized.
+- **410** — this agent was removed from the fleet.
+
+Three *consecutive* 401/410 heartbeats end the run: the runtime stops claiming,
+lets active sessions finish, prints how to re-enroll, and exits 78. The
+supervisor does not respawn on that code — a new process cannot fix a
+credential the control plane no longer honors.
+
 ## What needs live verification
 
 Most runtime behavior is covered offline. The Codex host adapter was also

package/dist/cli.cjs

@@ -20,6 +20,12 @@ 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";
+/**
+ * Exit code for "this machine's identity is gone". Deliberately outside the
+ * supervisor's restart codes (75 update, 76 remote restart): respawning cannot
+ * fix a revoked or removed credential, so the supervisor must exit too.
+ */
+const CREDENTIALS_REJECTED_EXIT_CODE = 78;
 /** Include a control-plane response's safe error detail in top-level CLI failures. */
 function describeCliError(err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -217,6 +223,17 @@ async function startCommand(flags) {
             readySent = true;
             process.send({ type: "navarch-ready", boot_id: bootId });
         }
+    }, (status) => {
+        claimLoop.stop();
+        worktreeJanitor.stop();
+        log.error(status === 410
+            ? `agent ${identity.name} has been removed from the fleet; it can no longer claim tasks.`
+            : `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.
+        void capacity.waitForIdle().then(() => process.exit(CREDENTIALS_REJECTED_EXIT_CODE));
     });
     updateCoordinatorRef.current = new update_coordinator_cjs_1.RuntimeUpdateCoordinator({
         config,

package/dist/heartbeat-loop.cjs

@@ -1,10 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MachineHeartbeatLoop = void 0;
+const api_cjs_1 = require("./api.cjs");
 const version_cjs_1 = require("./version.cjs");
 const usage_limits_cjs_1 = require("./usage-limits.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const log = (0, logger_cjs_1.createLogger)("heartbeat");
+/**
+ * How many consecutive credential rejections end the loop. A single 401 is not
+ * proof of anything — before the control plane learned to answer a failed
+ * token lookup with 503, a transient database blip surfaced here as one — so
+ * the identity is only declared dead once several beats in a row agree.
+ */
+const CREDENTIAL_REJECTION_LIMIT = 3;
+/** 401: the token is not recognized. 410: this agent was removed from the fleet. */
+function credentialRejectionStatus(err) {
+    if (!(err instanceof api_cjs_1.NavarchApiError))
+        return null;
+    return err.status === 401 || err.status === 410 ? err.status : null;
+}
 /**
  * Machine-level heartbeat loop (implementation-plan.md WP-07), separate from
  * the per-lease heartbeat in session.cts: reports this machine's online
@@ -19,13 +33,22 @@ class MachineHeartbeatLoop {
     bootId;
     onResult;
     onHealthy;
+    onCredentialsRejected;
     timer = null;
     heartbeatInFlight = false;
     heartbeatPending = false;
     updateState = "idle";
     lastUpdateError;
     draining = false;
-    constructor(api, machineId, config, capacity, bootId, onResult, onHealthy) {
+    credentialRejections = 0;
+    constructor(api, machineId, config, capacity, bootId, onResult, onHealthy, 
+    /**
+     * Called once the machine's credentials have been rejected
+     * CREDENTIAL_REJECTION_LIMIT times running. The loop has stopped itself by
+     * then: without this the runtime would warn every interval forever while
+     * claiming nothing, which is indistinguishable from an idle agent.
+     */
+    onCredentialsRejected) {
         this.api = api;
         this.machineId = machineId;
         this.config = config;
@@ -33,6 +56,7 @@ class MachineHeartbeatLoop {
         this.bootId = bootId;
         this.onResult = onResult;
         this.onHealthy = onHealthy;
+        this.onCredentialsRejected = onCredentialsRejected;
     }
     start() {
         if (this.timer)
@@ -88,11 +112,28 @@ class MachineHeartbeatLoop {
                             ...(this.lastUpdateError ? { last_update_error: this.lastUpdateError } : {}),
                         },
                     });
+                    this.credentialRejections = 0;
                     this.onHealthy?.();
                     this.onResult?.(result);
                 }
                 catch (err) {
-                    log.warn(`machine heartbeat failed: ${String(err)}`);
+                    const rejection = credentialRejectionStatus(err);
+                    if (rejection === null) {
+                        this.credentialRejections = 0;
+                        log.warn(`machine heartbeat failed: ${String(err)}`);
+                        continue;
+                    }
+                    this.credentialRejections += 1;
+                    const reason = rejection === 410
+                        ? "this agent has been removed from the fleet"
+                        : "the control plane does not recognize this machine token";
+                    log.warn(`machine heartbeat rejected (${rejection}): ${reason} ` +
+                        `(${this.credentialRejections}/${CREDENTIAL_REJECTION_LIMIT})`);
+                    if (this.credentialRejections >= CREDENTIAL_REJECTION_LIMIT) {
+                        this.stop();
+                        this.onCredentialsRejected?.(rejection);
+                        return;
+                    }
                 }
             } while (this.heartbeatPending);
         }

package/package.json

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