@sagentlab/navarch-runtime 0.1.58 → 0.1.60

package/dist/delivery.cjs

@@ -54,13 +54,21 @@ async function probeWorktreeDelivery(args) {
         const parsed = Number(raw.trim());
         return Number.isInteger(parsed) && parsed >= 0 ? parsed : -1;
     };
+    // Both counts skip empty commits: `--full-history -- .` keeps every commit
+    // that changes a file (merges included) and drops the ones that change
+    // nothing. The runtime opens every new task branch with an empty
+    // `chore(navarch): claim task branch` commit (git-worktree.cts); counting it
+    // failed sessions that correctly delivered nothing — a superseded task, say —
+    // as "1 commit never pushed" and pushed their agent to open an empty PR.
     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),
+        args.baseRef
+            ? git(["rev-list", "--count", "--full-history", `${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"]),
+        git(["rev-list", "--count", "--full-history", "HEAD", "--not", "--remotes=origin", "--", "."]),
     ]);
     const branch = branchRaw?.trim() ?? "";
     return {

package/dist/git-worktree.cjs

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GitWorktree = void 0;
 exports.branchSlug = branchSlug;
+exports.hostedCheckpointRef = hostedCheckpointRef;
 const node_path_1 = __importDefault(require("node:path"));
 const worktree_janitor_cjs_1 = require("./worktree-janitor.cjs");
 const node_fs_1 = require("node:fs");
@@ -21,6 +22,10 @@ class GitWorktree {
     worktreePath;
     repositoryPath;
     branch;
+    /** Set by prepare() when the session resumed a hosted attempt's checkpoint. */
+    restoredHostedCheckpoint = null;
+    /** Why an existing hosted checkpoint could not be restored, for the session log. */
+    hostedCheckpointRestoreFailure = null;
     runner;
     checkpointRoot;
     cloneUrl;
@@ -30,6 +35,8 @@ class GitWorktree {
     legacyTaskBranchSuffix;
     taskOwnershipTrailer;
     sessionTokenMarker;
+    hostedCheckpointRef;
+    hostedCheckpointLocalRef;
     constructor(options) {
         const projectKey = safePathSegment(options.projectId);
         const sessionKey = safePathSegment(options.sessionId);
@@ -53,6 +60,8 @@ class GitWorktree {
         this.cloneUrl = options.cloneUrl;
         this.githubToken = options.githubToken;
         this.repoLocalGithubToken = options.repoLocalGithubToken;
+        this.hostedCheckpointRef = options.restoreHostedCheckpoint ? hostedCheckpointRef(options.taskId) : null;
+        this.hostedCheckpointLocalRef = `refs/navarch/restored-checkpoints/${taskKey}`;
     }
     async prepare() {
         await node_fs_1.promises.mkdir(node_path_1.default.dirname(this.repositoryPath), { recursive: true });
@@ -145,6 +154,10 @@ class GitWorktree {
         // `worktree add -b` would fail on it, dooming every remaining attempt.
         const staleTip = await this.reclaimStaleLocalBranch();
         const baseRef = taskRef ?? (await this.resolveStartRef());
+        // A hosted attempt never pushes the allocated branch until it delivers; an
+        // interrupted one leaves its work only in a checkpoint ref. Without this a
+        // self-hosted retry starts from the default branch and silently discards it.
+        const checkpoint = !taskRef && !staleTip ? await this.fetchHostedCheckpoint() : null;
         // The stale local tip may hold commits the killed session never pushed;
         // resume it unless the pushed task branch has moved past it (then the
         // remote is the durable record).
@@ -152,7 +165,9 @@ class GitWorktree {
             ? taskRef && !(await this.isAncestor(taskRef, staleTip))
                 ? taskRef
                 : staleTip
-            : baseRef;
+            : checkpoint
+                ? checkpoint.parent
+                : baseRef;
         if (!startRef) {
             // Empty remote (no commits yet): there is nothing to base the session on,
             // so bootstrap an orphan branch the session can push as the first commit.
@@ -172,6 +187,91 @@ class GitWorktree {
         ], false);
         if (!taskRef && !staleTip)
             await this.createTaskOwnershipCommit();
+        if (checkpoint)
+            await this.applyHostedCheckpoint(checkpoint);
+    }
+    /**
+     * Fetches the hosted checkpoint for this task into the cache, or returns
+     * null when there is none. Best-effort: a checkpoint that cannot be read
+     * costs only the work a fresh start would have lost anyway.
+     */
+    async fetchHostedCheckpoint() {
+        const ref = this.hostedCheckpointRef;
+        if (!ref)
+            return null;
+        try {
+            const listed = await this.runGit(["--git-dir", this.repositoryPath, "ls-remote", "origin", ref], true);
+            if (!listed.stdout.trim())
+                return null;
+            await this.runGit(["--git-dir", this.repositoryPath, "fetch", "--quiet", "--no-tags", "origin", `+${ref}:${this.hostedCheckpointLocalRef}`], true);
+            const [sha, parent] = await Promise.all([this.hostedCheckpointLocalRef, `${this.hostedCheckpointLocalRef}^`].map(async (rev) => (await this.runGit(["--git-dir", this.repositoryPath, "rev-parse", "--verify", `${rev}^{commit}`], false))
+                .stdout.trim()));
+            if (!/^[0-9a-f]{40,64}$/i.test(sha) || !/^[0-9a-f]{40,64}$/i.test(parent)) {
+                throw new Error("the checkpoint ref did not resolve to a snapshot commit with a parent");
+            }
+            return { ref, sha: sha, parent: parent };
+        }
+        catch (error) {
+            this.hostedCheckpointRestoreFailure = errorMessage(error);
+            await this.dropHostedCheckpointLocalRef();
+            return null;
+        }
+    }
+    /**
+     * Puts the snapshot's files in the working tree as uncommitted edits on top
+     * of the branch, which already sits on the hosted agent's HEAD: the state the
+     * interrupted agent was in. `read-tree -u --reset` rewrites the index and
+     * files (deletions included) without moving HEAD; the mixed reset then puts
+     * the index back on HEAD so the edits show as unstaged, as they were.
+     */
+    async applyHostedCheckpoint(checkpoint) {
+        try {
+            const meta = await this.runGit(["--git-dir", this.repositoryPath, "show", "-s", "--format=%cI%x00%B", checkpoint.sha], false);
+            const [savedAt = "", body = ""] = meta.stdout.split("\0");
+            const hostedBranch = body
+                .split("\n")
+                .map((line) => line.match(/^Navarch-Checkpoint-Branch:\s*(\S+)\s*$/)?.[1])
+                .find(Boolean) ?? "";
+            await this.runGit(["-C", this.worktreePath, "read-tree", "-u", "--reset", checkpoint.sha], false);
+            await this.runGit(["-C", this.worktreePath, "reset", "-q"], false);
+            const status = await this.runGit(["-C", this.worktreePath, "status", "--porcelain"], false);
+            this.restoredHostedCheckpoint = {
+                ref: checkpoint.ref,
+                sha: checkpoint.sha,
+                hostedBranch,
+                savedAt: savedAt.trim(),
+                changedFiles: status.stdout.split("\n").filter((line) => line.trim()).length,
+            };
+        }
+        catch (error) {
+            // The branch still carries the hosted agent's commits; only its
+            // uncommitted edits are lost. Leave a clean tree, not a half-applied one.
+            this.hostedCheckpointRestoreFailure = errorMessage(error);
+            await this.runner
+                .run("git", ["-C", this.worktreePath, "reset", "-q", "--hard", "HEAD"])
+                .catch(() => undefined);
+            await this.runner.run("git", ["-C", this.worktreePath, "clean", "-fdq"]).catch(() => undefined);
+        }
+        finally {
+            await this.dropHostedCheckpointLocalRef();
+        }
+    }
+    async dropHostedCheckpointLocalRef() {
+        await this.runner
+            .run("git", ["--git-dir", this.repositoryPath, "update-ref", "-d", this.hostedCheckpointLocalRef])
+            .catch(() => undefined);
+    }
+    /**
+     * Removes the restored hosted checkpoint from origin once a pull request
+     * carries its work, so a later hosted attempt does not resume a stale
+     * snapshot. Best-effort, like the hosted side's own delete.
+     */
+    async deleteRestoredHostedCheckpoint() {
+        const restored = this.restoredHostedCheckpoint;
+        if (!restored)
+            return;
+        await this.runGit(["--git-dir", this.repositoryPath, "push", "--quiet", "origin", `:${restored.ref}`], true);
+        this.restoredHostedCheckpoint = null;
     }
     /**
      * Releases a leftover local task branch (and any dead worktree holding it)
@@ -287,6 +387,14 @@ class GitWorktree {
             .split("\n")
             .some((line) => line.trim() === this.taskOwnershipTrailer);
     }
+    /**
+     * The ownership line a push to the delivery branch must keep, for the
+     * pre-push guard (`NAVARCH_DELIVERY_TASK_MARKER`). Null for a resumed legacy
+     * full-UUID branch, whose name alone proves ownership.
+     */
+    get deliveryTaskMarker() {
+        return this.branch.endsWith(this.legacyTaskBranchSuffix) ? null : this.taskOwnershipTrailer;
+    }
     /** Records full task ownership without lengthening the human-facing branch name. */
     async createTaskOwnershipCommit() {
         await this.runGit([
@@ -557,6 +665,11 @@ async function pathExists(value) {
  * 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.
+ *
+ * With `NAVARCH_DELIVERY_TASK_MARKER` it also refuses a delivery-branch push
+ * whose history lost the task's ownership commit (an amend, reset, or rebase
+ * drops the empty claim commit). A retry only resumes a short-suffix branch
+ * that carries the marker, so an unmarked push strands the task.
  */
 const DELIVERY_BRANCH_GUARD_HOOK = `#!/bin/sh
 # Managed by @sagentlab/navarch-runtime (git-worktree.cts).
@@ -572,6 +685,18 @@ while read -r local_ref local_sha remote_ref remote_sha; do
   if [ "$branch" != "$allowed" ]; then
     printf '%s\\n' "navarch: refusing to push '$branch'; this task's delivery branch is '$allowed'." >&2
     status=1
+    continue
+  fi
+  marker="\${NAVARCH_DELIVERY_TASK_MARKER:-}"
+  [ -n "$marker" ] || continue
+  case "$local_sha" in
+    *[!0]*) ;;
+    *) continue ;;
+  esac
+  if [ -z "$(git log -1 --format=%H --fixed-strings --grep="$marker" "$local_sha" 2>/dev/null)" ]; then
+    printf '%s\\n' "navarch: refusing to push '$branch'; its history no longer contains the task ownership line '$marker' (the empty 'chore(navarch): claim task branch' commit was amended, reset, or rebased away)." >&2
+    printf '%s\\n' "navarch: restore it with: git commit --allow-empty -m 'chore(navarch): claim task branch' -m '$marker' && git push" >&2
+    status=1
   fi
 done
 exit "$status"
