@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/lib/commands/register.mjs

@@ -0,0 +1,249 @@
+// `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.
+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 { receiptHash } from "../deliverable.mjs";
+import { rememberRepo, defaultHarness } from "../config.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";
+
+/** 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 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);
+  // 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;
+  if (pr.isCrossRepository) throw new Error("fork PRs are not registered");
+  if (pr.state !== "OPEN") throw new Error(`PR is ${pr.state}`);
+
+  const { block } = parseBlock(pr.body);
+  const prdId = prdIdFor(pr.headRefName);
+  const found = state.findByPr(repo, pr.number);
+  const id = found ? found[0] : entryId(repo, prdId);
+  const existing = found ? found[1] : state.get(id);
+  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`);
+  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
+  // flag spellings and not values in unexpected positions: `--session '--approval-mode=yolo'` was accepted, and
+  // goose derives its session FILE from the name, so `--session ../../../etc/passwd` chose where that file went.
+  if (session && !isSessionFor(chosenHarness, session)) throw new Error(`--session "${String(session).slice(0, 60)}" is not a ${chosenHarness} session id; nothing was registered`);
+
+  if (worktree) await assertCheckout(git, worktree, repo, pr.headRefName);
+  const dir = worktree || existing?.worktree || await git.fromBranch({ nameWithOwner: repo, prdId, branch: pr.headRefName, path: worktreePath(config, repo, prdId) });
+  // The final harness and session pair, checked as a PAIR. `--session` is validated against the chosen harness above,
+  // but an INHERITED session never was: `--harness codex` with no `--session` carried the old harness's id straight
+  // through, so changing claude to opencode kept a UUID where opencode needs `ses_...`. The next fix round then resumed
+  // an id its harness cannot mean, and the block written with it was refused by `parseBlock` on the way back, which
+  // kills the recovery the block exists for.
+  //
+  // Cleared rather than refused. A session id from another harness is not a mistake the operator made, it is a value
+  // that has no meaning under the new harness: opencode cannot resume claude's conversation whatever it is called. So
+  // the honest result is no session, which is what a fresh registration has, and the next fix round starts one. What it
+  // must not be is silent, because the operator loses a conversation they may have wanted: the drop is logged with both
+  // harnesses and the id, and `register` returns the session it actually stored so the caller never reports a resume it
+  // did not keep. An explicit `--session` is a different case and still refuses above, because an operator who typed an
+  // id meant that id.
+  let chosenSession = session || existing?.session || block?.session || null;
+  const from = existing?.session === chosenSession ? existing.harness : block?.harness;
+  if (chosenSession && !session && (from !== chosenHarness || !isSessionFor(chosenHarness, chosenSession))) {
+    log.warn(`${id}: session ${chosenSession} is not a ${chosenHarness} session id${from && from !== chosenHarness ? ` (it is ${from}'s)` : ""}; dropped, and the next fix round will start a fresh ${chosenHarness} session`);
+    chosenSession = null;
+  }
+
+  // The block records the branch as it is; a hand-made branch keeps its name, and recovery only trusts our own.
+  // It is written when there is none, and rewritten when `--harness` or `--session` overrode what it records. The
+  // invariant is that the block and the entry never disagree about identity: reconciliation rebuilds an entry from
+  // the block alone after `state.json` is lost, so a block left saying the old harness or the old session would
+  // restore the wrong one. The PRD path in an existing block is kept; only identity is being corrected here.
+  const blockPrd = block?.prd || existing?.prd || (isOurBranch(pr.headRefName) ? `docs/prds/${prdId}.md` : null);
+  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
+  // saying when the SECOND one fails.
+  //
+  // The body write is the point of no return, so it goes last. It changes the recovery identity: `reconcile` rebuilds
+  // an entry from the block alone once `state.json` is lost, reading the harness and the session out of it. With the
+  // body written first and the comment then failing, `register` reported that nothing was reset and left the registry
+  // on the OLD identity while GitHub already recorded the new one, so a running daemon and a later recovery resumed
+  // different harnesses or different sessions for the same PR. That is the one outcome no retry recovers from, because
+  // neither side is wrong on its own terms and nothing compares them.
+  //
+  // The comment is safely repeatable, which is what qualifies it to go first. `countRounds` takes the LAST reset
+  // marker among the daemon's own comments and counts the round comments after it (`events.mjs:208`), so a second
+  // marker counts exactly as one does. A failed body write therefore leaves a reset comment on the PR, the registry
+  // untouched, and an identity that still agrees with itself on both sides; running the same command again completes
+  // the reset and the extra comment changes no count.
+  //
+  // Throwing is the choice for both, where the tick's equivalent has to leave a retryable state instead: `register` is
+  // one interactive command with an operator in front of it, and it already refuses for other preconditions (a fork
+  // PR, a closed PR, an unconfigured harness, a mistyped `--worktree`).
+
+  // The reset comment IS the reset boundary. `countRounds` finds it among the daemon's own comments and counts the
+  // round comments after it; with the comment missing, every round comment of every earlier round is still in front of
+  // 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.`); }
+  }
+  // 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"}${!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,
+  // which is how a retargeted PR is picked up on the next register.
+  const prBase = typeof pr.baseRefName === "string" && pr.baseRefName ? pr.baseRefName : null;
+  const base = existing || newEntry({ prd: blockPrd, harness: chosenHarness, repo, branch: pr.headRefName, worktree: dir, state: STATES.prOpen, nowIso: nowIso(), base: prBase });
+  // A fresh registration sees the PR's whole history, so feedback already on it gets addressed; a reset starts now.
+  // A reset keeps `last.run` and its exit so the tick never re-settles a run that already ended.
+  //
+  // Floored to the second. GitHub stamps comments and reviews to the second while `nowIso()` carries milliseconds,
+  // and the cursor comparison is inclusive of its own boundary, so a cursor of 02:00:00.500Z would sit after every
+  // 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,
+    ...(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.
+    //
+    // `round_comment` goes with `iteration`, for the same reason and one more. It is the comment a counted round still
+    // owes the PR, and the reset zeroes the count, so a debt carried across it would announce a round the registry no
+    // longer claims: the daemon would post "round 0" and `why` would report a recovery counting minus one. The reset
+    // comment posted above is the new boundary anyway, so every marker before it is already outside the count and one
+    // more would change nothing. `labels_pending` goes with them, though it is inert rather than wrong: it is only read
+    // on a `needs-human` entry and `needsHuman` recomputes it on the next stop, so a stale true never acts. It is
+    // cleared anyway, because a reset entry carrying a debt from before the reset is a thing a reader has to reason
+    // about, and there is no reading of it that should survive.
+    //
+    // `prd_divergence` goes with `reason` for the same reason and is inert in the same way. It is the difference between
+    // the brief the run started against and the operator's own copy, recorded when the tick stopped the entry for it, and
+    // every reader of it (`status`, `why`, the tracker) recomputes the comparison live rather than trusting the field. So
+    // a stale one never decides anything. It is cleared because a reset entry carrying the record of a stop it no longer
+    // has is a thing a reader has to reason about. What is deliberately NOT cleared is `checkout` and `prd_fingerprint`:
+    // those say where the operator's copy lives and what contract the snapshot carries, which a reset does not change,
+    // and dropping them would silently turn the comparison off for a PR the operator has just asked to watch again.
+    state: STATES.prOpen, reason: null, retry: null, network_retry: null, iteration: 0, round_comment: null, public_fix: null, labels_pending: false, prd_divergence: null,
+    // `checks_sha` is null, and `up.mjs`'s `reconcile` now agrees rather than setting it to the recovered head. It names
+    // the head whose failing checks were already dispatched, and on a PR being taken over no head qualifies: a fix that
+    // had been dispatched and had pushed would have moved the head, so red checks on the head that is actually there
+    // have not been addressed by anything, and the operator running this command is asking for them to be.
+    cursor: { since, dispatched: [], fixed_sha: pr.headRefOid, checks_sha: null, receipt_hash: receiptHash(pr.body) },
+    rereview: { at: since, nudged: false },
+    last: existing ? { ...(existing.last || {}), at: nowIso(), event: "reset by register" } : null,
+    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}`));
+  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(); }
+}
+
+/**
+ * A worktree passed on the command line is stored as given and the harness then edits and pushes from it, so it is
+ * checked before it is accepted: same repository on `origin`, already on the PR's head branch. A mistyped or stale
+ * path is an error rather than a second repository quietly taking the session's commits. It is never relocated or
+ * re-cloned, because a resumed session is keyed to the directory it ran in.
+ */
+async function assertCheckout(git, dir, repo, branch) {
+  if (!git.exists(dir)) throw new Error(`--worktree ${dir} is not a git checkout`);
+  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}`);
+  let current;
+  try { current = await git.currentBranch(dir); }
+  catch (e) { throw new Error(`--worktree ${dir}: cannot read the checked-out branch: ${e.message}`); }
+  if (current !== branch) throw new Error(`--worktree ${dir} is on ${current}, not the PR's branch ${branch}; check it out there first`);
+}

