@uchibeke/gallivant 0.2.0 → 0.2.1

package/lib/commands/init.mjs

@@ -1,34 +1,245 @@
-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 { gallivantHome, expand, templatePath, readJson, writeJsonAtomic, contract, VERSION, PACKAGE_NAME } from "../fs.mjs";
+import { discoverHarnesses, validate, merge, configPath, repoEntry } from "../config.mjs";
+import { makeGh, repoFromRemote } from "../gh.mjs";
 import { silentLog } from "../log.mjs";
+import { checkHarness } from "../probe.mjs";
+import { resolveCredential, describe as describeCredential } from "../credential.mjs";
+import { doctor as runDoctor, repositoryWriteScopeCheck } from "./doctor.mjs";
+import { acquireCliMutation } from "../daemon.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; } };
+
+/**
+ * A remote URL with its userinfo removed. `https://x-access-token:SECRET@github.com/...` is a remote git and
+ * `repoFromRemote` both accept, and every message here that names the origin would otherwise print the secret into
+ * a terminal or a CI log. Only scheme URLs carry userinfo; `git@github.com:owner/name` names a login, not a secret.
+ */
+export const safeOrigin = url => String(url || "").replace(/^([a-z][a-z0-9+.-]*:\/\/)[^@/]*@/i, "$1");
+
+/**
+ * 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}`);
+  const repo = repoFromRemote(origin);
+  if (!repo) throw new Error(`origin remote ${safeOrigin(origin)} is not a github.com repository URL. Gallivant opens pull requests on github.com; point origin at the GitHub repository, then rerun gallivant init. ${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, dir = process.cwd(),
+  discover = discoverHarnesses, gh = makeGh({ log: silentLog }), repository = targetRepository, harnessCheck = checkHarness, doctor = runDoctor,
+  resolve = resolveCredential, ghFor = credential => makeGh({ credential: async () => credential, log: silentLog }) } = {}) {
+  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 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 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 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);
+
+  // 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 (!/^[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 ? structuredClone(raw) : {
+    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 };
+  }
+  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 };
+  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(target.repo).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 = await repositoryWriteScopeCheck(runGh, credential);
+  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") : [],
+    config: merged, doctor: results,
+    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 (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

@@ -8,7 +8,9 @@ import { parseBlock, normalizePublicBody } from "../block.mjs";
 import { repoFromUrl, remoteMatches, RESET_MARKER } from "../gh.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";
 
@@ -39,6 +41,33 @@ export async function register(ctx, { url, harness = null, session = null, workt
   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`);
+  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 +106,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,6 +134,12 @@ 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}`); }
     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.`); }
@@ -111,14 +147,22 @@ export async function register(ctx, { url, harness = null, session = null, workt
   // 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)) {
+    if (switching) remoteMayBeNew = true; // A failed reply cannot prove that the body write did not land.
     try { const updated = await gh.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,
@@ -134,6 +178,8 @@ export async function register(ctx, { url, harness = null, session = null, workt
   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,
+    ...(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,6 +211,7 @@ 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.
@@ -174,6 +221,13 @@ export async function register(ctx, { url, harness = null, session = null, workt
   if (rememberRepo(repo, config.home)) await gh.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(); }
 }
 
 /**

package/lib/context.mjs

@@ -14,7 +14,7 @@ import { makeLog } from "./log.mjs";
 import { makeRunner } from "./run.mjs";
 import { ensureDir, gallivantHome, readText, writeText } from "./fs.mjs";
 import { aportDirFor, guardrailMode } from "./aport.mjs";
-import { makeExecution, assertExecutionDependency } from "./execution.mjs";
+import { makeExecution, executionEpoch, assertExecutionDependency } from "./execution.mjs";
 import { makeAgentsTransport } from "./openai_agents.mjs";
 import { capabilitiesFor } from "./harness.mjs";
 import { createLearningService } from "./learning.mjs";
@@ -67,7 +67,9 @@ export function makeContext({ home = gallivantHome(), needConfig = true, readOnl
     executionFor: (id, provider) => {
       const root = join(home, "runs", idSlug(id)), selected = config.harness[provider];
       const account = selected?.account || "operator";
-      return makeExecution({ root, taskId: id, provider, account,
+      const entry = state.get(id), runner = capabilitiesFor(provider).transport === "remote" ? null : makeRunner(root);
+      const epoch = executionEpoch({ root, taskId: id, entry, provider, account, runner });
+      return makeExecution({ root, taskId: id, provider, account, ledgerEpoch: epoch, ledgerFile: join(root, epoch ? `execution-${epoch}.json` : "execution.json"),
         ...(provider === "openai-agents" ? { transport: makeAgentsTransport({ root, taskId: id, account, config: selected }), capabilities: { ...capabilitiesFor(provider), models: [selected?.model] } } : {}),
         ...(provider === "codex-cloud" ? { transport: makeCloudTransport({ root, taskId: id, account, config: selected, verifyRemote: async input => {
           if (await gh.refSha(input.repo, input.sources.inputBranch) !== input.inputHead || await gh.refSha(input.repo, input.branch) !== input.inputHead) throw new Error("Cloud remote input revision moved; reconcile before dispatch");
@@ -76,7 +78,7 @@ export function makeContext({ home = gallivantHome(), needConfig = true, readOnl
           }
         } }), capabilities: { ...capabilitiesFor(provider), environments: [selected?.environment] } } : {}),
         legacySessionId: state.get(id)?.harness === provider ? state.get(id).session : null,
-        runner: capabilitiesFor(provider).transport === "remote" ? null : makeRunner(root), limits: config.execution });
+        runner, limits: config.execution });
     },
     // The APort API key the Claude install recorded, if any, so hosted gate calls count against the same account.
     aportApiKey: guardrailMode(aportDirFor(config.harness?.claude?.settings)).apiKey,

package/lib/execution.mjs

@@ -1,6 +1,6 @@
 // Versioned durable transport boundary. No transport implements a review loop.
 import { join } from "node:path";
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, readdirSync, rmSync } from "node:fs";
 import { randomUUID, createHash } from "node:crypto";
 import { ensureDir, readJson, writeJsonAtomic } from "./fs.mjs";
 import { acquireProcessLock } from "./daemon.mjs";
@@ -31,6 +31,82 @@ const preparationFingerprint = input => {
 };
 export const executionRunner = (ctx, id, provider = ctx.state.get(id)?.harness) => ctx.executionFor && provider ? ctx.executionFor(id, provider) : ctx.runnerFor(id);
 
+const epochFile = (root, epoch) => join(root, epoch ? `execution-${epoch}.json` : "execution.json");
+const validEpoch = epoch => Number.isSafeInteger(epoch) && epoch >= 0 && epoch <= 1000;
+const latestLedger = root => {
+  const epochs = readdirSync(root, { withFileTypes: true }).filter(file => file.isFile() && /^execution-[1-9][0-9]*\.json$/.test(file.name))
+    .map(file => Number(file.name.slice(10, -5)));
+  if (!epochs.length) return null;
+  const epoch = Math.max(...epochs);
+  if (!validEpoch(epoch)) throw executionError("EXECUTION_VERSION", "invalid execution handoff epoch; restore its matching ledger backup");
+  return { epoch, ledger: readJson(epochFile(root, epoch)) };
+};
+
+// Reserve a new provider epoch before changing the registry or starting a run.
+// Its empty ledger is also the durable route recovered after state.json loss.
+export function reserveExecutionEpoch({ root, taskId, provider, account, epoch, pr = null }) {
+  if (!validEpoch(epoch) || epoch === 0) throw executionError("EXECUTION_VERSION", "invalid execution handoff epoch");
+  const file = epochFile(root, epoch);
+  if (existsSync(file)) {
+    const saved = readJson(file);
+    if (saved?.version !== EXECUTION_VERSION || saved.taskId !== taskId || saved.provider !== provider || saved.account !== account ||
+        saved.handoff && (saved.handoff.epoch !== epoch || pr != null && saved.handoff.pr !== pr)) {
+      throw executionError("EXECUTION_OWNERSHIP", "reserved handoff ledger belongs to a different execution; restore its matching backup");
+    }
+    return;
+  }
+  writeJsonAtomic(file, { version: EXECUTION_VERSION, taskId, provider, account, operations: {}, current: null, stopped: null,
+    ...(pr != null ? { handoff: { epoch, pr } } : {}) });
+}
+
+// A registered PR may change local harnesses only after its previous run has
+// settled. Keep that provider's execution.json intact and give the new harness
+// a separate ledger while run directories remain under the same task root.
+// The legacy inference repairs registrations made before the epoch was saved:
+// it is deliberately limited to the exact settled reset, not an arbitrary
+// provider mismatch or a remote task whose ownership remains unresolved.
+export function executionEpoch({ root, taskId, entry, provider, account, runner }) {
+  if (entry?.execution_epoch != null) {
+    if (!validEpoch(entry.execution_epoch)) throw executionError("EXECUTION_VERSION", "invalid execution handoff epoch; restore its matching registry backup");
+  }
+  const latest = existsSync(root) ? latestLedger(root) : null;
+  if (latest) {
+    const pending = entry?.handoff_pending;
+    const oldEpoch = entry?.execution_epoch ?? 0;
+    // A reset interrupted after reserving its new empty ledger keeps the old
+    // registry entry fenced. Let a retry inspect that exact old ledger, while
+    // `dispatch_stopped` prevents a daemon from launching the old provider.
+    if (entry?.dispatch_stopped === "harness-handoff-pending" && pending?.from === provider &&
+        pending.to === latest.ledger?.provider && pending.epoch === latest.epoch && pending.pr === entry.pr &&
+        oldEpoch === latest.epoch - 1 && latest.ledger?.taskId === taskId && latest.ledger.handoff?.pr === entry.pr &&
+        latest.ledger.current === null && !latest.ledger.stopped && Object.keys(latest.ledger.operations ?? {}).length === 0) {
+      return oldEpoch;
+    }
+    if (entry?.execution_epoch != null && entry.execution_epoch !== latest.epoch) throw executionError("EXECUTION_OWNERSHIP", "registry and latest handoff ledger disagree; reconcile the interrupted reset before dispatch");
+    if (latest.ledger?.version !== EXECUTION_VERSION || latest.ledger.taskId !== taskId || latest.ledger.provider !== provider || latest.ledger.account !== account ||
+        latest.ledger.handoff && (latest.ledger.handoff.epoch !== latest.epoch || latest.ledger.handoff.pr !== entry?.pr)) {
+      throw executionError("EXECUTION_OWNERSHIP", "latest handoff ledger belongs to another provider/account; do not reopen an older session");
+    }
+    return latest.epoch;
+  }
+  if (entry?.execution_epoch != null) {
+    if (entry.execution_epoch > 0) throw executionError("EXECUTION_OWNERSHIP", "recorded handoff ledger is missing; restore its matching backup before dispatch");
+    return 0;
+  }
+  const old = readJson(epochFile(root, 0));
+  if (!old || old.provider === provider && old.account === account) return 0;
+  const prior = old.current?.execution;
+  const current = runner?.current();
+  const exactReset = entry?.pr && entry.session === null &&
+    entry.last?.run === old.current?.id && entry.last?.exit === old.current?.exit &&
+    entry.execution?.provider === old.provider && entry.execution?.account === old.account &&
+    old.taskId === taskId && old.account === "operator" && account === "operator" &&
+    prior?.transport === "cli" && prior.provider === old.provider && prior.collected === true &&
+    ["succeeded", "failed"].includes(prior.providerState) && !old.stopped &&
+    current?.id === old.current.id && current.running === false;
+  return exactReset ? 1 : 0;
+}
+
 // A sessionless resume is allowed only for an owned, proven unsubmitted first
 // launch. Older refusal entries can recover from the private transport proof;
 // a registry reason or an absent session alone never authorizes a new session.
@@ -53,9 +129,9 @@ export function assertExecutionDependency(taskService) {
  * Methods accept scoped immutable input plus AbortSignal and return bounded JSON.
  * A remote adapter never needs a local command, PID, or inherited environment.
  */