@@ -602,6 +727,16 @@ function branchSlug(options) {
         .replace(/^-+|-+$/g, "");
     return idSlug || "task";
 }
+/**
+ * The hidden per-task ref hosted runs checkpoint to
+ * (worker/hosted-agent/checkpoint.ts `checkpointRef`), or null for an id that
+ * is unsafe in a refname.
+ */
+function hostedCheckpointRef(taskId) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId) && !taskId.includes("..")
+        ? `refs/navarch/checkpoints/${taskId}`
+        : null;
+}
 function safePathSegment(value) {
     const safe = value.replace(/[^A-Za-z0-9_.-]/g, "-").replace(/^-+|-+$/g, "");
     if (!safe)

package/dist/prompt.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderPrompt = renderPrompt;
 exports.renderGuidanceCorrectionPrompt = renderGuidanceCorrectionPrompt;
+exports.renderHostedCheckpointNote = renderHostedCheckpointNote;
 const CODE_GRAPH_GUIDANCE = "For JS/TS dependency inspection, the runtime provides `navarch-runtime code-graph --query <symbol-or-file> --mode search|callers|callees|impact --commit HEAD`. If the runtime is not on PATH, use its installed entry point; do not install another copy mid-task. Results describe committed source and include commit/freshness warnings; inspect current files for uncommitted changes and unresolved dependencies.";
 /**
  * Renders the four-layer context bundle (project-plan.md §3.8: steering docs,
@@ -63,3 +64,25 @@ function renderGuidanceCorrectionPrompt(originalPrompt, guidance) {
         "",
     ].join("\n");
 }
+/**
+ * Tells the agent its worktree starts from a hosted attempt's checkpoint
+ * (GitWorktree.restoredHostedCheckpoint), mirroring the hosted side's own
+ * resume note (worker/hosted-agent/checkpoint.ts `buildCheckpointRestoreNote`).
+ */
+function renderHostedCheckpointNote(restored, deliveryBranch) {
+    const changes = restored.changedFiles > 0
+        ? `${restored.changedFiles} file${restored.changedFiles === 1 ? "" : "s"} with uncommitted changes are in the working tree.`
+        : "There are no uncommitted changes.";
+    const hosted = restored.hostedBranch
+        ? ` The hosted agent was working on \`${restored.hostedBranch}\`; its commits are already on \`${deliveryBranch}\`, so deliver from \`${deliveryBranch}\` and do not push \`${restored.hostedBranch}\`.`
+        : "";
+    return [
+        "## Resuming a hosted attempt",
+        "",
+        "A hosted Navarch agent worked on this task before you and was cut off before it delivered.",
+        `Navarch checkpointed its checkout${restored.savedAt ? ` at ${restored.savedAt}` : ""}, and this worktree was restored from it. ${changes}${hosted}`,
+        "",
+        "Start by inspecting that work with `git status`, `git log --oneline`, and `git diff`, then continue from it",
+        "rather than starting over. Discard it only if it is clearly wrong for the task.",
+    ].join("\n");
+}

package/dist/session.cjs

@@ -136,7 +136,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     const workDir = node_path_1.default.join(config.workspaceRoot, "sessions", sessionId);
     await node_fs_1.promises.mkdir(workDir, { recursive: true });
     await (0, worktree_janitor_cjs_1.markSessionWorkspaceActive)(workDir);
-    const promptText = (0, prompt_cjs_1.renderPrompt)(task, bundle);
+    let promptText = (0, prompt_cjs_1.renderPrompt)(task, bundle);
     await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), promptText, "utf8");
     // Secrets: initially fetched once and held in the registry + child env map.
     // The broker-issued github-pat is additionally installed in the project-local
