@uchibeke/gallivant 0.2.0 → 0.3.0

package/lib/commands/init.mjs

@@ -1,34 +1,287 @@
-import { mkdirSync, openSync, closeSync, writeFileSync, existsSync, lstatSync } from "node:fs";
+// `gallivant init`: set up the repository you are standing in, then hand over to `doctor`.
+//
+// Explicit setup only. It never signs in for you, never reads a password or token, never touches global harness
+// settings, credentials or repository permissions, and never rewrites a key the operator wrote. Repeating it is safe:
+// an existing config keeps every value as written and gains at most one `repos` entry, the one for this checkout.
+//
+// Every prerequisite is checked before anything is written, so a signed-out `gh`, a signed-out harness or a checkout
+// that is not a GitHub repository stops the command with the exact action and leaves no partial state behind.
+import { mkdirSync, openSync, closeSync, writeFileSync, lstatSync, realpathSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { gallivantHome, expand, templatePath } from "../fs.mjs";
-import { discoverHarnesses, validate, merge } from "../config.mjs";
-import { makeGh } from "../gh.mjs";
+import { execFileSync } from "node:child_process";
+import { isDeepStrictEqual } from "node:util";
+import { gallivantHome, expand, templatePath, readJson, writeJsonAtomic, contract, VERSION, PACKAGE_NAME } from "../fs.mjs";
+import { discoverHarnesses, validate, merge, configPath, repoEntry } from "../config.mjs";
+import { hosts, makeHostRegistry } from "../hosts.mjs";
+import { repositoryReviewConfig } from "../review_policy.mjs";
+import { safeOrigin, assertBranchName } from "../repository.mjs";
+export { safeOrigin };
 import { silentLog } from "../log.mjs";
+import { checkHarness } from "../probe.mjs";
+import { describe as describeCredential } from "../credential.mjs";
+import { doctor as runDoctor, repositoryWriteScopeCheck } from "./doctor.mjs";
+import { acquireCliMutation } from "../daemon.mjs";
+import { repositoryPreflight } from "../repository_preflight.mjs";
 
-// Explicit setup only; never rewrite an existing config or touch global harness
-// settings, credentials or repository permissions.
-export async function init({ home = gallivantHome(), harness = "codex", login, worktrees,
-  discover = discoverHarnesses, user = () => makeGh({ log: silentLog }).user() } = {}) {
-  if (!["codex", "claude"].includes(harness)) throw new Error("init supports --harness codex or claude; configure other adapters explicitly after checking docs/install.md");
+export const INIT_HARNESSES = ["codex", "claude"];
+
+/** Every message that stops setup ends with this, so nobody reads a stopped run as a half-finished one. */
+const NOTHING_WRITTEN = "Setup did not complete and nothing was written.";
+
+const firstLine = e => String(e?.message || e).split("\n")[0];
+const isSymlink = p => { try { return lstatSync(p).isSymbolicLink(); } catch { return false; } };
+
+/**
+ * The repository a checkout belongs to, read from its `origin` remote. Local only: no network, no `gh`. Throws a
+ * message naming the unmet prerequisite, so a directory that is not a GitHub checkout is refused before anything else
+ * runs. `owner/name` is lowercased as `repoFromRemote` does, which is also how `rememberRepo` and `doctor` spell it.
+ */
+export function targetRepository(dir = process.cwd(), exec = execFileSync) {
+  const git = args => {
+    try { return exec("git", args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10_000 }).trim(); }
+    catch (e) {
+      if (e?.code === "ENOENT") throw new Error(`git is not on PATH. Install Git, then rerun gallivant init. ${NOTHING_WRITTEN}`);
+      return null;
+    }
+  };
+  const checkout = git(["rev-parse", "--show-toplevel"]);
+  if (!checkout) throw new Error(`${dir} is not inside a Git checkout. Run gallivant init from the repository you want to set up (cd into it first). ${NOTHING_WRITTEN}`);
+  const origin = git(["remote", "get-url", "origin"]);
+  if (!origin) throw new Error(`${checkout} has no origin remote. Create the repository on GitHub and add it (git remote add origin https://github.com/<owner>/<name>.git), then rerun gallivant init. ${NOTHING_WRITTEN}`);
+  let repo;
+  try { repo = hosts.inspectRemote(origin).repository.key; }
+  catch (error) { throw new Error(`${error.message} ${NOTHING_WRITTEN}`); }
+  // The redacted form is the only one returned: nothing downstream needs the credential, and nothing may print it.
+  return { checkout, origin: safeOrigin(origin), repo };
+}
+
+/** Infer a harness only when there is one local choice; otherwise setup requires an explicit selection. */
+const onlyLocalHarness = raw => {
+  const names = Object.keys(raw?.harness || {}).filter(n => INIT_HARNESSES.includes(n));
+  return names.length === 1 ? names[0] : null;
+};
+
+/** `checkHarness` reads expanded paths, as `load` would hand them over; a raw config may still spell them with `~`. */
+const expandedFor = (config, name) => {
+  const h = config.harness[name];
+  return { ...config, harness: { ...config.harness, [name]: { ...h, bin: expand(h.bin), ...(h.settings ? { settings: expand(h.settings) } : {}) } } };
+};
+
+/**
+ * Options:
+ *   home       the Gallivant home; `config.json` lives here
+ *   harness    `codex` or `claude`; null keeps an existing config's harnesses and defaults a new one to codex
+ *   worktrees  where task checkouts go; refused when an existing config already chose a different directory
+ *   dir        the target checkout; the repository it belongs to is what gets recorded
+ * The rest are injected for tests: harness discovery, the operator's own `gh` (used only to name the login), the
+ * credential resolver and the `gh` built from what it resolves, repository resolution, the readiness check and `doctor`.
+ */
+export async function init(options = {}) {
+  for (let attempt = 0; ; attempt++) {
+    try { return await initAttempt(options); }
+    catch (error) {
+      if (error.code !== "INIT_CONFIG_CHANGED" || attempt >= 2) throw error;
+    }
+  }
+}
+
+async function initAttempt({ home = gallivantHome(), harness = null, worktrees = null, hostConfig = null, base = null, dir = process.cwd(),
+  discover = discoverHarnesses, gh = null, repository = targetRepository, harnessCheck = checkHarness, doctor = runDoctor,
+  resolve = null, ghFor = null, transportPreflight = repositoryPreflight } = {}) {
+  if (harness != null && !INIT_HARNESSES.includes(harness)) throw new Error("init supports --harness codex or claude; configure other adapters explicitly after checking docs/install.md");
   home = expand(home);
-  const file = join(home, "config.json");
-  if (existsSync(file)) throw new Error(`Config already exists at ${file}; edit it or run gallivant doctor. Nothing was overwritten.`);
-  for (let dir = home; ; dir = dirname(dir)) {
-    if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) throw new Error(`Setup directory must not be a symlink: ${dir}`);
-    if (dirname(dir) === dir) break;
-  }
-  const selected = discover(home)[harness];
-  if (!selected) throw new Error(`${harness} is not on PATH. Install it and sign in, then retry gallivant init --harness ${harness}`);
-  const ownLogin = login || await user();
-  if (!/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(ownLogin || "")) throw new Error("Sign in with gh auth login before running init");
-  const config = { trusted_authors: [ownLogin], worktrees: expand(worktrees || join(dirname(home), ".gallivant-worktrees")),
-    harness: { [harness]: selected }, notify: null, github_token_file: null, repos: [] };
-  const problems = validate(merge(config, home), home);
-  if (problems.length) throw new Error(problems.join("; "));
+  const file = configPath(home);
+  // `lstat` rather than `exists`: a dangling symlink does not exist and is still a symlink.
+  for (let d = home; ; d = dirname(d)) {
+    if (isSymlink(d)) throw new Error(`Setup directory must not be a symlink: ${d}. ${NOTHING_WRITTEN}`);
+    if (dirname(d) === d) break;
+  }
+  const missing = Symbol("missing config");
+  const raw = readJson(file, missing);
+  const existing = raw !== missing;
+  if (existing && (raw === null || typeof raw !== "object" || Array.isArray(raw))) throw new Error(`${file} is not a JSON object. Fix or move it, then rerun gallivant init. ${NOTHING_WRITTEN}`);
+
+  // 1. The repository, before any network call: a directory that is not a GitHub checkout has nothing to set up.
+  const target = repository(dir);
+  if (base !== null) assertBranchName(base);
+  const setup = existing ? structuredClone(raw) : {};
+  let selectedHost = makeHostRegistry({ config: setup }).inspect(target.repo);
+  if (hostConfig !== null) {
+    const settings = readJson(expand(hostConfig), null);
+    const errors = selectedHost.adapter.validateConfig?.(settings) ?? ["This host does not support --host-config"];
+    if (errors.length) throw new Error(`${errors.join("; ")}. ${NOTHING_WRITTEN}`);
+    const previous = setup.git_hosts?.[selectedHost.repository.host];
+    // Setup adds observed identities after importing policy. Carry only those
+    // generated fields into the comparison; omitted policy remains a conflict,
+    // and a supplied identity may never overwrite a different saved binding.
+    for (const [path, binding] of Object.entries(previous?.repositories ?? {})) {
+      if (!binding || typeof binding !== "object") continue;
+      const identity = Object.fromEntries(["uuid", "workspaceUuid"].filter(key => Object.hasOwn(binding, key)).map(key => [key, binding[key]]));
+      if (Object.keys(identity).length) settings.repositories = { ...settings.repositories, [path]: { ...identity, ...settings.repositories?.[path] } };
+    }
+    if (previous && !isDeepStrictEqual(previous, settings)) throw new Error(`Existing host settings differ; edit the selected config explicitly instead of replacing them with --host-config. ${NOTHING_WRITTEN}`);
+    setup.git_hosts = { ...setup.git_hosts, [selectedHost.repository.host]: previous ?? settings };
+    selectedHost = makeHostRegistry({ config: setup }).inspect(target.repo);
+  }
+  gh ??= selectedHost.api;
+  resolve ??= config => selectedHost.adapter.credential(config, selectedHost.repository);
+  ghFor ??= credential => makeHostRegistry({ credential: async () => credential, log: silentLog }).inspect(target.repo).api;
+
+  // 2. GitHub sign-in, by asking `gh` who it is. The fix is `gh`'s own login flow; nothing here reads a credential.
+  let login = null, ghError = null;
+  try { login = await gh.user(); } catch (e) { ghError = firstLine(e); }
+  if (selectedHost.adapter.features?.transportSetup) {
+    if (!login) throw new Error(`${ghError || "Host API credential is missing"}\n${NOTHING_WRITTEN}`);
+  } else if (!/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(login || "")) throw new Error(`GitHub CLI is not signed in${ghError ? ` (${ghError})` : ""}.\nRun: gh auth login\nThen rerun gallivant init. ${NOTHING_WRITTEN}`);
+
+  // 3. The config this run would leave behind, built but not yet written.
+  const selected = harness ?? (existing ? onlyLocalHarness(raw) : "codex");
+  const candidate = existing ? setup : {
+    ...setup,
+    trusted_authors: [login], worktrees: expand(worktrees || join(dirname(home), ".gallivant-worktrees")),
+    harness: {}, notify: null, github_token_file: null, repos: [],
+  };
+  if (existing && worktrees && expand(worktrees) !== expand(raw.worktrees)) throw new Error(`config already sets worktrees to ${raw.worktrees}; edit ${contract(file)} to move it rather than passing --worktrees. ${NOTHING_WRITTEN}`);
+  if (selected && !candidate.harness?.[selected]) {
+    const found = discover(home)[selected];
+    if (!found) throw new Error(`${selected} is not on PATH. Install it and sign in, then retry gallivant init --harness ${selected}. ${NOTHING_WRITTEN}`);
+    candidate.harness = { ...(candidate.harness || {}), [selected]: found };
+  }
+  if (selectedHost.adapter.reviewPolicy) repositoryReviewConfig(candidate, target.repo, selectedHost.adapter);
+  if (base !== null) {
+    const previous = (candidate.repos || []).find(r => repoEntry(r)?.repo === target.repo);
+    candidate.repos = [...(candidate.repos || []).filter(r => repoEntry(r)?.repo !== target.repo), { ...(typeof previous === "object" ? previous : {}), repo: target.repo, base }];
+  }
+  const merged = merge(candidate, home);
+  const problems = validate(merged, home);
+  if (problems.length) throw new Error(`${existing ? `Config problems in ${contract(file)}: ` : ""}${problems.join("; ")}. ${NOTHING_WRITTEN}`);
+  if (!selected) throw new Error(`Choose a harness: rerun gallivant init --harness codex or gallivant init --harness claude. ${NOTHING_WRITTEN}`);
+
+  // 4. The selected harness has to be installed at a supported version and signed in. The adapter owns the fix line
+  //    (`codex login`, `claude auth login`); init only repeats it. Version and sign-in say nothing about model access.
+  if (selected) {
+    const ready = await harnessCheck(selected, expandedFor(merged, selected));
+    if (!ready.ok) throw new Error(`${selected} is not ready (${ready.detail}).\nRun: ${ready.fix}\nThen rerun gallivant init --harness ${selected}. ${NOTHING_WRITTEN}`);
+  }
+
+  // 5. The repository has to be one a RUN can push to, asked of GitHub with the credential this config resolves
+  //    (`github_token_file` first, then the environment, then `gh`), exactly as `start` and `doctor` resolve it. The
+  //    operator's ambient login is the wrong identity to ask: an explicit PAT that cannot reach the repository is the
+  //    failure this check exists to catch, and an ambient login that can would hide it.
+  const runConfig = { ...merged, github_token_file: merged.github_token_file ? expand(merged.github_token_file) : null };
+  if (selectedHost.adapter.features?.transportSetup) {
+    const report = await transportPreflight(runConfig, target.repo);
+    const host = selectedHost.repository.host, path = selectedHost.repository.path;
+    candidate.git_hosts = { ...candidate.git_hosts, [host]: { ...candidate.git_hosts?.[host], repositories: {
+      ...candidate.git_hosts?.[host]?.repositories, [path]: { ...candidate.git_hosts?.[host]?.repositories?.[path], uuid: report.identity.uuid, workspaceUuid: report.identity.workspaceUuid },
+    } } };
+  } else {
+    let credential;
+    try { credential = await resolve(runConfig); } catch (e) { throw new Error(`${firstLine(e)}\n${NOTHING_WRITTEN}`); }
+    if (!credential?.token) throw new Error(`${credential?.why || "No GitHub credential could be resolved for a run."}\n${NOTHING_WRITTEN}`);
+    const identity = describeCredential(credential);
+    const runGh = ghFor(credential);
+    const perm = await runGh.repoPermissions(selectedHost.repository.path).catch(e => ({ error: firstLine(e) }));
+    if (!perm || perm.error) throw new Error(`GitHub cannot resolve ${target.repo} with the run credential (${identity})${perm?.error ? `: ${perm.error}` : ""}. Check that origin (${safeOrigin(target.origin)}) names a repository that credential can see, then rerun gallivant init. ${NOTHING_WRITTEN}`);
+    if (perm.archived) throw new Error(`${target.repo} is archived, so nothing can be pushed to it. Unarchive it or run gallivant init in another repository. ${NOTHING_WRITTEN}`);
+    if (!perm.push) throw new Error(`the run credential (${identity}) has no push permission on ${target.repo}. ${runConfig.github_token_file ? `Give the token in ${contract(runConfig.github_token_file)} Contents: write on ${target.repo}` : "Ask for write access, or fork it and point origin at the fork"}, then rerun gallivant init. ${NOTHING_WRITTEN}`);
+    // Repository role alone does not grant a classic token write scope, even when that account can push.
+    const scope = selectedHost.adapter.features?.repositoryScopes ? await repositoryWriteScopeCheck(runGh, credential) : { ok: true };
+    if (!scope.ok) throw new Error(`${scope.detail}.\nFix: ${scope.fix}\n${NOTHING_WRITTEN}`);
+  }
+
+  // 6. Write. The repository is deduplicated by lowercased name whichever form each entry takes, so a second run,
+  //    or a run from a clone whose remote spells the owner differently, never appends a duplicate. The string form is
+  //    what a first use writes; a base branch is chosen with `start --base` or by hand, not here.
+  const repos = Array.isArray(candidate.repos) ? candidate.repos : [];
+  const known = repos.some(r => repoEntry(r)?.repo === target.repo);
+  if (!known) candidate.repos = [...repos, target.repo];
+  const changed = !existing || JSON.stringify(candidate) !== JSON.stringify(raw);
   mkdirSync(home, { recursive: true, mode: 0o700 });
-  mkdirSync(config.worktrees, { recursive: true, mode: 0o700 });
-  // wx also refuses a dangling symlink and protects concurrent invocations.
-  const fd = openSync(file, "wx", 0o600);
-  try { writeFileSync(fd, JSON.stringify(config, null, 2) + "\n"); } finally { closeSync(fd); }
-  return { file, harness, config, templates: { passport: templatePath("passport.gallivant.json"), sandbox: templatePath("claude-settings.json") } };
+  const owner = acquireCliMutation(home);
+  try {
+    // Probes await external tools. Another CLI writer may have changed the config meanwhile. Compare under the
+    // shared mutation lock, then retry all probes against the new settings rather than overwriting or trusting them.
+    const current = readJson(file, missing);
+    if (JSON.stringify(current) !== JSON.stringify(raw)) throw Object.assign(new Error(`Config changed during setup; rerun gallivant init. ${NOTHING_WRITTEN}`), { code: "INIT_CONFIG_CHANGED" });
+    mkdirSync(expand(merged.worktrees), { recursive: true, mode: 0o700 });
+    if (!existing) {
+      // wx also refuses a dangling symlink.
+      const fd = openSync(file, "wx", 0o600);
+      try { writeFileSync(fd, JSON.stringify(candidate, null, 2) + "\n"); } finally { closeSync(fd); }
+    } else if (changed) {
+      writeJsonAtomic(file, candidate, 0o600);
+    }
+  } finally { owner.release(); }
+
+  // 7. The same report `doctor` prints, so the operator reads one checklist rather than two.
+  const results = await doctor({ home });
+  return {
+    file, created: !existing, changed, login,
+    repo: target.repo, checkout: target.checkout, recorded: !known,
+    harness: selected, harnesses: Object.keys(merged.harness),
+    worktrees: expand(merged.worktrees),
+    preserved: existing ? Object.keys(raw).filter(k => k !== "repos" && !(selectedHost.adapter.features?.transportSetup && k === "git_hosts")) : [],
+    config: merged, doctor: results, dispatchGuidance: selectedHost.adapter.dispatchReason ?? null,
+    templates: { passport: templatePath("passport.gallivant.json"), sandbox: templatePath("claude-settings.json") },
+  };
 }
