@sagentlab/navarch-runtime 0.1.48 → 0.1.50

package/README.md

@@ -837,3 +837,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/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,7 +207,7 @@ 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 activeSessionIds = new Set();
@@ -277,6 +289,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 +347,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/delivery.cjs

@@ -0,0 +1,154 @@
+"use strict";
+// Delivery verification for BYO sessions.
+//
+// `mapExitCondition()` decides a lease outcome from how the agent process
+// ended: a zero exit with no error events is reported `completed`. That is
+// evidence the process finished cleanly, not evidence the task was delivered.
+// session.cts already looks up the head-branch pull request, but only to push
+// onto `evidenceUrls` — the outcome was settled before the lookup ran, so a
+// session that committed work and never opened (or never pushed) a pull
+// request still closed its lease as a success.
+//
+// This module reads what the worktree actually holds after a turn and turns it
+// into a verdict. The hosted executor runs the same rules from inside its
+// sandbox (worker/hosted-agent/delivery.ts); the two differ only in how they
+// reach the checkout, which is why the rules and their justifications live in
+// both places rather than in a shared package the Worker cannot import.
+//
+// Direction of failure: only positive evidence of stranded work gates. An
+// unreadable checkout, a failed pull-request lookup, or an unresolvable base
+// ref all produce `unknown`, which behaves exactly as this code did before the
+// gate existed. A verification mechanism that fails good sessions when its own
+// dependency is unavailable is worse than no mechanism.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeWorktreeDelivery = probeWorktreeDelivery;
+exports.evaluateDelivery = evaluateDelivery;
+exports.renderDeliveryCorrectionPrompt = renderDeliveryCorrectionPrompt;
+const sandbox_cjs_1 = require("./sandbox.cjs");
+const GIT_TIMEOUT_MS = 30_000;
+/**
+ * Reads the worktree's delivery state.
+ *
+ * Every field degrades independently: a git invocation that fails leaves its
+ * field "unknown" (-1, or `dirty: false`) rather than throwing, because a
+ * probe that cannot describe one property should still report the others.
+ * `dirty` is deliberately conservative — an unreadable `git status` reports a
+ * clean tree, so the gate under-fires rather than failing a good session.
+ */
+async function probeWorktreeDelivery(args) {
+    const runner = args.runner ?? sandbox_cjs_1.nodeCommandRunner;
+    const git = async (gitArgs) => {
+        try {
+            const result = await runner.run("git", ["-C", args.worktreePath, ...gitArgs], {
+                timeoutMs: GIT_TIMEOUT_MS,
+            });
+            return result.code === 0 ? result.stdout : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const count = (raw) => {
+        if (raw === null)
+            return -1;
+        const parsed = Number(raw.trim());
+        return Number.isInteger(parsed) && parsed >= 0 ? parsed : -1;
+    };
+    const [branchRaw, statusRaw, aheadRaw, unpushedRaw] = await Promise.all([
+        git(["rev-parse", "--abbrev-ref", "HEAD"]),
+        git(["status", "--porcelain"]),
+        args.baseRef ? git(["rev-list", "--count", `${args.baseRef}..HEAD`]) : Promise.resolve(null),
+        // Commits no origin ref carries. Independent of the base ref, so it still
+        // answers "was this pushed?" when the base cannot be resolved at all.
+        git(["rev-list", "--count", "HEAD", "--not", "--remotes=origin"]),
+    ]);
+    const branch = branchRaw?.trim() ?? "";
+    return {
+        branch: branch && branch !== "HEAD" ? branch : null,
+        dirty: statusRaw !== null && statusRaw.trim().length > 0,
+        commitsAhead: count(aheadRaw),
+        unpushedCommits: count(unpushedRaw),
+    };
+}
+/**
+ * Maps a probe to a verdict.
+ *
+ * Dirty files are stranded even if a PR carries the committed HEAD. Once
+ * the tree is clean, the SHA-verified PR lookup is stronger evidence than
+ * potentially stale remote-tracking refs. Otherwise ordering runs from most to least
+ * certain — uncommitted edits, then commits that were never pushed, then
+ * pushed commits with no pull request — so the reason a session is failed
+ * names the earliest point the delivery chain broke.
+ */
+function evaluateDelivery(probe) {
+    if (probe.dirty) {
+        return {
+            status: "incomplete",
+            reason: "the worktree still has uncommitted changes, so the work was never committed or pushed",
+        };
+    }
+    if (probe.pullRequestUrl)
+        return { status: "delivered", pullRequestUrl: probe.pullRequestUrl };
+    const hasWork = probe.commitsAhead > 0 || probe.unpushedCommits > 0;
+    if (!hasWork) {
+        // Both counts unknown: the checkout could not be read at all.
+        if (probe.commitsAhead < 0 && probe.unpushedCommits < 0) {
+            return { status: "unknown", reason: "the worktree's commit state could not be read" };
+        }
+        // A base that could not be resolved hides commits that a resumed task
+        // branch already carried, so only a confirmed zero means "no work".
+        if (probe.commitsAhead < 0 && probe.unpushedCommits === 0) {
+            return { status: "unknown", reason: "the branch's base ref could not be resolved" };
+        }
+        return { status: "no_changes" };
+    }
+    if (probe.unpushedCommits > 0) {
+        const plural = probe.unpushedCommits === 1 ? "commit" : "commits";
+        return {
+            status: "incomplete",
+            reason: `${probe.unpushedCommits} ${plural} on ${describeBranch(probe.branch)} ` +
+                "were never pushed, so the work exists only in this session's worktree",
+        };
+    }
+    // Pushed, but nothing carries it. Only gate when GitHub actually answered.
+    if (probe.pullRequestLookupFailed) {
+        return { status: "unknown", reason: "the pull request lookup could not run, so delivery cannot be confirmed" };
+    }
+    const plural = probe.commitsAhead === 1 ? "commit" : "commits";
+    return {
+        status: "incomplete",
+        reason: `${probe.commitsAhead} ${plural} were pushed to ${describeBranch(probe.branch)} ` +
+            "but no pull request was opened for that branch",
+    };
+}
+function describeBranch(branch) {
+    return branch ? `\`${branch}\`` : "a detached HEAD";
+}
+/**
+ * Prompt for the turn that follows an `incomplete` verdict.
+ *
+ * session.cts already re-runs the agent in the same worktree for mid-flight
+ * human guidance and for remediable control-plane rejections; this is the same
+ * shape of turn for the same reason — the partial work on disk is the state
+ * worth continuing from, so the prompt points at it rather than restating the
+ * task.
+ */
+function renderDeliveryCorrectionPrompt(args) {
+    return [
+        args.originalPrompt.trim(),
+        "",
+        "## Delivery is incomplete",
+        "",
+        `Your previous turn ended without delivering the task: ${args.reason}.`,
+        "",
+        `This is delivery attempt ${args.attempt} of ${args.maxAttempts}. You are in the same worktree as before,`,
+        "so your earlier edits, commits, and branch are all still here — start with `git status` and",
+        "`git log --oneline` and continue from there rather than redoing the work.",
+        "",
+        "Finish the delivery chain: commit the work, push the branch, and open the pull request.",
+        "If part of the task genuinely cannot be completed, still deliver what does work as a pull request",
+        "and state plainly in the description what is missing and why.",
+        "",
+        "This session's worktree is deleted when the session ends. Work that is not pushed is lost.",
+    ].join("\n");
+}

package/dist/git-worktree.cjs

@@ -304,6 +304,20 @@ class GitWorktree {
             this.taskOwnershipTrailer,
         ], false);
     }