@@ -188,6 +188,11 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         return;
     }
     const githubToken = secrets[bundle.repository?.credential_secret_name ?? "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 gitWorktree = new git_worktree_cjs_1.GitWorktree({
         workspaceRoot: config.workspaceRoot,
         projectId: task.project_id,
@@ -198,12 +203,9 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         cloneUrl,
         githubToken,
         repoLocalGithubToken: secrets["github-pat"],
+        // Hosted runs skip checkpoints for verify tasks, which deliver a verdict.
+        restoreHostedCheckpoint: !allowBranchRename && task.task_type !== "verify",
     });
-    // 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;
@@ -406,9 +408,24 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     lifecycle.enteredMainSessionTry = true;
     try {
         await gitWorktree.prepare();
+        if (gitWorktree.hostedCheckpointRestoreFailure) {
+            log.warn(`hosted checkpoint for ${leaseId} could not be restored: ` +
+                `${(0, redact_cjs_1.redactText)(gitWorktree.hostedCheckpointRestoreFailure, registry.list())}; starting without it.`);
+        }
+        const restoredCheckpoint = gitWorktree.restoredHostedCheckpoint;
+        if (restoredCheckpoint) {
+            log.info(`resumed hosted checkpoint ${restoredCheckpoint.sha.slice(0, 12)} for ${leaseId} ` +
+                `(${restoredCheckpoint.changedFiles} uncommitted file(s)).`);
+            promptText = `${promptText}\n\n${(0, prompt_cjs_1.renderHostedCheckpointNote)(restoredCheckpoint, gitWorktree.branch)}`;
+            await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), promptText, "utf8");
+        }
         // Preparation may resume an existing task branch with an older slug or ID format.
