@uchibeke/gallivant 0.2.1 → 0.3.0

package/lib/promotion_git.mjs

@@ -0,0 +1,63 @@
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileAsync, transportExecutor } from "./process.mjs";
+import { runEnv } from "./git.mjs";
+import { shellQuote } from "./runtime-environment.mjs";
+
+/** Git's pre-push hook receives the actual advertised old OID. The server then
+ * compares that old OID atomically. This closes the planning/push race without
+ * --force or a lease that could permit a non-fast-forward update. */
+export function pushGuard({ branch, head, previous }) {
+  return `const fs = require('node:fs');
+const rows = fs.readFileSync(0, 'utf8').trim().split('\\n').map(s => s.split(/\\s+/));
+const expected = ${JSON.stringify({ branch, head, previous })};
+if (rows.length !== 1 || rows[0].length !== 4 || rows[0][1] !== expected.head || rows[0][2] !== 'refs/heads/' + expected.branch || rows[0][3] !== (expected.previous || '0'.repeat(expected.head.length))) {
+  process.stderr.write('Promotion target changed: inspect a fresh dry-run plan.\\n'); process.exit(1);
+}`;
+}
+
+/** Isolated object transfer: never checkout/execute repository files or copy
+ * credentials. Each network call gets only that host's existing bound Git auth. */
+export async function makePromotionTransfer(ctx, { execute = execFileAsync } = {}) {
+  const dir = await mkdtemp(join(tmpdir(), "branch-promotion-"));
+  const exec = transportExecutor(execute);
+  const clean = () => Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^(?:GIT_|GH_|GITHUB_|BITBUCKET_|BB_|SSH_|HOST_API_)/.test(key)));
+  const git = async (args, repo = null) => {
+    const credential = repo ? await ctx.hosts.gitCredential(repo) : null;
+    const env = { ...clean(), ...runEnv(ctx.config, credential), GIT_TERMINAL_PROMPT: "0" };
+    const { stdout } = await exec("git", args, { cwd: dir, env, timeout: 300_000 });
+    return stdout.trim();
+  };
+  try { await git(["init", "--bare", "."]); }
+  catch (error) { await rm(dir, { recursive: true, force: true }); throw error; }
+  const fetchRef = async (repo, ref, slot, expected) => {
+    const remote = ctx.hosts.remote(repo);
+    await git(["fetch", "--no-tags", "--no-recurse-submodules", remote.url, `+${ref}:refs/promotion/${slot}`], repo);
+    if (await git(["rev-parse", `refs/promotion/${slot}^{commit}`]) !== expected) throw new Error("Remote Git ref changed or differs from host API evidence; inspect a new plan");
+  };
+  const ancestor = async (before, after) => {
+    try { await git(["merge-base", "--is-ancestor", before, after]); return true; }
+    catch (error) { if (error.code === 1) return false; throw error; }
+  };
+  return {
+    async validate(plan) {
+      await fetchRef(plan.source.repo, `refs/pull/${plan.source.number}/head`, "source", plan.source.head);
+      await fetchRef(plan.source.repo, plan.source.baseHead, "source-base", plan.source.baseHead);
+      await fetchRef(plan.target.repo, `refs/heads/${plan.target.base}`, "target-base", plan.target.baseHead);
+      if (plan.target.head) await fetchRef(plan.target.repo, `refs/heads/${plan.target.branch}`, "target", plan.target.head);
+      if (!await ancestor(plan.source.baseHead, plan.source.head)) throw new Error("Source branch does not contain its reviewed base; reconcile and review before promotion");
+      const sourceTree = await git(["rev-parse", `${plan.source.baseHead}^{tree}`]);
+      const targetTree = await git(["rev-parse", `${plan.target.baseHead}^{tree}`]);
+      if (sourceTree !== targetTree) throw new Error("Source reviewed base and Bitbucket base trees differ; reconcile on GitHub and review again before promotion");
+      if (plan.target.head && !await ancestor(plan.target.head, plan.source.head)) throw new Error("Bitbucket branch diverged; promotion never force-pushes or rewrites history");
+    },
+    async push(plan) {
+      const hooks = join(dir, "promotion-hooks");
+      await mkdir(hooks, { recursive: true });
+      await writeFile(join(hooks, "pre-push"), `#!/bin/sh\nexec ${shellQuote(process.execPath)} --input-type=commonjs -e ${shellQuote(pushGuard({ branch: plan.target.branch, head: plan.source.head, previous: plan.target.head }))}\n`, { mode: 0o700 });
+      await git(["-c", `core.hooksPath=${hooks}`, "push", "--no-follow-tags", ctx.hosts.remote(plan.target.repo).url, `${plan.source.head}:refs/heads/${plan.target.branch}`], plan.target.repo);
+    },
+    close: () => rm(dir, { recursive: true, force: true }),
+  };
+}