+
+/**
+ * Whether this process was started by `npx` / `npm exec` rather than from an installed `gallivant` command. npm
+ * marks the child's environment; the `_npx` cache directory in the script path is the fallback for a shell that
+ * stripped the environment.
+ */
+export const viaNpx = (env = process.env, script = process.argv[1] || "") =>
+  env.npm_command === "exec" || env.npm_lifecycle_event === "npx" || /[\\/]_npx[\\/]/.test(script);
+
+/** The command that runs this package again, spelled for how it was started this time. */
+export const commandPrefix = npx => (npx ? `npx --yes ${PACKAGE_NAME}` : "gallivant");
+
+export const FIRST_TASK = "Document how to run the existing tests in CONTRIBUTING.md. Use the commands already defined in the repository. Change documentation only.";
+
+/**
+ * What `gallivant init` prints: what it did, doctor's report, and what to run next. `report` is `renderDoctor`'s
+ * result. The `npx` paragraph says what `npx` did and did not do, because a one-command setup that silently looked
+ * like a global installation would send the operator looking for a `gallivant` command that is not there.
+ */
+export function renderInit(r, report, { npx = viaNpx(), script = process.argv[1] } = {}) {
+  const cmd = commandPrefix(npx);
+  const failed = r.doctor.filter(x => !x.ok).length;
+  const lines = [
+    `Package:    ${PACKAGE_NAME} ${VERSION}${npx ? " (run by npx)" : ""}`,
+    `Running:    ${script ? safeRealpath(script) : "(unknown)"}`,
+    `Config:     ${contract(r.file)} (${r.created ? "created, mode 600" : r.changed ? `kept; ${r.preserved.length} existing key(s) preserved` : "unchanged"})`,
+    `Harness:    ${r.harness ? `${r.harness} (${r.config.harness[r.harness]?.bin || "configured"})` : r.harnesses.join(", ") || "none"}`,
+    `Repository: ${r.repo} (${r.recorded ? "recorded in repos" : "already in repos; not duplicated"})`,
+    `Worktrees:  ${r.worktrees}`,
+    "",
+    "Doctor:",
+    report.text,
+    "",
+    "Next:",
+  ];
+  if (r.dispatchGuidance) {
+    lines.push(`  ${r.dispatchGuidance}`, `  Check access again: ${cmd} doctor`);
+    return lines.join("\n");
+  }
+  if (failed) lines.push(`  Fix the ${failed} failing check(s) above, then run:   ${cmd} doctor`);
+  else lines.push(`  All checks passed. Confirm the reviewer setting in ${contract(r.file)} (default: the Codex GitHub review integration), then start a small task.`);
+  lines.push(
+    `  First task (uses your ${r.harness} account for inference; --run authorizes implementation once the brief is ready):`,
+    `    ${cmd} task ${JSON.stringify(FIRST_TASK)} --harness ${r.harness} --verify 'git diff --check' --run`,
+    `    ${cmd} start`,
+    "  Setup did not create a GitHub ruleset, install harness hooks, start a task or merge anything; doctor names each remaining step.",
+    `  Guide: https://github.com/uchibeke/gallivant/blob/main/docs/install.md`,
+  );
+  if (npx) {
+    lines.push("",
+      `npx ran ${PACKAGE_NAME} on demand from npm's cache. Nothing was installed globally and no gallivant command was added to your PATH.`,
+      `  Run it again any time:        ${cmd} doctor`,
+      `  Optional persistent install:  npm install -g ${PACKAGE_NAME}   # then use plain: gallivant doctor`);
+  }
+  lines.push("", "Packaged templates:", `  ${r.templates.passport}`, `  ${r.templates.sandbox}`);
+  return lines.join("\n");
+}
+
+const safeRealpath = p => { try { return realpathSync(p); } catch { return p; } };