-        if (!allowBranchRename)
+        if (!allowBranchRename) {
             sessionEnv.NAVARCH_DELIVERY_BRANCH = gitWorktree.branch;
+            const marker = gitWorktree.deliveryTaskMarker;
+            if (marker)
+                sessionEnv.NAVARCH_DELIVERY_TASK_MARKER = marker;
+        }
         if (sandbox) {
             await sandbox.create();
             // Security-policy refusals (a mount outside the allowlist, an egress
@@ -432,6 +449,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         let nextPrompt = null;
         let completionRemediationRetries = 0;
         let deliveryCorrectionRetries = 0;
+        let deliveredPullRequest = false;
         while (true) {
             // Guidance can arrive while the worktree/sandbox is being prepared.
             // It is already included in deliveredGuidance, so clear the pending
@@ -561,6 +579,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 catch (err) {
                     delivery = { status: "unknown", reason: `the delivery probe failed: ${String(err)}` };
                 }
+                deliveredPullRequest = delivery.status === "delivered";
                 if (delivery.status === "unknown") {
                     log.warn(`delivery for ${leaseId} could not be verified: ${delivery.reason}; completing anyway.`);
                 }
@@ -641,6 +660,13 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             };
             try {
                 await api.completeLease(leaseId, completion);
+                if (deliveredPullRequest && completion.status === "completed" && gitWorktree.restoredHostedCheckpoint) {
+                    // The pull request carries the hosted attempt's work now; a later
+                    // hosted attempt must not resume the stale snapshot.
+                    await gitWorktree.deleteRestoredHostedCheckpoint().catch((err) => {
+                        log.warn(`hosted checkpoint cleanup failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(String(err), knownSecrets)}`);
+                    });
+                }
                 break;
             }
             catch (err) {

package/package.json

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