@sagentlab/navarch-runtime 0.1.43 → 0.1.45

package/README.md

@@ -630,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/git-worktree.cjs

@@ -56,6 +56,7 @@ class GitWorktree {
         await node_fs_1.promises.mkdir(this.sessionRoot, { recursive: true });
         await withRepositoryLock(this.repositoryPath, async () => {
             await this.ensureRepositoryCache();
+            await this.installDeliveryBranchGuard();
             try {
                 await this.addSessionWorktree();
             }
@@ -94,6 +95,22 @@ class GitWorktree {
         await node_fs_1.promises.chmod(configPath, 0o600);
         await node_fs_1.promises.appendFile(configPath, block, { encoding: "utf8", mode: 0o600 });
     }
+    /**
+     * Installs the delivery-branch guard shared by every worktree of this cache.
+     * The hook is inert unless the session exports `NAVARCH_DELIVERY_BRANCH`, so
+     * PR-continuation sessions that must push a reviewed PR's head branch are
+     * unaffected. Root tasks export the allocated `navarch/...` branch, which
+     * stops an agent from renaming the branch (e.g. Codex's default `codex/...`
+     * prefix) and stranding the PR on a branch the task does not own.
+     */
+    async installDeliveryBranchGuard(repositoryPath = this.repositoryPath) {
+        const hooksDir = node_path_1.default.join(repositoryPath, "hooks");
+        await node_fs_1.promises.mkdir(hooksDir, { recursive: true });
+        await node_fs_1.promises.writeFile(node_path_1.default.join(hooksDir, "pre-push"), DELIVERY_BRANCH_GUARD_HOOK, {
+            encoding: "utf8",
+            mode: 0o755,
+        });
+    }
     /** Clones the bare cache if missing, repoints origin if needed, and fetches all branches. */
     async ensureRepositoryCache() {
         if (!(await pathExists(node_path_1.default.join(this.repositoryPath, "HEAD")))) {
@@ -312,6 +329,8 @@ class GitWorktree {
             if (!/unknown option|usage: git worktree add/i.test(errorMessage(error)))
                 throw error;
             await this.runGit(["init", "--initial-branch", this.branch, this.worktreePath], false);
+            // This fallback is a standalone repository, so it does not share cache hooks.
+            await this.installDeliveryBranchGuard(node_path_1.default.join(this.worktreePath, ".git"));
             await this.runGit(["-C", this.worktreePath, "remote", "add", "origin", this.cloneUrl], false);
         }
     }
@@ -337,6 +356,30 @@ class GitWorktree {
             sha,
         };
     }
+    /**
+     * Resolves the head the session reports to the control plane after an agent
+     * turn.
+     *
+     * Root tasks own exactly one delivery branch. If an agent renamed or switched
+     * away from the allocated `navarch/...` branch, the worktree is moved back
+     * onto it so completion evidence and the PR land on the branch the task owns.
+     * PR-continuation tasks (review-fix, conflict resolution, stale-PR recovery)
+     * pass `allowRename` so they can check out and push the reviewed PR's head
+     * branch, which is the one case a different branch is expected.
+     */
+    async resolveDeliveryHead(allowRename) {
+        const head = await this.resolveCurrentHead();
+        if (allowRename || head.branch === this.branch)
+            return head;
+        try {
+            await this.runGit(["-C", this.worktreePath, "checkout", "-B", this.branch, "HEAD"], false);
+        }
+        catch (error) {
+            throw new Error(`Could not restore task delivery branch ${this.branch} after the agent left ` +
+                `${head.branch ?? "a detached HEAD"}: ${errorMessage(error)}`);
+        }
+        return { branch: this.branch, sha: head.sha };
+    }
     async cleanup() {
         await withRepositoryLock(this.repositoryPath, async () => {
             await this.removeRepoLocalGithubToken();
@@ -443,6 +486,32 @@ async function pathExists(value) {
         return false;
     }
 }
+/**
+ * Pre-push guard installed in the repository cache's hooks directory. When
+ * `NAVARCH_DELIVERY_BRANCH` is present it refuses to create, update, or delete
+ * any other branch, so a coding agent cannot move a root task's delivery off
+ * the allocated `navarch/...` branch (for example onto Codex's default
+ * `codex/...` prefix). `--no-verify` bypasses any hook, so
+ * `resolveDeliveryHead` also repairs the worktree before completion.
+ */
+const DELIVERY_BRANCH_GUARD_HOOK = `#!/bin/sh
+# Managed by @sagentlab/navarch-runtime (git-worktree.cts).
+allowed="\${NAVARCH_DELIVERY_BRANCH:-}"
+[ -n "$allowed" ] || exit 0
+status=0
+while read -r local_ref local_sha remote_ref remote_sha; do
+  case "$remote_ref" in
+    refs/heads/*) ;;
+    *) continue ;;
+  esac
+  branch="\${remote_ref#refs/heads/}"
+  if [ "$branch" != "$allowed" ]; then
+    printf '%s\\n' "navarch: refusing to push '$branch'; this task's delivery branch is '$allowed'." >&2
+    status=1
+  fi
+done
+exit "$status"
+`;
 /**
  * Kebab-case slug for the task branch, derived from the task summary so
  * branch names read like `navarch/fix-login-redirect-<task-id>` instead of a

package/dist/github-pr.cjs

@@ -85,7 +85,7 @@ async function findHeadBranchPullRequestUrl(options) {
         (!normalizedHeadSha ||
             (typeof candidate.head.sha === "string" &&
                 candidate.head.sha.toLowerCase() === normalizedHeadSha)));
-    if (branchMatch || !normalizedHeadSha)
+    if (branchMatch || !normalizedHeadSha || options.allowShaFallback === false)
         return branchMatch;
     const commitUrl = new URL(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/commits/${normalizedHeadSha}/pulls`);
     commitUrl.searchParams.set("per_page", "10");

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/dist/session.cjs

@@ -193,6 +193,11 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         githubToken,
         repoLocalGithubToken: secrets["github-pat"],
     });
+    // A root task owns one delivery branch, so the pre-push guard and the
+    // completion-time reconciliation keep the agent on the allocated
+    // `navarch/...` branch. PR-continuation tasks are the exception: their agent
+    // must check out and push the reviewed PR's existing head branch.
+    const allowBranchRename = Boolean(task.review_of_task_id);
     const knownGuidanceIds = new Set((bundle.guidance ?? []).map((entry) => entry.id));
     const deliveredGuidance = [...(bundle.guidance ?? [])];
     let guidanceCursor = bundle.guidance_cursor ?? null;
@@ -344,6 +349,9 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     lifecycle.enteredMainSessionTry = true;
     try {
         await gitWorktree.prepare();
+        // Preparation may resume an existing task branch with an older slug or ID format.
+        if (!allowBranchRename)
+            sessionEnv.NAVARCH_DELIVERY_BRANCH = gitWorktree.branch;
         if (sandbox) {
             await sandbox.create();
             // Security-policy refusals (a mount outside the allowlist, an egress
@@ -435,7 +443,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             let headBranch = gitWorktree.branch;
             let headSha;
             try {
-                const currentHead = await gitWorktree.resolveCurrentHead();
+                const currentHead = await gitWorktree.resolveDeliveryHead(allowBranchRename);
                 headBranch = currentHead.branch ?? headBranch;
                 headSha = currentHead.sha;
             }
@@ -448,6 +456,9 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                     repository: bundle.repository?.full_name ?? task.repo,
                     headBranch,
                     headSha,
+                    // Keep SHA verification on the exact branch, but do not adopt a
+                    // foreign-branch PR as delivery evidence for a root task.
+                    allowShaFallback: allowBranchRename,
                     githubToken,
                 });
                 if (prUrl)

package/package.json

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