package/lib/commands/register.mjs

@@ -1,3 +1,7 @@
+import { repositoryReviewConfig } from "../review_policy.mjs";
+import { hosts } from "../hosts.mjs";
+import { assertRepositoryAccess } from "../host_contract.mjs";
+import { hostApi } from "../hosts.mjs";
 // `gallivant register <pr-url>`: put a hand-made PR, or one opened from a terminal session, into the loop.
 // On an entry that already exists it is the reset: reason cleared, iteration zero, a reset comment posted so the
 // count recovered from GitHub agrees, watching again.
@@ -5,28 +9,38 @@ import { resolve } from "node:path";
 import { newEntry, entryId, STATES } from "../state.mjs";
 import { worktreePath, isOurBranch, prdIdFromBranch } from "../git.mjs";
 import { parseBlock, normalizePublicBody } from "../block.mjs";
-import { repoFromUrl, remoteMatches, RESET_MARKER } from "../gh.mjs";
+import { repoFromUrl } from "../hosts.mjs";
+import { remoteMatches, safeOrigin } from "../repository.mjs";
+import { RESET_MARKER } from "../host_contract.mjs";
 import { receiptHash } from "../deliverable.mjs";
 import { rememberRepo, defaultHarness } from "../config.mjs";
-import { isSessionFor } from "../harness.mjs";
+import { isSessionFor, capabilitiesFor } from "../harness.mjs";
+import { executionEpoch, reserveExecutionEpoch } from "../execution.mjs";
+import { acquireRuntimeOwner } from "../daemon.mjs";
 import { ensurePrdSnapshot, toPrdId } from "../prd.mjs";
 import { nowIso, floorSecond } from "../time.mjs";
