@sagentlab/navarch-runtime 0.1.48 → 0.1.49

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,6 +30,13 @@ 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");
 /**
  * Runs one claimed task end to end (implementation-plan.md WP-07):
@@ -417,6 +425,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 +513,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 +525,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 +612,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.49",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",