@sagentlab/navarch-runtime 0.1.28 → 0.1.30

package/README.md

@@ -22,7 +22,34 @@ the API contract.
 For a project machine, use the command generated by **Onboard → Connect an
 agent** or **Project settings → Connect an agent**. It includes a single-use,
 project-scoped enrollment token and the correct control-plane origin. The
-recommended npm package requires Node.js 20 or later:
+recommended npm package requires Node.js 20 or later.
+
+Before generating the command, prepare the machine:
+
+- install Node.js 20 or later (the standard installation includes `npm` and
+  `npx`) and Git;
+- install the coding-agent CLI selected in Navarch — `claude`, `codex`,
+  `gemini`, or `opencode` — and complete its normal authentication flow; and
+- for Docker-backed sessions, install and start Docker and use an image that
+  contains the selected agent CLI and the repository toolchain, with provider
+  credentials supplied through the approved machine or project configuration.
+
+The generated command installs/runs only the Navarch runtime. It does not
+install Git, Docker, or a coding-agent CLI, and it cannot sign in to the agent
+provider for you. Verify the host path before enrollment (substitute the CLI
+selected in the UI):
+
+```sh
+node --version       # 20 or later
+npm --version
+npx --version
+git --version
+codex --version      # or: claude --version / gemini --version / opencode --version
+```
+
+Every command above must succeed before the long-running worker starts. See
+[Choosing an agent](#choosing-an-agent) for runtime-specific environment
+variables and isolation requirements.
 
 ```sh
 # Run the two commands copied from Navarch. Their values resemble:
@@ -516,7 +543,9 @@ contract used by `api.cts`, including:
    distinct from the per-lease heartbeat, needed because `machines.last_heartbeat_at`
    /`status` must update even when no task is claimed.
 3. **`POST /api/dispatch/:leaseId/transcript-upload-url`** — a signed
-   Supabase Storage upload URL for the session's redacted transcript.
+   Supabase Storage upload URL for the session's redacted transcript. The
+   bucket is private; the legacy `public_url` response field is only an
+   attested locator returned at completion, not an anonymous read URL.
 
 `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.

package/dist/github-pr.cjs

@@ -41,9 +41,11 @@ function matchingPullRequestUrl(body, repository, matchesHead) {
     const candidate = matches.find((pullRequest) => pullRequest.state === "open") ?? matches[0];
     return typeof candidate?.html_url === "string" ? candidate.html_url : null;
 }
-async function fetchPullRequests(url, headers, fetchImpl) {
+async function fetchPullRequests(url, headers, fetchImpl, options = {}) {
     const response = await fetchImpl(url, { headers });
     if (!response.ok) {
+        if (options.emptyStatuses?.includes(response.status))
+            return [];
         throw new Error(`GitHub pull request lookup failed with HTTP ${response.status}`);
     }
     return response.json();
@@ -87,7 +89,11 @@ async function findHeadBranchPullRequestUrl(options) {
         return branchMatch;
     const commitUrl = new URL(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/commits/${normalizedHeadSha}/pulls`);
     commitUrl.searchParams.set("per_page", "10");
-    return matchingPullRequestUrl(await fetchPullRequests(commitUrl, headers, fetchImpl), normalizedRepository, (candidate) => typeof candidate.head?.sha === "string" &&
+    return matchingPullRequestUrl(
+    // GitHub answers 422 ("No commit found for SHA") when the local head was
+    // never pushed -- the normal case for sessions that end without a PR, so
+    // it means "no evidence", not a lookup failure.
+    await fetchPullRequests(commitUrl, headers, fetchImpl, { emptyStatuses: [404, 422] }), normalizedRepository, (candidate) => typeof candidate.head?.sha === "string" &&
         candidate.head.sha.toLowerCase() === normalizedHeadSha);
 }
 function isPullRequestUrlForRepository(value, repository) {

package/dist/session.cjs

@@ -637,6 +637,10 @@ const REMEDIABLE_REJECTION_CODES = new Set([
     // The marker is already on the right head; the reviewer only has to relabel
     // the body, which is exactly what a remediation turn can do.
     "review_evidence_mislabeled",
+    // GitHub could not prove the native review's edit provenance. The control
+    // plane keeps the lease active and still fails closed; another turn retries
+    // the check without consuming a task retry as a crashed session.
+    "review_attestation_unavailable",
     // A verify agent that exited zero without the mandated leading
     // `Verification verdict:` line only has to restate its report; the
     // rejection prose spells out the exact format. Failed outcomes never reach

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, Gemini, or OpenCode.",
   "type": "commonjs",
   "license": "MIT",