+    /**
+     * Remote-tracking ref a delivery is measured against: the repository's
+     * default branch. Public so completion can count the task's commits without
+     * repeating default-branch discovery, and null-safe so an unreachable remote
+     * leaves the delivery gate "unknown" rather than failing the session.
+     */
+    async resolveDeliveryBase() {
+        try {
+            return await this.resolveStartRef();
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Resolves the remote-tracking ref new session branches start from, or null
      * when the remote has no branches at all (a freshly provisioned empty repo).

package/dist/session.cjs

@@ -21,6 +21,7 @@ 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 delivery_cjs_1 = require("./delivery.cjs");
 const worktree_guard_cjs_1 = require("./worktree-guard.cjs");
 const adapter_watchdog_cjs_1 = require("./adapter-watchdog.cjs");
 const lease_heartbeat_cjs_1 = require("./lease-heartbeat.cjs");
@@ -29,7 +30,29 @@ const adapter_capacity_cjs_1 = require("./adapter-capacity.cjs");
 const MCP_CONFIG_FILENAME = "mcp-config.json";
 const GIT_CREDENTIAL_HELPER_FILENAME = "git-credential-navarch.cjs";
 const COMPLETION_REMEDIATION_RETRIES = 2;
+/**
+ * Turns the delivery gate (delivery.cjs) may spend on a session that finished
+ * cleanly but left work undelivered. Counted separately from the
+ * control-plane remediation retries above: the two failures are independent,
+ * and one must not consume the other's budget.
+ */
+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
@@ -62,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}`);
@@ -102,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
@@ -417,6 +420,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         const maxRuntimeMs = task.max_runtime_ms ?? config.sessionTimeoutMs;
         let nextPrompt = null;
         let completionRemediationRetries = 0;
+        let deliveryCorrectionRetries = 0;
         while (true) {
             // Guidance can arrive while the worktree/sandbox is being prepared.
             // It is already included in deliveredGuidance, so clear the pending
@@ -504,8 +508,10 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 // Preserve the original exact-branch lookup if HEAD cannot be read.
                 log.warn(`worktree HEAD lookup failed for ${leaseId}: ${String(err)}`);
             }
+            let pullRequestUrl = null;
+            let pullRequestLookupFailed = false;
             try {
-                const prUrl = await (0, github_pr_cjs_1.findHeadBranchPullRequestUrl)({
+                pullRequestUrl = await (0, github_pr_cjs_1.findHeadBranchPullRequestUrl)({
                     repository: bundle.repository?.full_name ?? task.repo,
                     headBranch,
                     headSha,
@@ -514,14 +520,61 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                     allowShaFallback: allowBranchRename,
                     githubToken,
                 });
-                if (prUrl)
-                    mapping.evidenceUrls.push(prUrl);
+                if (pullRequestUrl)
+                    mapping.evidenceUrls.push(pullRequestUrl);
             }
             catch (err) {
                 // Evidence discovery is best-effort: a GitHub outage or token scope
                 // mismatch must not turn an otherwise valid completion into a crash.
+                // The delivery gate below reads this flag and declines to gate rather
+                // than failing a session whose pull request it simply could not see.
+                pullRequestLookupFailed = true;
                 log.warn(`head-branch PR lookup failed for ${leaseId}: ${String(err)}`);
             }
+            // -- delivery gate -----------------------------------------------------
+            // A clean exit is not delivery. Read what the worktree actually holds
+            // and, when work was started but never shipped, spend a correction turn
+            // in the same worktree before failing the lease. See delivery.cjs for
+            // why only positive evidence gates.
+            let deliveryFailureSummary = null;
+            if (mapping.leaseOutcome === "completed" && !leaseLost) {
+                let delivery;
+                try {
+                    const probe = await (0, delivery_cjs_1.probeWorktreeDelivery)({
+                        worktreePath: gitWorktree.worktreePath,
+                        baseRef: await gitWorktree.resolveDeliveryBase(),
+                    });
+                    delivery = (0, delivery_cjs_1.evaluateDelivery)({ ...probe, pullRequestUrl, pullRequestLookupFailed });
+                }
+                catch (err) {
+                    delivery = { status: "unknown", reason: `the delivery probe failed: ${String(err)}` };
+                }
+                if (delivery.status === "unknown") {
+                    log.warn(`delivery for ${leaseId} could not be verified: ${delivery.reason}; completing anyway.`);
+                }
+                if (delivery.status === "incomplete") {
+                    if (deliveryCorrectionRetries < DELIVERY_CORRECTION_RETRIES) {
+                        deliveryCorrectionRetries += 1;
+                        log.warn(`session ${leaseId} finished without delivering (${delivery.reason}); ` +
+                            `restarting agent turn ${deliveryCorrectionRetries}/${DELIVERY_CORRECTION_RETRIES} in the same worktree.`);
+                        nextPrompt = (0, delivery_cjs_1.renderDeliveryCorrectionPrompt)({
+                            originalPrompt: runPrompt,
+                            reason: delivery.reason,
+                            attempt: deliveryCorrectionRetries,
+                            maxAttempts: DELIVERY_CORRECTION_RETRIES,
+                        });
+                        continue;
+                    }
+                    deliveryFailureSummary =
+                        `Session ended without delivering the task: ${delivery.reason}. ` +
+                            `${deliveryCorrectionRetries} correction turn(s) did not recover it. ` +
+                            "The session worktree is deleted at teardown, so the work is gone; the task needs another attempt.";
+                    log.warn(`failing ${leaseId}: ${deliveryFailureSummary}`);
+                    mapping.leaseOutcome = "failed";
+                    mapping.exitStatus = "failed";
+                    mapping.reportSummary = `${deliveryFailureSummary}\n\n---\n\n${mapping.reportSummary}`;
+                }
+            }
             const knownSecrets = registry.list();
             if (mapping.leaseOutcome === "failed") {
                 log.warn(`adapter failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(mapping.reportSummary, knownSecrets)}`);
@@ -554,6 +607,9 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                     ? verificationFailureReport(task.task_type, redactedReport)
                     : redactedReport,
                 evidence_urls: mapping.evidenceUrls,
+                ...(deliveryFailureSummary
+                    ? { failure_summary: (0, redact_cjs_1.redactText)(deliveryFailureSummary, knownSecrets) }
+                    : {}),
                 cost: {
                     ...(result.tokensIn !== undefined ? { tokens_in: result.tokensIn } : {}),
                     ...(result.tokensOut !== undefined ? { tokens_out: result.tokensOut } : {}),

package/package.json

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