-export function makeExecution({ root, taskId, provider, account = "operator", transport = null, runner = null, legacySessionId = null, capabilities = capabilitiesFor(provider), clock = Date, limits = {}, secrets = [], jitter = Math.random }) {
+export function makeExecution({ root, taskId, provider, account = "operator", transport = null, runner = null, legacySessionId = null, ledgerFile = join(root, "execution.json"), ledgerEpoch = 0, capabilities = capabilitiesFor(provider), clock = Date, limits = {}, secrets = [], jitter = Math.random }) {
   const bounds = { ...EXECUTION_LIMITS, ...limits };
-  const file = join(root, "execution.json");
+  const file = ledgerFile;
   const collectionRejection = s => {
     const job = s.current, ex = job?.execution;
     if (!transport || !ownedRemote(ex) || !["succeeded", "failed"].includes(ex.terminalState)) return null;
@@ -246,7 +322,7 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
     if (s.learningContinuity?.pending && (method !== "submit" || input.sessionId)) throw executionError("EXECUTION_CONTINUATION", "retired advice requires a new provider session, not continuation");
     if (s.stopped) throw executionError("EXECUTION_STOPPED", `dispatch stopped: ${s.stopped}; late results remain quarantined`);
     if (s.current && executionLive(s.current)) throw executionError("BUSY", "previous provider work is not settled");
-    const legacy = !transport && !s.current ? runner.current() : null;
+    const legacy = !transport && !s.current && ledgerEpoch === 0 ? runner.current() : null;
     if (legacy?.running) throw executionError("BUSY", "legacy local writer is still running");
     const ownedSession = transport ? s.current?.execution.sessionId : s.current
       ? localSession(s, s.current.id, s.current.execution.sessionId)
@@ -313,9 +389,9 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
     const s = read();
     if (!transport) {
       const job = runner.current();
-      if (job && (!s.current || s.current.id === job.id)) return { ...job, ...(s.current ? { execution: s.current.execution,
+      if (job && ((ledgerEpoch === 0 && !s.current) || s.current?.id === job.id)) return { ...job, ...(s.current ? { execution: s.current.execution,
         ...(s.current.execution.quarantined ? { exit: s.current.exit, endedAt: s.current.endedAt } : {}) } : {}) };
-      if (!s.current) return job; // Legacy local runs retain their exact identity.
+      if (!s.current) return ledgerEpoch === 0 ? job : null; // Only the original epoch may adopt a legacy local run.
     }
     return s.current ? { ...s.current, running: executionLive(s.current) } : null;
   };
@@ -470,7 +546,7 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
       if (!s.stopped || reason !== "timeout") s.stopped = reason;
       // An upgrade may have an owned local writer but no boundary submission.
       // Preserve its identity for stop recovery without inventing a paid intent.
-      if (!s.current && !transport) {
+      if (!s.current && !transport && ledgerEpoch === 0) {
         const job = runner.current();
         // Completed pre-boundary runs need only the future-dispatch fence.
         // Adopt live/unfinished writers for the existing shutdown recovery.
@@ -519,7 +595,7 @@ export function makeExecution({ root, taskId, provider, account = "operator", tr
     });
   }
   return {
-    root, provider, account, capabilities, state: read, current, reconcile, collect, cancel,
+    root, provider, account, ledgerEpoch, capabilities, state: read, current, reconcile, collect, cancel,
     recover: async ({ operationId, authorized = false } = {}) => {
       const pending=await locked(async s => {
       const job=s.current,ex=job?.execution;

package/lib/fs.mjs

@@ -14,10 +14,17 @@ export const HOME = homedir();
  * so a decision can be traced to the release that asked for it. Unknown rather than fatal if the file is missing:
  * a version string is never worth failing a run over.
  */
-export const VERSION = (() => {
-  try { return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version || "unknown"; }
-  catch { return "unknown"; }
+const PACKAGE = (() => {
+  try { return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")); }
+  catch { return {}; }
 })();
+export const VERSION = PACKAGE.version || "unknown";
+
+/**
+ * The published npm name, read from the same package.json. `init` prints the `npx` and `npm install -g` commands
+ * that run this package again, and a name typed into a command module would drift from the one npm publishes.
+ */
+export const PACKAGE_NAME = PACKAGE.name || "@uchibeke/gallivant";
 
 /**
  * When the code a process is running was last changed, as the newest mtime across `lib/`. Paired with `VERSION`

package/lib/task_delivery_contract.mjs

@@ -2,7 +2,7 @@
 import { COMPLETION_SCHEMA } from "./task_completion.mjs";
 export { COMPLETION_SCHEMA, COMPLETION_CAPABILITIES, coordinatorEntryActive } from "./task_completion.mjs";
 export const DELIVERY_VERSION = 1;
-export const CORE_VERSION = "0.2.0";
+export const CORE_VERSION = "0.2.1";
 // One byte limit for the built APort MCP resource, package and runtime reader.
 export const MAX_TASK_UI_BYTES = 2_000_000;
 export const deliveryError = (code, message) => Object.assign(new Error(message), { code, version: DELIVERY_VERSION });