package/lib/prompt.mjs

@@ -1,3 +1,4 @@
+import { hostPrompts } from "./host_definitions.mjs";
 // Prompt builders. Anything that came from GitHub (comment bodies, review text) is quoted inside a four-backtick
 // fence with internal fences neutralised, and capped, so it reads as data. That is hygiene, not a control; the
 // controls are the sandbox, the token scope and the ruleset (PRD 6.11).
@@ -38,6 +39,7 @@ const indent = (s, n = 4) => s.split("\n").map(l => " ".repeat(n) + l).join("\n"
 // Deliberately not worded as distrust: the same session's instinct to verify a pre-existing failure was the right one.
 const BASE_RULE = "Do not merge. Do not touch the default branch. Do not force-push, and do not rebase: keeping this branch on its base is done for you.";
 const RULES = [
+  "Collect final exit status and verification results before returning. A background task or monitor cannot resume this worker after its process exits. Run finite checks in the foreground with a sufficient explicit timeout within the approved limits; do not substitute a watch or deferred notification for a completed check. If a task needs a temporary development server, keep its lifecycle within this run, collect its test results and stop it before returning. Never report partial output as a passed check. Gallivant owns durable wakeups and remote review polling.",
   "Open a regular pull request for review, never a draft: do not use --draft or convert the PR to draft. A regular PR is not a claim of completion; retain false acceptance criteria and outstanding verification honestly until they are resolved.",
   "Public PR titles, descriptions, completion-receipt prose, review replies, issue comments and commit messages must describe the work without mentioning Gallivant (in any letter case). Do not add runner branding or attribution. Use the supplied neutral receipt format; recovery metadata is managed for you. Keep internal paths, session identifiers and logs intact. Do not rewrite evidence URLs: cite a different accurate evidence pointer when needed.",
   "Before pushing, review the changed source and representative generated output against the approved brief. For each justified finding, identify the underlying rule and check its sibling callers, input/output boundaries and failure/cleanup paths already in scope. Fix related occurrences together, reuse existing validation and runner helpers, and add focused regression coverage that reproduces the defect. Do not expand the brief or add unrelated refactors to satisfy speculative review concerns.",
@@ -47,6 +49,7 @@ const RULES = [
   "Do not run `git stash` in any form. The stash stack is shared by every worktree of this repository, so a push can sweep up untracked files and a pop can drop another worktree's work into yours, and nothing in this run records that it happened. To check whether a failure is yours or was already there, get a second tree instead of moving this one: `git worktree add <temp path> <base>` and run the check there, or read a single file at the base with `git show <base>:<path>`.",
   "A denied tool call is a boundary, not an obstacle. If a guardrail blocks something, do not write a wrapper script, re-spell the command, move it into a file, or find another path to the same effect: stop that line of work and say in your final message what was blocked and what you were trying to do. The block may well be wrong, and the operator can only fix it if they hear about it; a way around it leaves them with neither the check nor the report.",
   "A sandbox permission error is different from a guardrail refusal. Codex protects .git even inside a writable checkout. For an authorized Git operation that needs it, use the tool's supported approval/escalation request; Gallivant routes Codex requests through automatic review. If the reviewer or a guardrail denies it, stop and report the denial. Do not change permissions, move Git metadata, or bypass the sandbox.",
+  "Commit only the requested product changes, tests and durable documentation. Do not commit task work files, session logs, scratch files, audit history, review notes or handoff notes. Create scratch space outside the repository with mktemp -d. Summarize verification in the PR receipt; full command/session logs are retained by the runner. Keep durable release and rollback instructions concise. Exact report or evidence deliverables listed in publish_files in the approved brief are allowed; a session must not add its own exceptions or rename work logs to evade the policy. Inspect the complete branch diff as well as staged paths before pushing.",
   "Commit with clear messages and push to this branch when done. Keep Git writes in separate tool calls from file-generation scripts, and stop on command failures. Check the staged diff before committing. After pushing, verify that the remote branch matches HEAD and that the upstream is origin/this branch; a push can exit zero even when writing local tracking metadata failed. Report any unfinished step explicitly.",
   // The half a git hook cannot reach. A commit message is a local file the `commit-msg` hook reads before a commit object
   // exists; a local agent can write a PR body directly over the network. Public-output checks guard coordinator
@@ -60,7 +63,7 @@ const RULES = [
  * branch, which is what this parameter used to be called and used to assume. A project whose pull requests all go to
  * `staging` was told to open one against `main`, and the session did as it was told.
  */
-export function startPrompt({ prd, repo, branch, base, verify, receipt = null, carried = [] }) {
+export function startPrompt({ prd, repo, branch, base, verify, receipt = null, carried = [], host = hostPrompts(repo) }) {
   const verifyBlock = verify.length ? `Before opening the PR, run these Verify commands and make them pass:\n${verify.map(v => `- ${v}`).join("\n")}` : "Run the project's tests before opening the PR.";
   // What the carried files ARE, said before the brief so a session reads them as given rather than as work. Without
   // this a session finds documents in its checkout that are in no commit and are not mentioned in the diff it is about
@@ -70,14 +73,14 @@ export function startPrompt({ prd, repo, branch, base, verify, receipt = null, c
     "",
     `These files were carried in from the operator's own checkout because the brief names them:`,
     ...carried.map(f => `- ${f}`),
-    "They are part of the brief, not work to be done. Read them; do not rewrite them to match what you expected.",
+    "They are part of the brief, not work to be done. Read them; do not rewrite them to match what you expected. Keep carried inputs local and untracked unless the approved brief explicitly lists them in publish_files. Never delete a carried input needed by the brief.",
   ].join("\n") : null;
   return cap([
     `You are implementing a PRD in ${repo} on branch \`${branch}\` (base: \`${base}\`). You are in a git worktree for that branch.`,
     "Read the PRD below, implement every user story so every acceptance criterion holds, and keep the change focused on what the PRD asks.",
     verifyBlock,
     ...(carriedBlock ? [carriedBlock] : []),
-    `Then open one pull request with \`gh pr create --base ${base} --head ${branch}\`. Title it after the PRD. In the body, summarise what changed and how you verified it, and link the PRD file.`,
+    `Then open one pull request with \`${host.create({ base, branch })}\`. Title it after the PRD. In the body, summarise what changed and how you verified it, and link the PRD file.`,
     ...(receipt ? ["", receipt] : []),
     ...RULES,
     "",
@@ -86,10 +89,10 @@ export function startPrompt({ prd, repo, branch, base, verify, receipt = null, c
   ].join("\n"));
 }
 
-export function registerPrompt({ repo, pr }) {
+export function registerPrompt({ repo, pr, host = hostPrompts(repo) }) {
   return cap([
     `You are taking over pull request #${pr} in ${repo}. You are in a git worktree on the PR branch.`,
-    `Run \`gh pr view ${pr} --repo ${repo}\` and \`gh pr diff ${pr} --repo ${repo}\` to understand it before changing anything.`,
+    host.inspect({ repo, pr }),
     ...RULES,
     "Do not open new PRs.",
   ].join("\n"));
@@ -111,10 +114,10 @@ export function registerPrompt({ repo, pr }) {
  * seen, which reads to the agent as the gate being broken. So each difference is listed and the session is told to reread
  * the brief in the worktree rather than trust what it remembers.
  */
-export function resumePrompt({ repo, pr, base = null, branch = null, reason, note = null, verify = [], receipt = null, briefChanged = [], unpushed = [], merged = null, uncommitted = null, carried = [] }) {
+export function resumePrompt({ repo, pr, base = null, branch = null, reason, note = null, verify = [], receipt = null, briefChanged = [], unpushed = [], merged = null, uncommitted = null, carried = [], host = hostPrompts(repo) }) {
   const deferredBaseRule = [
     "Do not merge a pull request or write to the default/base branch. Do not force-push or rebase.",
-    `The automatic base merge was deferred to preserve unfinished files. After committing only the task's changes, fetch origin and merge ${base ? `\`origin/${base}\`` : "the PR's target base (confirm it with GitHub first)"} into this task branch before verification and push. This base-into-task merge is the only merge authorized for this run.`,
+    `The automatic base merge was deferred to preserve unfinished files. After committing only the task's changes, fetch origin and merge ${base ? `\`origin/${base}\`` : "the PR's target base (confirm it with the host first)"} into this task branch before verification and push. This base-into-task merge is the only merge authorized for this run.`,
     "Give that merge the neutral message `Merge approved base into task branch` with git merge -m; the default generated message can expose a legacy branch prefix and is refused by the commit-message hook.",
     "Preserve unrelated edits and carried instructions. If they prevent the merge, stop and report the exact conflicting paths; do not stash, discard or commit those files to force it through. Resolve merge conflicts only within the approved task scope, then rerun the Verify commands on the combined result before pushing.",
   ].join(" ");
@@ -128,12 +131,12 @@ export function resumePrompt({ repo, pr, base = null, branch = null, reason, not
     // no-reason-recorded default.
     "no-push": "your last run ended without pushing anything",
     "harness-error": "your last run ended with an error",
-    stuck: "a GitHub write kept failing and has now been dealt with",
+    stuck: "a repository-host write kept failing and has now been dealt with",
     "checks-red": "checks were red and a person has now looked",
     "reviewer-blocking": "the reviewer was blocking and a person has now looked",
     "reviewer-silent": "the reviewer went quiet and a person has now looked",
     "context-paths": "the read directories the brief asked for could not be granted and have now been settled",
-    "no-credential": "no GitHub credential could be resolved, so the push would have failed; one is available now",
+    "no-credential": "no repository credential could be resolved, so the push would have failed; one is available now",
     "no-identity": "this machine had no git identity, so every commit you made would have failed; one is configured now",
     uncommitted: "unfinished work remains in the checkout; inspect and preserve it before continuing",
   }[reason] ?? `your last run stopped (${reason ?? "no reason recorded"})`;
@@ -172,7 +175,7 @@ export function resumePrompt({ repo, pr, base = null, branch = null, reason, not
     "",
     "If you were part way through something, finish it. If you were about to run the checks, run them.",
     verify.length ? `The Verify commands that must pass:\n${verify.map(v => `- ${v}`).join("\n")}` : "Run the project's tests and make them pass.",
-    pr ? "Push to this branch when the work is done. Do not open new PRs." : `Then open one pull request for this branch${base && branch ? ` with \`gh pr create --base ${base} --head ${branch}\`` : ""}. Title it after the brief, and in the body summarise what changed and how you verified it.`,
+    pr ? "Push to this branch when the work is done. Do not open new PRs." : `Then open one pull request for this branch${base && branch ? ` with \`${host.create({ base, branch })}\`` : ""}. Title it after the brief, and in the body summarise what changed and how you verified it.`,
     ...(receipt ? ["", receipt] : []),
     ...RULES.map(rule => uncommitted && rule === BASE_RULE ? deferredBaseRule : rule),
   ].join("\n"));
@@ -182,7 +185,7 @@ export function resumePrompt({ repo, pr, base = null, branch = null, reason, not
  * One prompt per batch of events. Events are the normalised objects from events.mjs:
  * { kind: "review"|"inline"|"command"|"check", author, state?, id?, path?, line?, body?, name?, runId? }
  */
-export function fixPrompt({ repo, pr, headSha, events, verify, receipt = null, denials = null, merged = null }) {
+export function fixPrompt({ repo, pr, headSha, events, verify, receipt = null, denials = null, merged = null, host = hostPrompts(repo) }) {
   const reviews = groupReviews(events.filter(e => e.kind === "review" || e.kind === "inline"));
   const checks = events.filter(e => e.kind === "check");
   const commands = events.filter(e => e.kind === "command");
@@ -204,7 +207,7 @@ export function fixPrompt({ repo, pr, headSha, events, verify, receipt = null, d
   }
   if (checks.length) {
     parts.push("", `Checks failing on ${headSha ? headSha.slice(0, 7) : "the head"}:`);
-    for (const c of checks) parts.push(`- ${c.name}${c.runId ? `, run ${c.runId}. Run \`gh run view ${c.runId} --repo ${repo} --log-failed\` for the log.` : `. See ${c.url || "the checks tab"}.`}`);
+    for (const c of checks) parts.push(`- ${c.name}${host.check({ repo, check: c })}`);
   }
   if (commands.length) {
     parts.push("", "Requests from the operator:");
@@ -218,7 +221,7 @@ export function fixPrompt({ repo, pr, headSha, events, verify, receipt = null, d
     ...RULES,
     "Reply to each inline thread with one line on what you changed or why you did not.",
     "Do not open new PRs.",
-    "If only the completion receipt in the PR body needed fixing, edit the PR body with `gh pr edit` and do not push an empty commit.",
+    host.editReceipt,
   );
   return cap(parts.join("\n"));
 }

package/lib/provider_health.mjs

@@ -1,6 +1,17 @@
 import { join } from "node:path";
 import { readJson, writeJsonAtomic } from "./fs.mjs";
 import { boundedCall, EXECUTION_LIMITS, nextAttempt } from "./execution_io.mjs";
+// A coordinator cycle can outlast the ten-second execution progress cadence.
+// Keep a successful probe usable for five bounded minutes by default; an explicit
+// operator progress interval remains authoritative.
+export const coordinatorHealthLimits = execution => ({ ...execution, progressMs: execution?.progressMs ?? 300_000 });
+// Provider probes need their own lane: an unrelated slow coordinator tick must
+// not prevent a due account check from refreshing. makeProviderHealth coalesces
+// concurrent probes and still fences dispatch while a refresh is pending.
+export function scheduleProviderHealth(health, scopes, { intervalMs, onError = () => {}, schedule = setInterval, cancel = clearInterval } = {}) {
+  const timer = schedule(() => { Promise.resolve().then(() => health.refresh(scopes)).catch(onError); }, intervalMs);
+  return () => cancel(timer);
+}
 export function makeProviderHealth({ home, file = join(home, "provider-health.json"), clock = Date, limits = {}, probe, jitter = Math.random }) {
   const bounds = { ...EXECUTION_LIMITS, ...limits }, pending = new Map();
   const key = (provider, account) => JSON.stringify([provider, account]);
@@ -12,11 +23,11 @@ export function makeProviderHealth({ home, file = join(home, "provider-health.js
   const get = (provider, account = "operator") => {
     const s = read();
     const id = key(provider, account), saved = s.scopes[id];
-    if (!saved) return { ok: false, detail: "provider/account check pending" };
+    if (!saved) return { ok: false, pending: true, detail: "provider/account check pending" };
     // Fence due scopes before refresh starts, including those waiting for a
     // probe worker. A read never probes; restart uses the same saved deadline.
-    if (saved.ok && (pending.has(id) || clock.now() >= (saved.nextAttemptAt ?? saved.observedAt + bounds.progressMs))) return { ...saved, ok: false, detail: "provider/account health refresh pending; awaiting the coordinator's next probe" };
-    if (saved.ok && clock.now() > saved.observedAt + bounds.progressMs * 2) return { ...saved, ok: false, detail: "provider/account health is stale; awaiting the coordinator's next probe" };
+    if (saved.ok && (pending.has(id) || clock.now() >= (saved.nextAttemptAt ?? saved.observedAt + bounds.progressMs))) return { ...saved, ok: false, pending: true, detail: "provider/account health refresh pending; awaiting the coordinator's next probe" };
+    if (saved.ok && clock.now() > saved.observedAt + bounds.progressMs * 2) return { ...saved, ok: false, pending: true, detail: "provider/account health is stale; awaiting the coordinator's next probe" };
     return saved;
   };
   const refresh = async scopes => {

package/lib/repository.mjs

@@ -0,0 +1,68 @@
+// Repository identity is independent of transport, execution provider and harness.
+// Bare owner/name is the persisted v1 GitHub spelling; other hosts are qualified.
+export const LEGACY_HOST = "github.com";
+export function assertBranchName(value) {
+  if (typeof value !== "string" || !value || value.startsWith("-") || /[\s~^:?*\[\\\x00-\x1f\x7f]/.test(value) || value.includes("..") || value.includes("@{") || value === "@" || value.split("/").some(p => !p || p.startsWith(".") || p.endsWith(".") || p.endsWith(".lock"))) throw new Error("Invalid Git branch name; select an explicit branch before repository transport");
+  return value;
+}
+const segment = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*$/;
+const hostname = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/;
+const invalid = () => new Error("Invalid repository origin or identity; restore a canonical HTTPS or Git SSH origin and retry. Credentials in URLs are never included in diagnostics.");
+// Cloud's SSH endpoint is a transport alias, never a separate repository identity.
+const sshIdentityHosts = { "ssh.bitbucket.org": "bitbucket.org" };
+const sshTransportHosts = { "bitbucket.org": "ssh.bitbucket.org" };
+
+export function repositoryIdentity(value, host = LEGACY_HOST) {
+  if (value && typeof value === "object") {
+    const identity = repositoryIdentity(value.path ?? value.repo, value.host ?? host);
+    if (value.host && identity.host !== value.host.toLowerCase()) throw invalid();
+    return identity;
+  }
+  if (typeof value !== "string") throw invalid();
+  const parts = value.split("/");
+  if (parts.length === 3) host = parts.shift();
+  host = String(host).toLowerCase();
+  if (!hostname.test(host) || parts.length !== 2 || parts.some(p => !segment.test(p) || p === "." || p === "..")) throw invalid();
+  const path = parts.join("/").toLowerCase();
+  return Object.freeze({ host, path, remoteIdentity: `${host}/${path}`, key: host === LEGACY_HOST ? path : `${host}/${path}` });
+}
+
+/** Parse without URL normalization hiding traversal, ports, query strings or escapes. */
+export function parseRemote(value) {
+  const raw = typeof value === "string" ? value.trim().replace(/\/+$/, "") : "";
+  if (!raw || /[\s\\?#%\x00-\x1f\x7f]/.test(raw)) throw invalid();
+  let match, transport;
+  // HTTP is retained for historical GitHub remotes, but the adapter upgrades it before use.
+  if ((match = raw.match(/^(https?):\/\/(?:[^/@]+@)?([^/:@]+)\/([^/]+\/[^/]+)$/i))) transport = match[1].toLowerCase();
+  else if ((match = raw.match(/^(ssh):\/\/(?:[A-Za-z0-9._-]+@)?([^/:@]+)\/([^/]+\/[^/]+)$/i))) transport = "ssh";
+  else {
+    const scp = raw.match(/^(?:[A-Za-z0-9._-]+@)?([^/:@]+):([^/]+\/[^/]+)$/i);
+    if (!scp) throw invalid();
+    match = [raw, "ssh", scp[1], scp[2]]; transport = "ssh";
+  }
+  const host = match[2].toLowerCase();
+  const identity = repositoryIdentity(match[3].replace(/\.git$/i, ""), transport === "ssh" ? sshIdentityHosts[host] ?? host : host);
+  return Object.freeze({ ...identity, transport, url: transport === "ssh" ? `git@${sshTransportHosts[identity.host] ?? identity.host}:${identity.path}.git` : `https://${identity.host}/${identity.path}.git` });
+}
+
+export const safeOrigin = value => { try { return parseRemote(value).url; } catch { return "[invalid origin]"; } };
+export const repositoryMatches = (a, b) => { try { return repositoryIdentity(a).remoteIdentity === repositoryIdentity(b).remoteIdentity; } catch { return false; } };
+export const remoteMatches = (url, repo) => { try { return parseRemote(url).remoteIdentity === repositoryIdentity(repo).remoteIdentity; } catch { return false; } };
+export const repoFromRemote = url => { try { return parseRemote(url).key; } catch { return null; } };
+
+export function parsePullRequestUrl(value) {
+  // Host adapters own the PR route. This parses only the URL envelope, never userinfo.
+  const m = typeof value === "string" && value.match(/^https:\/\/([^/:@]+)\/([^?#\s\\%]+)$/i);
+  if (!m || !hostname.test(m[1].toLowerCase())) throw invalid();
+  return { host: m[1].toLowerCase(), pathname: m[2] };
+}
+
+/** Read old records without rewriting IDs, cursors or counters. Contradictions require recovery. */
+export function savedRepository(entry) {
+  const identity = repositoryIdentity(entry.repo);
+  if ((entry.host && entry.host !== identity.host) || (entry.repository && repositoryIdentity(entry.repository).remoteIdentity !== identity.remoteIdentity) ||
+      (entry.url && (parsePullRequestUrl(entry.url).host !== identity.host || !parsePullRequestUrl(entry.url).pathname.toLowerCase().startsWith(`${identity.path}/`)))) {
+    throw new Error("Ambiguous saved repository identity; stop the coordinator, back up state, and reconcile its repository, host and PR URL before retrying. Do not redispatch.");
+  }
+  return identity;
+}

package/lib/repository_preflight.mjs

@@ -0,0 +1,11 @@
+import { makeGit } from "./git.mjs";
+import { makeHostRegistry } from "./hosts.mjs";
+import { configuredBase } from "./config.mjs";
+
+/** Transport readiness is independent of dispatch qualification. It makes no remote writes. */
+export async function repositoryPreflight(config, repo, { registry = makeHostRegistry({ config }), git = makeGit({ config, hosts: registry }), base = configuredBase(config, repo) } = {}) {
+  const selected = registry.inspect(repo);
+  if (!selected.api.preflight) throw new Error("This host uses its existing setup diagnostics");
+  const report = await selected.api.preflight(selected.repository.path, { base });
+  return { ...report, ...await git.probeAccess(repo, report.base, report.baseSha), dispatch: selected.adapter.dispatch !== false, guidance: selected.adapter.dispatchReason ?? null };
+}

package/lib/review_evaluation.mjs

@@ -0,0 +1,25 @@
+// Offline metrics over captured, independently adjudicated review outputs.
+// Seed labels alone cannot manufacture live judgement or baseline evidence.
+export function evaluateReviews(corpus, runs, baseline) {
+  if (corpus?.version !== 1 || !Array.isArray(corpus.cases) || !corpus.cases.length) throw new Error("versioned held-out corpus required");
+  const score = records => {
+    if (!Array.isArray(records) || records.length !== corpus.cases.length || new Set(records.map(r=>r.caseId)).size !== records.length) throw new Error("one recorded result per held-out case is required");
+    let detected=0, defects=0, falsePositives=0, clean=0, latencyMs=0, costUsd=0, unknownCost=0;
+    for (const c of corpus.cases) {
+      const r=records.find(r=>r.caseId===c.id);
+      if (!r || !r.evidence || !["clear","findings","failed","incomplete"].includes(r.verdict) || !Array.isArray(r.detectedDefects) || !Number.isFinite(r.latencyMs) || r.latencyMs<0 || r.costUsd!==null && (!Number.isFinite(r.costUsd) || r.costUsd<0)) throw new Error("each result needs verifiable evidence, adjudicated defects, latency and explicit cost/unknown");
+      const accepted=new Set(r.detectedDefects);
+      if (accepted.size!==r.detectedDefects.length || [...accepted].some(id=>!c.defects.includes(id)) || r.verdict!=="findings" && accepted.size) throw new Error("detection IDs must be independently adjudicated against the held-out case");
+      defects+=c.defects.length; detected+=accepted.size;
+      if (!c.defects.length) { clean++; if (r.verdict==="findings") falsePositives++; }
+      latencyMs+=r.latencyMs;
+      if (r.costUsd===null) unknownCost++; else costUsd+=r.costUsd;
+    }
+    return { detected, defects, defectDetection: defects?detected/defects:null, falsePositives, clean, falsePositiveRate:clean?falsePositives/clean:null,
+      meanLatencyMs:latencyMs/records.length, knownSpendUsd:costUsd, unknownSpendRuns:unknownCost, failures:records.filter(r=>["failed","incomplete"].includes(r.verdict)).length };
+  };
+  const measured = score(runs);
+  if (!baseline) return { status:"baseline-missing", firstParty:measured, baseline:null, defaultChangeJustified:false };
+  if (!["external-review","human-reviewed"].includes(baseline.kind) || !baseline.evidence) throw new Error("an external-review or human-reviewed baseline evidence pointer is required");
+  return { status:"measured", firstParty:measured, baseline:{kind:baseline.kind,evidence:baseline.evidence,...score(baseline.runs)}, defaultChangeJustified:false };
+}