package/lib/commands/resume.mjs

@@ -0,0 +1,224 @@
+// 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";
+import { resolveHandle, handleFor, STATES } from "../state.mjs";
+import { readRepositoryText, writeRepositoryText, repositoryPath } from "../repository_files.mjs";
+import { makeTick } from "../tick.mjs";
+import { adapterFor, capabilitiesFor } from "../harness.mjs";
+import { resumePrompt, startPrompt } from "../prompt.mjs";
+import { verifyCommands, parsePrd, prdDivergence, sourceDivergence, sourceDiff, sourcePathsOf, divergenceReason, renderDivergence, resolvePrdSnapshot, retakePrdSnapshot } from "../prd.mjs";
+import { criteriaFromPrd, receiptInstructions } from "../deliverable.mjs";
+import { nowIso, floorSecond } from "../time.mjs";
+import { requireHarness } from "../probe.mjs";
+import { executionRunner, unsubmittedInitialDispatch } from "../execution.mjs";
+import { assertAgentsCheckout } from "../openai_agents_sources.mjs";
+
+/** States worth resuming. A `done` entry is merged or closed, and a `running` one already has a live run. */
+const RESUMABLE = new Set([STATES.needsHuman, STATES.prOpen, STATES.ready]);
+
+export async function resume(ctx, { handle, note = null, resnapshot = false, freshSession = false, automaticNetworkRecovery = false }) {
+  const { state, git, log, readPrd } = ctx;
+  const id = resolveHandle(state.entries(), handle);
+  let entry = state.get(id);
+  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`);
+  const runner = executionRunner(ctx, id);
+  const initialDispatch = !entry.session ? unsubmittedInitialDispatch(entry, runner) : null;
+  if (!entry.session && !initialDispatch) throw new Error(`${handleFor(id, entry)} has no session to resume and no proven unsubmitted initial launch. Inspect its start/execution ownership before retrying; remove the entry only if the work is no longer wanted.`);
+  if (initialDispatch && !readPrd(id)) throw new Error("unsubmitted initial launch requires its saved approved brief; restore it before resume");
+
+  const divergence = prdDivergence({ id, entry, readPrd });
+  const divReason = divergenceReason(divergence);
+  let briefChanged = [...(entry.brief_changes ?? [])];
+  if (divReason) {
+    if (divergence.verdict !== "changed" || !resnapshot) {
+      throw new Error([
+        `${handleFor(id, entry)}: ${divergence.why}`,
+        renderDivergence(divergence),
+        divergence.verdict === "changed"
+          ? `Nothing was resumed. The session holds the brief this run started against, so resuming would put it back to work on one contract while the gate judges another.\nDecide: rerun with --resnapshot to make the edited brief the brief (the session is told what changed), or put the brief back the way it was.`
+          : divergence.verdict === "illegal"
+            ? `Nothing was resumed. ${divergence.path} would be refused by \`gallivant start\` as it stands, so it cannot become the brief the gate judges. Fix it and \`gallivant ready\` it again.`
+            : `Nothing was resumed. Restore the file, or \`gallivant remove ${handleFor(id, entry)}\` if the work is no longer wanted.`,
+      ].filter(Boolean).join("\n"));
+    }
+  }
+
+  if (resnapshot && divergence.repo && divergence.repo.harness !== entry.harness) {
+    throw new Error(`${handleFor(id, entry)}: cannot change harness from ${entry.harness} to ${divergence.repo.harness} with --resnapshot; the recorded session belongs to ${entry.harness}. Restore the harness or start a new entry.`);
+  }
+  const sources = sourceDivergence({ id, entry, readSource: ctx.readSource });
+  const sourceChanges = sourceDiff(sources);
+  if (sourceChanges.length && !resnapshot) {
+    throw new Error(`${handleFor(id, entry)}: carried files differ from the snapshot:\n${sourceChanges.join("\n")}\nNothing was resumed. Restore the files or use --resnapshot to accept the edited sources; remove deleted files from the brief's sources list first.`);
+  }
+  if (resnapshot && sourceChanges.length && !divergence.repo) throw new Error("cannot resnapshot carried files without the operator's brief; restore the brief first");
+  const acceptedSources = resnapshot && divergence.repo ? sourcePathsOf(divergence.repo) : null;
+  const sourceTexts = new Map();
+  for (const rel of acceptedSources ?? []) {
+    const text = readRepositoryText(entry.checkout, rel);
+    if (text.includes("\u0000")) throw new Error(`${rel} is not text`);
+    sourceTexts.set(rel, text);
+  }
+
+  if (freshSession && (!entry.session || !entry.learning?.rules?.length && !entry.learning_revocation?.freshSessionRequired)) throw new Error("fresh-session requires recorded learned context or its revocation; no task state was reset");
+  if (freshSession && !readPrd(id)) throw new Error("fresh-session requires the saved approved brief for continuity");
+  const current = runner.current();
+  if (current?.running) throw new Error(`${handleFor(id, entry)} already has a run in flight (${current.id}); wait for it or stop it first`);
+  if (entry.last?.run && entry.last.exit == null) {
+    throw new Error(`${handleFor(id, entry)}: run ${entry.last.run} still needs settling; wait for the daemon (gallivant up) before resuming`);
+  }
+
+  // Manual resume does not pass through the daemon's probes. Refuse before recreating or merging the checkout,
+  // or accepting a changed brief, so upgrading and rerunning resume preserves the stopped run exactly as it was.
+  if (runner.capabilities?.transport === "remote") {
+    if (!runner.capabilities.available) throw new Error(`execution provider unavailable: ${runner.capabilities.reason}`);
+  }
+  await requireHarness(entry.harness, ctx.config);
+
+  const recreated = !git.exists(entry.worktree);
+  if (recreated) {
+    log.info(`${id}: recreating the checkout at ${entry.worktree}`);
+    await git.fromBranch({ nameWithOwner: entry.repo, prdId: id.split("/").pop(), branch: entry.branch, path: entry.worktree });
+  }
+
+  const tick = makeTick({ ...ctx, ownLogin: ctx.ownLogin ?? "resume" });
+
+  // A correction must be able to recover unfinished work, including operator-carried
+  // files. Leave the index and tree intact; only the automatic base merge is deferred.
+  const tree = git.dirty ? await git.dirty(entry.worktree, { strict: true }) : null;
+  const uncommitted = tree && (tree.modified || tree.untracked) ? tree : null;
+  if (capabilitiesFor(entry.harness).transport === "remote" && uncommitted) {
+    await assertAgentsCheckout({ worktree: entry.worktree, overlays: [entry.prd, ...(acceptedSources ?? entry.sources ?? [])].filter(Boolean) });
+  }
+  const copyingBrief = initialDispatch || divReason || recreated || briefChanged.length || sourceChanges.length;
+  const sourcesToCopy = acceptedSources ?? ((initialDispatch || recreated || briefChanged.length) ? entry.sources ?? [] : []);
+  if (copyingBrief || sourcesToCopy.length) {
+    // Explicitly accepting a revised contract may replace its previous snapshot,
+    // but must never overwrite session edits to that file. Unrelated unfinished
+    // task files and unchanged carried instructions do not block the correction.
+    const replacements = sourcesToCopy.map(rel => [rel, ctx.readSource(id, rel), sourceTexts.get(rel) ?? ctx.readSource(id, rel)]);
+    if (entry.prd && (divReason || recreated || briefChanged.length)) replacements.push([entry.prd, readPrd(id), divReason ? divergence.repoText : readPrd(id)]);
+    for (const [rel, before, after] of replacements) {
+      let current = null;
+      try { current = readRepositoryText(entry.worktree, rel); }
+      catch (error) { if (error.code !== "ENOENT") throw error; }
+      // Ignored files do not appear in Git status. Compare their bytes as well;
+      // absent files in a clean/recreated checkout are safe to restore.
+      if ((current !== null || uncommitted && !initialDispatch) && current !== before && current !== after) {
+        throw new Error(`Cannot resnapshot ${rel}: local edits differ from both the previous snapshot and the accepted replacement. Preserve those edits before retrying; no files or snapshots were replaced.`);
+      }
+    }
+  }
+
+  // A failed fetch or merge must leave the accepted contract unchanged.
+  const merged = uncommitted ? null : await tick.mergeBaseInto(id, entry);
+  if (merged?.conflict) {
+    throw new Error([
+      `${handleFor(id, entry)}: ${entry.branch} cannot be merged with origin/${merged.base}: ${merged.why}`,
+      "Nothing was resumed, and the checkout was left clean: the merge was aborted.",
+      `Resolve it in ${entry.worktree} (\`git merge origin/${merged.base}\`, fix the conflicts, commit, push), then resume again.`,
+    ].join("\n"));
+  }
+  if (merged?.merged) entry = state.get(id) ?? entry;
+
+  await tick.reopen(id, entry);
+  if (copyingBrief && entry.prd) repositoryPath(entry.worktree, entry.prd, { createParents: true });
+  for (const rel of sourcesToCopy) repositoryPath(entry.worktree, rel, { createParents: true });
+  briefChanged = [...new Set([...briefChanged, ...(divReason ? divergence.diff : []), ...sourceChanges])];
+  // Persist the notice before snapshots move, so a failed write or spawn cannot silently lose it.
+  if (briefChanged.length) state.update(id, { brief_changes: briefChanged });
+
+  // Source writes must succeed before accepting a new manifest in the authoritative PRD.
+  if (acceptedSources) for (const [rel, text] of sourceTexts) ctx.writeSource(id, rel, text);
+
+  if (divReason) {
+    resolvePrdSnapshot(ctx, { id, entry, divergence, by: "gallivant resume --resnapshot" });
+    entry = state.get(id);
+  } else if (divergence.verdict === "same" && divergence.repoText !== undefined && divergence.repoText !== readPrd(id)) {
+    retakePrdSnapshot(ctx, { id, divergence });
+    log.info(`${id}: the brief was edited outside its contract; snapshot re-taken from ${divergence.path} before resuming`);
+    entry = state.get(id);
+  }
+
+  if (acceptedSources) {
+    entry = state.update(id, { sources: acceptedSources });
+  }
+
+  const text = readPrd(id);
+  const parsed = text ? parsePrd(text, `${id}.md`) : null;
+
+  if ((initialDispatch || briefChanged.length || recreated) && entry.prd && text) writeRepositoryText(entry.worktree, entry.prd, text);
+  for (const rel of sourcesToCopy) {
+    const source = ctx.readSource(id, rel);
+    if (source == null) throw new Error(`${rel}: carried-file snapshot is missing; restore it before resuming`);
+    writeRepositoryText(entry.worktree, rel, source);
+  }
+
+  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 ?? [] }),
+    "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({
+    repo: entry.repo,
+    pr: entry.pr,
+    base: entry.base,
+    branch: entry.branch,
+    reason: entry.reason,
+    note,
+    verify: parsed ? verifyCommands(parsed) : [],
+    receipt: parsed ? receiptInstructions(criteriaFromPrd(parsed), id) : null,
+    briefChanged,
+    unpushed,
+    merged: merged?.merged ? merged : null,
+    uncommitted,
+    carried: entry.sources ?? [],
+  });
+
+  if (freshSession) {
+    if (runner.capabilities && !runner.freshLearningSession) throw new Error("execution provider cannot establish fresh learning continuity");
+    const transition = entry.learning_continuity?.status === "prepared" ? entry.learning_continuity : {
+      status: "prepared", previousSession: entry.session, previousRun: entry.last?.run ?? null,
+      newSession: runner.capabilities?.transport === "remote" ? null : adapterFor(entry.harness).newSession(),
+    };
+    // Durable intent is separate from task/review ownership; failures retain the
+    // old session and retry the same newly allocated local session.
+    entry = state.update(id, { learning_continuity: transition });
+    if (runner.freshLearningSession) await runner.freshLearningSession({ runId: transition.previousRun, sessionId: transition.previousSession });
+    prompt = `Continue this same logical task in a fresh provider session. Preserve the existing branch, checkout, PR, review cursors, iteration and budget. Previous provider memory is unavailable. Reread the approved brief and carried files before proceeding.\n\nApproved brief snapshot:\n${text}\n\n${prompt}`;
+    entry = { ...entry, session: null };
+  }
+
+  // The resumed process may publish and exit before the daemon's first poll. Begin public-output observation
+  // before spawning it, and preserve an earlier boundary so unresolved replies cannot disappear on resume.
+  if (!entry.public_since) {
+    const saved = state.update(id, { public_since: floorSecond(nowIso()) });
+    entry = freshSession ? { ...saved, session: null } : saved;
+  }
+  const { job, session, managed } = await tick.startRun(id, initialDispatch ? { ...entry, initial_dispatch: initialDispatch } : entry, { name: initialDispatch ? "start" : "resume", prompt,
+    dispatchDeadline: automaticNetworkRecovery ? Date.parse(entry.network_retry.first_at) + NETWORK_RECOVERY_WINDOW : null });
+
+  state.update(id, current => ({
+    ...learningDeliveryPatch(current, managed || {}, job),
+    ...(freshSession ? { learning_continuity: { ...entry.learning_continuity, status: "accepted", run: job.id, session }, learning_revocation: null } : {}),
+    state: entry.pr ? STATES.prOpen : STATES.running,
+    reason: null,
+    gate_skipped: null,
+    labels_pending: false,
+    public_fix: null,
+    retry: null,
+    network_retry: automaticNetworkRecovery ? { ...entry.network_retry, phase: "running", next_at: null } : null,
+    brief_changes: null,
+    session,
+    ...(initialDispatch ? { initial_dispatch: null } : {}),
+    ...(job.execution ? { execution: job.execution } : {}),
+    prd_divergence: null,
+    timeout: null,
+    last: { at: nowIso(), run: job.id, exit: null, event: `resumed after ${entry.reason ?? entry.state}${briefChanged.length ? ", brief resnapshotted" : ""}` },
+    updated_at: nowIso(),
+  }));
+  await learningDelivered(ctx, id);
+  log.info(`${id}: resumed ${entry.harness} session ${session} (run ${job.id})${briefChanged.length ? ` against the edited brief (${briefChanged.length} change${briefChanged.length === 1 ? "" : "s"})` : ""}`);
+  return { id, handle: handleFor(id, entry), run: job.id, session, ...(initialDispatch ? { initialLaunch: true } : {}), worktree: entry.worktree, resnapshotted: briefChanged, attach: runner.capabilities?.transport === "remote" ? null : adapterFor(entry.harness).attach({ pr: entry.pr, session }) };
+}