+import { legacyReviewPolicy, selectReviewPolicy } from "../review_policy.mjs";
 
 /** The PRD id for a hand-made branch: our own convention when the branch follows it, else a slug of the name. */
 const prdIdFor = branch => prdIdFromBranch(branch) ?? toPrdId(branch);
 
 export async function register(ctx, { url, harness = null, session = null, worktree = null }) {
-  const { config, state, gh, git, log } = ctx;
+  const { config, state, git, log } = ctx;
+  const host = hostApi(ctx);
   const publicSince = floorSecond(nowIso());
   // Resolved against the directory `register` runs in, before anything reads it. The registry is read back by a
   // daemon whose working directory is its own, so a relative path stored as typed would point somewhere else there:
   // the harness would run in the wrong tree, or `ensureWorktree` would clone over it. Absolute from here on.
   if (worktree) worktree = resolve(worktree);
-  const parsed = repoFromUrl(url);
-  if (!parsed) throw new Error(`not a GitHub PR URL: ${url}`);
-  const pr = await gh.prView(parsed.repo, parsed.number);
+  const selectedHost = (ctx.hosts ?? hosts).fromUrl(url);
+  const parsed = { repo: selectedHost.repository.key, number: selectedHost.number };
+  if (!parsed) throw new Error("Invalid or unsupported host PR URL; use a canonical URL on a qualified host");
+  repositoryReviewConfig(config, parsed.repo, selectedHost.adapter);
+  const pr = await host.prView(parsed.repo, parsed.number);
   // The repo as GitHub spells it, so an oddly cased URL never yields a second entry for the same PR.
-  const repo = repoFromUrl(pr.url)?.repo || parsed.repo;
+  const observed = (ctx.hosts ?? hosts).fromUrl(pr.url);
+  if (observed.repository.key !== parsed.repo || observed.number !== parsed.number) throw new Error("PR identity mismatch; restore the qualified URL before registering");
+  const repo = observed.repository.key;
   if (pr.isCrossRepository) throw new Error("fork PRs are not registered");
   if (pr.state !== "OPEN") throw new Error(`PR is ${pr.state}`);
 
@@ -35,10 +49,39 @@ export async function register(ctx, { url, harness = null, session = null, workt
   const found = state.findByPr(repo, pr.number);
   const id = found ? found[0] : entryId(repo, prdId);
   const existing = found ? found[1] : state.get(id);
+  const reviewPolicy = existing?.reviewPolicy || (existing ? legacyReviewPolicy(repositoryReviewConfig(config, repo, selectedHost.adapter)) : ctx.reviewService ? await ctx.reviewService.preflight(repo) : selectReviewPolicy(config, repo));
   state.assertCanRegister(id);
   if (existing && existing.pr !== pr.number && existing.pr !== null) throw new Error(`${id} already watches PR #${existing.pr}`);
   const chosenHarness = harness || existing?.harness || block?.harness || defaultHarness(config);
   if (!config.harness[chosenHarness]) throw new Error(`harness "${chosenHarness}" is not configured`);
+  assertRepositoryAccess(capabilitiesFor(chosenHarness), selectedHost.repository);
+  const switching = existing && chosenHarness !== existing.harness;
+  // A daemon holds this lock for its entire lifetime. Claim it through the
+  // GitHub reset and registry write so an old-provider tick cannot dispatch
+  // after the settlement check, nor can a daemon boot midway through it.
+  const owner = switching ? (ctx.acquireRuntimeOwner ?? acquireRuntimeOwner)(ctx.home) : null;
+  let fenced = false, remoteMayBeNew = false, reservationAttempted = false;
+  try {
+  if (switching && JSON.stringify(state.get(id)) !== JSON.stringify(existing)) {
+    throw new Error("the watched entry changed while stopping the coordinator; inspect its latest run and retry the harness reset");
+  }
+  let nextEpoch = existing?.execution_epoch ?? 0;
+  if (switching) {
+    if (existing.handoff_pending && (existing.dispatch_stopped !== "harness-handoff-pending" || existing.handoff_pending.to !== chosenHarness || existing.handoff_pending.pr !== pr.number)) {
+      throw new Error("another provider handoff is pending; inspect and finish that reset before choosing a different harness");
+    }
+    if (existing.task || capabilitiesFor(existing.harness).transport !== "cli" || capabilitiesFor(chosenHarness).transport !== "cli") throw new Error("changing harness on an owned task or remote execution requires an explicit provider handoff; nothing was registered");
+    if (session) throw new Error("a cross-harness reset requires a fresh provider session; --session cannot prove ownership in the new execution ledger");
+    if (existing.last?.run && existing.last.exit == null) throw new Error("the previous run is not settled; wait for its outcome before changing harness");
+    const previous = ctx.executionFor?.(id, existing.harness);
+    const ledger = previous?.state?.();
+    const job = previous?.current?.();
+    if (job?.running || ledger?.stopped || ledger?.current && (ledger.current.id !== existing.last?.run || ledger.current.exit == null || ledger.current.execution?.collected !== true)) {
+      throw new Error("the previous provider still owns unsettled execution; reconcile it before changing harness");
+    }
+    const root = previous?.root;
+    nextEpoch = root ? executionEpoch({ root, taskId: id, entry: existing, provider: existing.harness, account: previous.account, runner: ctx.runnerFor?.(id) }) + 1 : nextEpoch + 1;
+  }
   if (session && !worktree && !existing?.worktree) throw new Error("--session needs --worktree: both harnesses key sessions by the directory they ran in");
   // The same rule the block is held to, so the flag and the block agree on what a session is. A value typed here
   // reaches argv position 2 on the next fix round, right after `--resume` or `--name`, where `assertSafeArgv` matches
@@ -77,6 +120,7 @@ export async function register(ctx, { url, harness = null, session = null, workt
   const identity = { prd: blockPrd, harness: chosenHarness, session: chosenSession, branch: pr.headRefName };
   const writesRecovery = isOurBranch(pr.headRefName) && blockPrd !== null;
   const stale = writesRecovery && block && (block.harness !== chosenHarness || block.session !== chosenSession || normalizePublicBody(pr.body, { identity, taskId: id }) !== pr.body);
+  remoteMayBeNew = switching && block?.harness === chosenHarness && block?.session === chosenSession;
 
   // Two durable GitHub writes, and the ORDER between them is the whole of this. Both are preconditions of the local
   // reset, so either failing throws and leaves the registry untouched; what the order decides is what GitHub is left
@@ -104,21 +148,35 @@ export async function register(ctx, { url, harness = null, session = null, workt
   // it, so a recovery after `state.json` is lost rebuilds the iteration this command had just zeroed. An entry restored
   // at `max_iterations` then stops with `reason: "iterations"` on its next event, having done no work in this round at
   // all, and the operator is told the budget is spent on a PR they had just reset.
+  if (switching) {
+    state.put(id, { ...existing, state: STATES.needsHuman, reason: "harness-handoff-pending",
+      dispatch_stopped: "harness-handoff-pending",
+      handoff_pending: { from: existing.harness, to: chosenHarness, epoch: nextEpoch, pr: pr.number, at: nowIso() } });
+    fenced = true;
+  }
   if (existing) {
-    try { await gh.comment(repo, pr.number, `Watching again from here.\n\n${RESET_MARKER}`); }
+    try { await host.comment(repo, pr.number, `Watching again from here.\n\n${RESET_MARKER}`); }
     catch (e) { throw new Error(`cannot post the reset comment on ${pr.url}: ${e.message}. Nothing was reset; the entry keeps its ${existing.iteration} round${existing.iteration === 1 ? "" : "s"} and its state, and its recorded harness and session are unchanged. Fix the cause and run register again.`); }
   }
   // The identity of record, written last of the two and still before anything reaches the registry, so a failure here
   // leaves GitHub and the registry agreeing on the OLD identity rather than disagreeing.
   if (writesRecovery && (!block || stale)) {
-    try { const updated = await gh.setRecoveryMetadata(repo, pr.number, identity, { taskId: id }); pr.body = updated.body; }
+    if (switching) remoteMayBeNew = true; // A failed reply cannot prove that the body write did not land.
+    try { const updated = await host.setRecoveryMetadata(repo, pr.number, identity, { taskId: id }); pr.body = updated.body; }
     // The message names the identity that survived, and only claims the PR agrees when the PR actually had a block to
     // agree with: an existing entry on a PR with no block at all is a case where the registry has an identity and
     // GitHub has none, which is what this write was about to fix and is not the same as the two of them agreeing.
-    catch (e) { throw new Error(`cannot write the gallivant block to ${pr.url}: ${e.message}. Nothing was registered${existing ? `: the entry keeps harness ${existing.harness} and session ${existing.session ?? "none"}${block ? ", which is still what the PR records" : ", and the PR still records no identity at all"}` : ""}. Fix the cause and run register again.`); }
+    catch (e) { throw new Error(`cannot write the gallivant block to ${pr.url}: ${e.message}. Nothing was registered${existing ? `: the entry keeps harness ${existing.harness} and session ${existing.session ?? "none"}${!switching ? block ? ", which is still what the PR records" : ", and the PR still records no identity at all" : ""}` : ""}.${switching ? " The old entry remains fenced because the remote write may have landed." : ""} Fix the cause and run register again.`); }
     if (stale) log.info(`${id}: PR block updated to harness ${chosenHarness}, session ${chosenSession ?? "none"}`);
   }
 
+  if (switching && ctx.executionFor) {
+    const previous = ctx.executionFor(id, existing.harness);
+    reservationAttempted = true;
+    (ctx.reserveExecutionEpoch ?? reserveExecutionEpoch)({ root: previous.root, taskId: id, provider: chosenHarness,
+      account: config.harness[chosenHarness]?.account || "operator", epoch: nextEpoch, pr: pr.number });
+  }
+
   // `base` on the entry is the branch this PR targets, and it comes from the PR itself. A registered PR is one a person
   // opened, so the operator's config has no say in where it was aimed: `baseRefName` is the truth, and it is what the
   // daemon merges in before every later round. An existing entry keeps whatever it had unless the PR says otherwise,
@@ -133,7 +191,9 @@ export async function register(ctx, { url, harness = null, session = null, workt
   // piece of feedback written in that second and lose it for good.
   const since = floorSecond(existing ? nowIso() : pr.createdAt);
   const entry = {
-    ...base, public_since: existing?.public_since || publicSince, harness: chosenHarness, session: chosenSession, worktree: dir, pr: pr.number, url: pr.url, base: prBase ?? base.base ?? null,
+    ...base, reviewPolicy, public_since: existing?.public_since || publicSince, harness: chosenHarness, session: chosenSession, worktree: dir, pr: pr.number, url: pr.url, base: prBase ?? base.base ?? null,
+    ...(switching ? { execution_epoch: nextEpoch, execution_handoff: { from: existing.harness, to: chosenHarness, previousRun: existing.last?.run ?? null, at: nowIso() },
+      dispatch_stopped: null, handoff_pending: null } : {}),
     // `retry` goes with `reason`: it counts the consecutive failures of one GitHub write the tick declines a step for,
     // and a reset is the operator saying the cause is dealt with. Left behind, an entry reset after a `stuck` stop would
     // carry four failures into its next one and stop again on the first write that failed.
@@ -165,15 +225,23 @@ export async function register(ctx, { url, harness = null, session = null, workt
     updated_at: nowIso(),
   };
   state.put(id, entry);
+  fenced = false;
   // The snapshot the completion gate reads, taken the same way `reconcile` takes it. Without it `prdFor` returns
   // nothing, the gate logs "no PRD snapshot" and the PR can be marked ready with no acceptance criterion evaluated.
   // After the entry is stored, so a GitHub read that fails leaves a watched PR rather than an aborted registration.
   // A snapshot already on disk is kept, so a reset never replaces the authoritative copy with the one the session
   // could have edited.
   await ensurePrdSnapshot(ctx, { id, repo, path: blockPrd, ref: pr.headRefName });
-  if (rememberRepo(repo, config.home)) await gh.ensureLabels(repo).catch(e => log.warn(`${repo}: labels not created: ${e.message}`));
+  if (rememberRepo(repo, config.home)) await host.ensureLabels(repo).catch(e => log.warn(`${repo}: labels not created: ${e.message}`));
   log.info(`${id}: ${existing ? "reset and " : ""}watching ${pr.url} with ${chosenHarness}${chosenSession ? " (resume)" : " (fresh session on first fix)"}`);
   return { id, pr: pr.number, worktree: dir, harness: chosenHarness, session: chosenSession };
+  } catch (error) {
+    // Before any possible identity write or ledger reservation, a failed reset
+    // may restore the exact prior entry. Once either may have landed, retain
+    // the dispatch fence so a restarted daemon cannot launch the old harness.
+    if (fenced && !remoteMayBeNew && !reservationAttempted) state.put(id, existing);
+    throw error;
+  } finally { owner?.release(); }
 }
 
 /**
@@ -187,7 +255,7 @@ async function assertCheckout(git, dir, repo, branch) {
   let origin;
   try { origin = await git.originOf(dir); }
   catch (e) { throw new Error(`--worktree ${dir} has no origin remote: ${e.message}`); }
-  if (!remoteMatches(origin, repo)) throw new Error(`--worktree ${dir} is a clone of ${origin}, not ${repo}`);
+  if (!remoteMatches(origin, repo)) throw new Error(`--worktree ${dir} is a clone of ${safeOrigin(origin)}, not ${repo}`);
   let current;
   try { current = await git.currentBranch(dir); }
   catch (e) { throw new Error(`--worktree ${dir}: cannot read the checked-out branch: ${e.message}`); }

package/lib/commands/resume.mjs

@@ -1,3 +1,5 @@
+import { hosts } from "../hosts.mjs";
+import { assertRepositoryAccess } from "../host_contract.mjs";
 // Resume a stopped session after validating its contract and preserving any unsettled run.
 import { NETWORK_RECOVERY_WINDOW } from "../network_recovery.mjs";
 import { learningDelivered, learningDeliveryPatch } from "../learning_input.mjs";
@@ -20,6 +22,7 @@ export async function resume(ctx, { handle, note = null, resnapshot = false, fre
   const { state, git, log, readPrd } = ctx;
   const id = resolveHandle(state.entries(), handle);
   let entry = state.get(id);
+  assertRepositoryAccess(capabilitiesFor(entry.harness), (ctx.hosts ?? hosts).select(entry).repository);
   if (entry.dispatch_stopped) throw new Error(`dispatch stopped: ${entry.dispatch_stopped}; cancellation and late results must be reconciled before any new task`);
 
   if (!RESUMABLE.has(entry.state)) throw new Error(`${handleFor(id, entry)} is ${entry.state}; resume takes a stopped or watched entry`);
@@ -159,8 +162,9 @@ export async function resume(ctx, { handle, note = null, resnapshot = false, fre
   const unpushed = git.unpushed ? await git.unpushed(entry.worktree, entry.branch, entry.base ?? null) : [];
   if (unpushed.length) log.info(`${id}: ${unpushed.length} unpushed commit${unpushed.length === 1 ? "" : "s"} on ${entry.branch}; the session is told to preserve and review them before pushing`);
 
-  let prompt = initialDispatch ? [startPrompt({ prd: parsed, repo: entry.repo, branch: entry.branch, base: entry.base, verify: verifyCommands(parsed), receipt: receiptInstructions(criteriaFromPrd(parsed), id), carried: entry.sources ?? [] }),
+  let prompt = initialDispatch ? [startPrompt({ host: (ctx.hosts ?? hosts).select(entry).adapter.prompts, prd: parsed, repo: entry.repo, branch: entry.branch, base: entry.base, verify: verifyCommands(parsed), receipt: receiptInstructions(criteriaFromPrd(parsed), id), carried: entry.sources ?? [] }),
     "This is the first provider implementation; the previous launch was refused before submission. Work from the supplied current source revision and preserve its commits.", ...(note ? [`Operator clarification: ${note}`] : [])].join("\n\n") : resumePrompt({
+    host: (ctx.hosts ?? hosts).select(entry).adapter.prompts,
     repo: entry.repo,
     pr: entry.pr,
     base: entry.base,

package/lib/commands/review.mjs

@@ -0,0 +1,66 @@
+import { resolveHandle } from "../state.mjs";
+import { executionRunner } from "../execution.mjs";
+import { STATES } from "../state.mjs";
+import { READY_LABEL } from "../host_contract.mjs";
+import { hostApi, hosts } from "../hosts.mjs";
+import { reviewDisclosure, REVIEW_MODES } from "../review_policy.mjs";
+import { withReviewState } from "../review_state.mjs";
+
+export async function reviewCommand(ctx, { action, handle, repo, mode, reason, finding, run = false, capability = "text", retry = false, wait = false }) {
+  if (action === "qualify") {
+    if (!repo) throw new Error("review qualify requires --repo owner/name or host/owner/name");
+    const { repository } = (ctx.hosts ?? hosts).select(repo);
+    if (wait && !run) throw new Error("qualification --wait requires --run");
+    let result = await ctx.reviewService.qualify(repository.key, { run, capability, retry, reason });
+    while (wait && ["preparing", "launch-intent", "running", "retry-waiting"].includes(result.status)) {
+      await new Promise(resolve => setTimeout(resolve, 250));
+      result = await ctx.reviewService.qualify(repository.key, { run: true, capability });
+    }
+    return result;
+  }
+  if (!handle) throw new Error("review status|policy|dispute|retry needs a task handle");
+  const id = resolveHandle(ctx.state.entries(), handle), entry = ctx.state.get(id);
+  if (action === "status") return { id, policy: entry.reviewPolicy, disclosure: reviewDisclosure(entry), record: entry.firstPartyReview, readiness: entry.review_readiness, history: ctx.state.reviewHistory ? ctx.state.reviewHistory(id) : entry.reviewHistory || [] };
+  if (!reason?.trim()) throw new Error("review policy/dispute/retry requires --reason with an explicit operator reason");
+  return withReviewState(ctx, id, () => mutateReview(ctx, id, { action, mode, reason, finding }));
+}
+
+async function mutateReview(ctx, id, { action, mode, reason, finding }) {
+  const entry = ctx.state.get(id);
+  (ctx.hosts ?? hosts).select(entry);
+  const host = hostApi(ctx);
+  if (executionRunner(ctx, id).current()?.running) throw new Error("settle the active coding run before changing review state");
+  if (action === "retry") {
+    const audit = await ctx.reviewService.retry(id, entry, reason);
+    ctx.state.update(id, { state: STATES.prOpen, reason: null, firstPartyReview: null,
+      reviewHistory: [...(entry.reviewHistory || []), entry.firstPartyReview], review_readiness: null,
+      reviewBinding: entry.reviewBinding ?? entry.firstPartyReview?.binding ?? null,
+      // Only local output is retried. Keep the existing external review window
+      // and binding: unchanged evidence retains approval, while a moved base,
+      // receipt or check still triggers the ordinary fresh-review requirement.
+      review_next_at: 0,
+      last: { ...entry.last, event: "operator authorized retry of a settled review job" } });
+    return { id, ...audit, reevaluation: "failed pieces queued; completed pieces and original attempts retained" };
+  }
+  if (action === "dispute") {
+    if (!entry.firstPartyReview?.result?.findings?.some(f => f.id === finding)) throw new Error("--finding must identify a recorded first-party finding");
+    const dispute = { finding, reason: reason.trim(), status: "pending-human", at: new Date().toISOString() };
+    ctx.state.update(id, { reviewDisputes: [...(entry.reviewDisputes || []), dispute], state: STATES.needsHuman, reason: "review-dispute", review_readiness: null, review_label_pending: Boolean(entry.pr) });
+    if (entry.pr) await host.removeLabel(entry.repo, entry.pr, READY_LABEL);
+    ctx.state.update(id, { review_label_pending: false });
+    return dispute;
+  }
+  if (action !== "policy" || !REVIEW_MODES.includes(mode)) throw new Error(`review policy requires --mode ${REVIEW_MODES.join("|")}`);
+  const policy = await ctx.reviewService.preflight(entry.repo, { mode, legacy_no_review: false });
+  const at = new Date().toISOString();
+  const patch = { reviewPolicy: policy, reviewPolicyHistory: [...(entry.reviewPolicyHistory || []), { policy: entry.reviewPolicy, reason, at }],
+    firstPartyReview: null, reviewHistory: [...(entry.reviewHistory || []), ...(entry.firstPartyReview ? [entry.firstPartyReview] : [])],
+    reviewBinding: null, review_readiness: null, review_next_at: 0, rereview: { at, nudged: false },
+    ...(entry.completionEvidence?.delivery ? { completionEvidence: { ...entry.completionEvidence, delivery: { ...entry.completionEvidence.delivery, invalidatedAt: at, invalidationReason: "explicit review policy change" } } } : {}),
+    state: STATES.needsHuman, reason: "review-policy-changed", review_label_pending: Boolean(entry.pr) };
+  // Fence before the host label write. A failed write cannot preserve clearance.
+  ctx.state.update(id, patch);
+  if (entry.pr) await host.removeLabel(entry.repo, entry.pr, READY_LABEL);
+  ctx.state.update(id, { state: entry.pr ? STATES.prOpen : STATES.needsHuman, review_label_pending: false });
+  return { id, policy, reason, reevaluation: "current head requires new review evidence" };
+}

package/lib/commands/serve.mjs

@@ -24,6 +24,7 @@ import { streamRun, sliceRun, TAIL } from "../tracker/stream.mjs";
 import { listRuns, listFlatRuns, runDir, sourceRunDir, validRunId } from "../tracker/runs.mjs";
 import { ASSETS, themeOf } from "../tracker/assets.mjs";
 import { dashboard, runPage, runsPage, page, esc, CSP, GROUPINGS } from "../tracker/pages.mjs";
+import { reviewActivity } from "../tracker/review.mjs";
 
 export const DEFAULT_PORT = 8791;
 const HOST = "127.0.0.1";
@@ -175,6 +176,13 @@ export const routes = {
     json(res, 200, { control: hit.entry.control || null, lastMessage: lastMessage(hit.entry), state: hit.entry.state, reason: hit.entry.reason });
   },
 
+  "GET /api/run/review-activity": (ctx, _req, res, url) => {
+    const id = url.searchParams.get("id") || "";
+    const entry = id && (ctx.state.reviewActivityEntry ? ctx.state.reviewActivityEntry(id) : ctx.state.get(id));
+    if (!entry) return json(res, 404, { error: "unknown entry" });
+    json(res, 200, reviewActivity(entry));
+  },
+
   "POST /api/run/control": async (ctx, req, res, url) => {
     if (!localRequest(req) || req.headers.origin !== `http://${req.headers.host}`
       || req.headers["x-gallivant-token"] !== tokenFor(ctx)) return json(res, 403, { error: "Open this page on localhost and reload before trying again." });