@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/commands/status.mjs

@@ -0,0 +1,150 @@
+// `gallivant status`: what needs you, what is running, and whether the daemon is alive. Built as a model first so
+// `--json` and any UI get the same facts the text view shows.
+import { STATES, handleFor } from "../state.mjs";
+import { readDaemon } from "./up.mjs";
+import { ago } from "../time.mjs";
+// Retries after review is clear, imported from the file that writes them so status cannot drift from the loop.
+import { READY_LABEL_WRITE, COMPLETION_GATE } from "../tick.mjs";
+import { briefDivergence, divergenceReason } from "../prd.mjs";
+import { chainRows } from "../chains.mjs";
+import { executionRunner } from "../execution.mjs";
+import { networkRecoveryDetail } from "../network_recovery.mjs";
+import { probeStatus } from "../probe.mjs";
+
+/**
+ * The divergence for one entry, never fatal. `status` is what an operator runs when something already looks wrong, so a
+ * brief that cannot be read must not be the thing that makes the whole command fail: the row loses one field and the
+ * rest of the answer still arrives.
+ */
+function divergenceOf(ctx, id, entry, readPrd) {
+  try { return briefDivergence({ id, entry, readPrd, readSource: ctx.readSource }); }
+  catch { return { verdict: "unknown", why: "", diff: [] }; }
+}
+
+export function model(ctx) {
+  const { home, config, state, runnerFor, log, readPrd = () => null } = ctx;
+  const daemon = readDaemon(home);
+  const rows = state.entries().map(([id, e]) => {
+    // The brief compared with the operator's own copy, on every row that is still being worked on. The comparison is the
+    // tick's too, but `status` runs it itself rather than reading a flag the tick left, for two reasons. An operator who
+    // has JUST edited the brief will run `status` before the next tick comes round, and a row that only knew what the
+    // last tick knew would say nothing for two minutes about the thing they are asking about. And `status` runs in the
+    // operator's own session, where their checkout is present and readable, which is not guaranteed for the daemon.
+    //
+    // A `done` entry is not compared: it is merged or closed, there is nothing left to certify, and an operator
+    // reorganising their briefs afterwards must not be told about finished work.
+    const divergence = e.state === "done" ? { verdict: "unknown", why: "", diff: [] } : divergenceOf(ctx, id, e, readPrd);
+    const run = executionRunner(ctx, id).current();
+    // A run is in flight from dispatch until the tick records its exit, whether or not the process is still alive.
+    const inFlight = !!e.last?.run && e.last?.exit == null;
+    const handle = handleFor(id, e);
+    const round = `round ${e.iteration}/${config.max_iterations}`;
+    let section, label, detail;
+    if (e.network_retry?.phase === "waiting" && !e.dispatch_stopped && e.state !== STATES.done) { section = "running"; label = "retrying"; detail = networkRecoveryDetail(e.network_retry); }
+    else if (e.state === STATES.needsHuman) { section = "needs_you"; label = "needs-human"; detail = e.reason; }
+    // `gate_skipped` says the completion gate never ran, which is a different thing from passing it, and a person
+    // deciding whether to merge on this line needs to be told which of the two it was.
+    else if (e.state === STATES.ready) { section = "needs_you"; label = "ready"; detail = e.gate_skipped ? `green, no blocking findings, RECEIPT NOT CHECKED (${e.gate_skipped})` : "green, no blocking findings, receipt accepted"; }
+    else if (e.state === STATES.done) { section = "done"; label = "done"; detail = ""; }
+    // `retry` names the one GitHub write the tick is declining a step for, and it is the truest thing this row can say
+    // while it is set. Without it, a start run whose identity block will not write read as "ended, settling on the next
+    // tick" on every poll: the process HAD ended, and the tick was not settling it, it was retrying one write and
+    // counting the failures. It outranks the run's own liveness because it is what the entry is actually waiting on.
+    //
+    // The label cannot come from the state alone. A `pr-open` entry is `fixing` for the two removals, which a fix round
+    // genuinely follows, but the ready-label WRITE is reached only after every readiness condition has passed: checks
+    // green, reviewer clear, receipt accepted. Nothing is being fixed, the PR is one label away from a person, and the
+    // row said `fixing` for it because the state was the only thing consulted. `blocked` says the entry is finished and
+    // held up by GitHub, which is what the operator needs to hear.
+    else if (e.retry) { section = "running"; label = [READY_LABEL_WRITE, COMPLETION_GATE].includes(e.retry.op) ? "blocked" : e.state === STATES.running ? "implementing" : "fixing"; detail = `${e.retry.op} failing (${e.retry.count}), retrying${e.retry.error ? `: ${e.retry.error}` : ""}`; }
+    else if (inFlight) { section = "running"; label = e.state === STATES.running ? "implementing" : "fixing"; detail = run?.running ? (e.last?.event || "") : "ended, settling on the next tick"; }
+    else if (e.state === STATES.running) { section = "running"; label = "starting"; detail = "waiting for the daemon to settle the run"; }
+    else { section = "running"; label = "waiting"; detail = e.rereview?.nudged ? "on reviewer, nudged once" : "on reviewer"; }
+    if (inFlight && run?.execution && e.state !== STATES.needsHuman) {
+      label = run.execution.providerState;
+      detail = run.execution.recoveryAction || `last observed ${run.execution.observedAt ?? "unknown"}; provider progress is separate from review readiness`;
+    }
+
+    // A diverged brief outranks everything above and moves the row into NEEDS YOU, whatever the entry is otherwise
+    // doing. It outranks them because it is the only thing on this row that says the work itself may be aimed at the
+    // wrong target: a red check, a waiting reviewer and a retrying label are all questions about work whose brief nobody
+    // disputes. And it moves sections because the operator is the only one who can resolve it, so a row sitting under
+    // RUNNING would be telling them to wait for a daemon that is going to stop the entry the moment it judges it.
+    //
+    // The row says so for an entry the tick has ALREADY stopped too, where `reason` is one of the three: the reason
+    // alone is a word, and `status` has room for the first difference, which is the thing the operator has to look at.
+    const divReason = divergenceReason(divergence);
+    if (divReason) {
+      section = "needs_you";
+      label = e.state === STATES.needsHuman ? "needs-human" : "brief-moved";
+      detail = divergence.diff[0] ? `${divReason}: ${divergence.diff[0]}` : divReason;
+    }
+    return {
+      id, handle, section, label, detail, round, state: e.state, reason: e.reason, gate_skipped: e.gate_skipped ?? null,
+      // The branch this PR targets, or will target. It is on every row because the question "what will this open against?"
+      // has a wrong answer that costs a whole run, and before the PR exists there is nowhere else to read it.
+      base: e.base ?? null,
+      // When the daemon last merged the base into this branch, so an operator can see the history was changed and when.
+      base_merge: e.base_merge ?? null,
+      retry: e.retry ?? null, network_retry: e.network_retry ?? null, pr: e.pr, url: e.url || null, harness: e.harness, since: e.updated_at,
+      // `handle` rides along so a consumer can print the command that resolves it without rebuilding the handle from the
+      // other fields: the tracker does exactly that, and `handleFor` is not its to know.
+      divergence: divReason ? { verdict: divergence.verdict, reason: divReason, why: divergence.why, diff: divergence.diff, path: divergence.path ?? null, handle } : null,
+      run: run ? { id: run.id, running: run.running, startedAt: run.startedAt } : null,
+      execution: run?.execution ?? e.execution ?? null,
+    };
+  });
+  return {
+    daemon: daemon ? { alive: daemon.alive, unverified: Boolean(daemon.unverified), pid: daemon.pid, startedAt: daemon.startedAt, lastTick: daemon.lastTick, nextTick: daemon.nextTick, probes: daemon.probes || {}, stale: Boolean(daemon.stale) } : null,
+    latestError: log.latest(),
+    chains: chainRows(ctx),
+    needs_you: rows.filter(r => r.section === "needs_you"),
+    running: rows.filter(r => r.section === "running"),
+    done: rows.filter(r => r.section === "done"),
+  };
+}
+
+const pad = (s, n) => String(s ?? "").padEnd(n);
+
+export function render(m, { all = false, clock = Date } = {}) {
+  const lines = [];
+  if (m.daemon?.unverified) lines.push(`gallivant  daemon UNVERIFIED  pid ${m.daemon.pid} is alive; verify and stop the older daemon before restarting`);
+  else if (!m.daemon || !m.daemon.alive) lines.push("gallivant  daemon DOWN  run: gallivant up");
+  else {
+    const probes = Object.entries(m.daemon.probes).map(([k, p]) => `${k} ${probeStatus(p)}`).join("  ");
+    const next = m.daemon.nextTick ? `next in ${Math.max(0, Math.round((Date.parse(m.daemon.nextTick) - clock.now()) / 1000))}s` : "";
+    lines.push(`gallivant  daemon up since ${ago(m.daemon.startedAt, clock)}  last tick ${ago(m.daemon.lastTick, clock)}  ${next}  ${probes}`);
+    // A daemon running code that no longer exists on disk. Its own line rather than a word in the header, because the
+    // symptom it produces never points at the daemon: runs fail in whatever way the old code failed, so an operator
+    // reads a sandbox error or a git error and debugs that instead. See `codeStamp` in lib/fs.mjs.
+    if (m.daemon.stale) lines.push("           the daemon is running code older than what is installed; its runs use the old behaviour. Restart it: gallivant down && gallivant up");
+  }
+  if (m.latestError) lines.push(`latest error: ${m.latestError}`);
+  const section = (title, rows) => {
+    lines.push("", title);
+    if (!rows.length) { lines.push("  (none)"); return; }
+    for (const r of rows) {
+      // `why` is the hint for a moved brief as well as for a stop, because `why` is where the whole difference is
+      // printed and the row only has room for the first line of it.
+      const hint = r.label === "needs-human" || r.label === "brief-moved" ? `gallivant why ${r.handle}` : r.label === "ready" ? (r.url || "") : "";
+      // The base rides in the round column's neighbour rather than getting one of its own: it is short, it is constant for
+      // the life of an entry, and a column of its own would push the hint off an 80-column terminal.
+      lines.push(`  ${pad(r.handle, 26)} ${pad(r.label, 13)} ${pad(r.detail, 30)} ${pad(r.round, 11)} ${pad(r.base ? `-> ${r.base}` : "", 14)} ${pad(ago(r.since, clock), 10)} ${hint}`.replace(/\s+$/, ""));
+    }
+  };
+  section("NEEDS YOU", m.needs_you);
+  section("RUNNING", m.running);
+  if (all) section("DONE", m.done);
+  const chains = (m.chains || []).filter(c => all || !["done", "cancelled"].includes(c.status));
+  if (chains.length) {
+    lines.push("", "CHAINS");
+    for (const c of chains) lines.push(`  ${c.name}  ${c.status}  ${c.completed}/${c.total} merged -> ${c.base}  ${c.reason}  gallivant chain ${c.name}`);
+  }
+  return lines.join("\n");
+}
+
+export function status(ctx, { all = false, json = false } = {}) {
+  const m = model(ctx);
+  const text = json ? JSON.stringify(m, null, 2) : render(m, { all });
+  return { text, exitCode: m.daemon?.alive ? 0 : 1 };
+}

package/lib/commands/task.mjs

@@ -0,0 +1,73 @@
+// Thin CLI adapter. Structured clients use createTaskService directly; question
+// IDs, revision checks and transitions are owned by that same implementation.
+import { createTaskService, TASK_VERSION } from "../tasks.mjs";
+import { MAX_INPUT_BYTES } from "../task_contract.mjs";
+import { acquireCliMutation, withTaskMutationOwner } from "../daemon.mjs";
+import { taskError } from "../task_store.mjs";
+
+export async function readTaskStdin(stream = process.stdin, timeoutMs = 5000) {
+  if (stream.isTTY) throw taskError("TASK_INPUT", "pipe task text to stdin or pass it as an argument; preparation never opens an interactive prompt");
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    const cleanup = () => { clearTimeout(timer); stream.removeListener("data", data); stream.removeListener("end", end); stream.removeListener("error", error); stream.pause(); };
+    const error = e => { cleanup(); reject(e); };
+    const data = chunk => {
+      size += Buffer.byteLength(chunk);
+      if (size > MAX_INPUT_BYTES) return error(taskError("TASK_INPUT", `stdin exceeds ${MAX_INPUT_BYTES} bytes`));
+      chunks.push(Buffer.from(chunk));
+    };
+    const end = () => { cleanup(); resolve(Buffer.concat(chunks).toString("utf8")); };
+    const timer = setTimeout(() => error(taskError("TASK_INPUT", "stdin did not finish within five seconds; pipe a complete request or pass text explicitly")), timeoutMs);
+    stream.on("data", data).once("end", end).once("error", error);
+    stream.resume();
+  });
+}
+
+export async function taskCommand(ctx, { args, values, service = null, stdin = readTaskStdin }) {
+  const [first, id] = args;
+  const operation = ["prepare", "answer", "resume", "validate", "start", "inspect", "list"].includes(first) ? first : "prepare";
+  const expectedRevision = values.revision === undefined ? undefined : Number(values.revision);
+  const shared = { taskId: id, expectedRevision, noDaemon: values["no-daemon"] };
+  if (values.context !== undefined && !["prepare", "answer"].includes(operation)) throw taskError("TASK_INPUT", "--context is supported by task prepare and task answer");
+  if (values["completion-target"] !== undefined && operation !== "prepare") throw taskError("TASK_INPUT", "--completion-target is selected only at task creation");
+  if (operation === "list") return (service || createTaskService(ctx)).list();
+  if (operation === "inspect") return (service || createTaskService(ctx)).inspect(shared);
+  const owner = acquireCliMutation(ctx.home);
+  try { return await withTaskMutationOwner(ctx.home, owner, async () => {
+    service ||= createTaskService(ctx, { mutationOwner: owner });
+    if (operation === "resume") return await service.resume(shared);
+    if (operation === "validate") return await service.validate(shared);
+    if (operation === "start") return await service.start({ ...shared, run: values.run });
+    if (operation === "answer") {
+      const answers = Object.create(null);
+      for (const value of values.answer || []) {
+        const split = value.indexOf("=");
+        if (split < 1) throw taskError("TASK_INPUT", "--answer takes question-id=text");
+        const key = value.slice(0, split), text = value.slice(split + 1);
+        if (Object.hasOwn(answers, key)) throw taskError("TASK_INPUT", `duplicate answer identifier ${key}`);
+        answers[key] = text;
+      }
+      return await service.answer({ ...shared, answers, operationId: values["request-id"], context: values.context || [], verifyCommands: values.verify || [] });
+    }
+    const textArgs = first === "prepare" ? args.slice(1) : args;
+    if (values.stdin && textArgs.length) throw taskError("TASK_INPUT", "use text or --stdin, not both");
+    const text = textArgs.length ? textArgs.join(" ") : await stdin();
+    return await service.prepare({ text, dir: values.dir, repo: values.repo, base: values.base, harness: values.harness, context: values.context || [], requestId: values["request-id"], run: values.run, noDaemon: values["no-daemon"], verifyCommands: values.verify || [], ...(values["completion-target"] === undefined ? {} : { completion: { target: values["completion-target"] } }) });
+  }); } finally { owner.release(); }
+}
+
+export function renderTask(result) {
+  if (result.tasks) return result.tasks.map(t => `${t.taskId}: ${t.status} (revision ${t.revision})`).join("\n") || "No saved tasks.";
+  return [
+    `${result.taskId}: ${result.status} (revision ${result.revision}, contract v${TASK_VERSION})`,
+    result.draft && `Draft: ${result.draft.path}`,
+    ...result.questions.map(q => `${q.id}: ${q.text}`),
+    ...result.failures,
+    result.dispatchRecovery && `Dispatch recovery: inspect the clone at ${result.dispatchRecovery.worktree}; start ownership is retained`,
+    result.implementation && `Implementation: ${result.implementation.id} (run ${result.implementation.run})`,
+    result.completion && `Completion target: ${result.completion.target} (${result.completion.status})`,
+    result.daemonError,
+    `Next: ${result.nextAction}`,
+  ].filter(Boolean).join("\n");
+}

package/lib/commands/up.mjs

@@ -0,0 +1,228 @@
+// `gallivant up`: the daemon. Reconciles with GitHub on boot, then ticks on a setTimeout chain so ticks never
+// overlap. Health is a file (daemon.json) that `status` reads; a second daemon exits when the first is alive.
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { openSync, closeSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { makeTick } from "../tick.mjs";
+import { checkGh, checkHarness, probeFix } from "../probe.mjs";
+import { makeProviderHealth } from "../provider_health.mjs";
+import { EXECUTION_LIMITS } from "../execution_io.mjs";
+import { readJson, writeJsonAtomic, VERSION, codeStamp, gallivantHome } from "../fs.mjs";
+import { nowIso, later } from "../time.mjs";
+import { parseBlock } from "../block.mjs";
+import { countRounds, lastOwnCommentAt, reviewerClock } from "../events.mjs";
+import { ensurePrdSnapshot } from "../prd.mjs";
+import { newEntry, entryId, STATES } from "../state.mjs";
+import { receiptHash } from "../deliverable.mjs";
+import { worktreePath, isOurBranch, prdIdFromBranch } from "../git.mjs";
+import { daemonPath, readDaemon, assertDaemonUsable, acquireDaemon, assertUnpinnedHome } from "../daemon.mjs";
+import { repoNames } from "../config.mjs";
+
+export { daemonPath, readDaemon } from "../daemon.mjs";
+
+
+/**
+ * `gallivant down`: stop the daemon.
+ *
+ * It existed as a signal and not as a command, which is a gap an operator pays for at the worst moment. `up` already
+ * traps SIGTERM and writes `stoppedAt` before exiting, so the mechanism was there; what was missing was any way to
+ * reach it without reading a pid out of `ps`. That came up for real: a daemon had to be stopped because it was running
+ * stale code, and the instruction was a raw `kill <pid>`.
+ *
+ * SIGTERM and not SIGKILL, so the trap runs and the heartbeat records that the daemon stopped on purpose rather than
+ * leaving a file that says it is alive with a pid that is not.
+ *
+ * It does not wait for a run to finish, and says so rather than deciding for the operator. A spawned session is its own
+ * process and survives the daemon; the next `up` settles it, because `last.exit` is null and that is what tells
+ * `settleRun` the run is still owed an outcome.
+ */
+export function down(ctx, { home = ctx?.home ?? gallivantHome() } = {}) {
+  const d = readDaemon(home);
+  if (!d) return { stopped: false, why: `no daemon has run under ${home}` };
+  if (!d.alive) return { stopped: false, why: `no daemon is running with a verified identity (pid ${d.pid}${d.stoppedAt ? `, stopped at ${d.stoppedAt}` : ""})`, pid: d.pid };
+  try { process.kill(d.pid, "SIGTERM"); }
+  catch (e) { return { stopped: false, why: `pid ${d.pid} could not be signalled (${e.code || e.message})`, pid: d.pid }; }
+  ctx?.log?.info?.(`daemon ${d.pid} sent SIGTERM`);
+  return { stopped: true, pid: d.pid, startedAt: d.startedAt };
+}
+
+/**
+ * Bring the registry in line with GitHub: every open PR of ours on a gallivant/* branch with a valid block is
+ * watched, iteration recovered from our round comments (since the last reset comment), cursors set so history is
+ * not replayed. The PRD snapshot is taken from the PR branch when the daemon has none; that copy was writable by
+ * the session, which the log says. Missing checkouts are recreated lazily by the tick when a run is needed.
+ */
+export async function reconcile(ctx, ownLogin) {
+  const { config, state, gh, log } = ctx;
+  const added = [];
+  for (const repo of repoNames(config)) {
+    let prs;
+    try { prs = await gh.prListMine(repo); } catch (e) { log.warn(`reconcile ${repo}: ${e.message}`); continue; }
+    for (const pr of prs || []) {
+      if (pr.isCrossRepository || !isOurBranch(pr.headRefName)) continue;
+      if (state.findByPr(repo, pr.number)) continue;
+      const { block, reason } = parseBlock(pr.body);
+      if (!block) { log.warn(`reconcile ${repo}#${pr.number}: ${reason}, ignored`); continue; }
+      if (block.branch !== pr.headRefName) { log.warn(`reconcile ${repo}#${pr.number}: block branch differs from head, ignored`); continue; }
+      const prdId = prdIdFromBranch(pr.headRefName);
+      const id = entryId(repo, prdId);
+      if (state.get(id)) { log.warn(`reconcile ${repo}#${pr.number}: id ${id} already in use, ignored`); continue; }
+      try { state.assertCanRegister(id); }
+      catch (e) { log.warn(`reconcile ${repo}#${pr.number}: ${e.message}, ignored`); continue; }
+      const [comments, headDate] = await Promise.all([gh.issueComments(repo, pr.number), gh.commitDate(repo, pr.headRefOid).catch(() => null)]);
+      const lastOwn = lastOwnCommentAt(comments, ownLogin);
+      await ensurePrdSnapshot(ctx, { id, repo, path: block.prd, ref: pr.headRefName });
+      // `base` is the branch the PR targets, read off the PR rather than guessed from config: a recovered entry has to merge
+      // in the branch this pull request will actually be merged into, and only GitHub knows which that is.
+      const entry = newEntry({ prd: block.prd, harness: block.harness, session: block.session, repo, branch: pr.headRefName, worktree: worktreePath(config, repo, prdId), pr: pr.number, url: pr.url, state: STATES.prOpen, nowIso: nowIso(), base: typeof pr.baseRefName === "string" && pr.baseRefName ? pr.baseRefName : null });
+      try { state.put(id, {
+        ...entry,
+        iteration: countRounds(comments, ownLogin),
+        // The receipt fingerprint comes from the body `prListMine` already returned, as every other writer of this
+        // cursor sets it. Left null, a receipt that was on the PR before the recovery read as a change the next time
+        // a run ended, so a run that did nothing counted as a round and posted "Completion receipt updated." to the
+        // PR, which `countRounds` then read back as a real round on the recovery after that.
+        //
+        // `checks_sha` is null here, the same as `register.mjs` sets it and for the same reason, which is the one thing
+        // the two files used to disagree about. It is the head whose failing checks were already dispatched, and no head
+        // qualifies on a recovery: a fix that had been dispatched AND had pushed would have moved the head, so failures
+        // on the head that is actually there have not been fixed by anything. The only case a recovery could dispatch
+        // twice is a run that was still in flight when the daemon died, and that run is orphaned and its work lost
+        // anyway, so redoing it is the point. Setting it to the recovered head instead suppressed those failures, and
+        // suppressing them is not the same as stopping for them: `checks-red` only fires when the reviewer verdict is
+        // not "waiting", and on a recovery with a bot reviewer that has not spoken it is, so a red head arrived
+        // unaddressed and the entry then stopped with `reviewer-silent`, naming the wrong thing entirely.
+        cursor: { since: later(lastOwn, headDate ?? pr.createdAt), dispatched: [], fixed_sha: pr.headRefOid, checks_sha: null, receipt_hash: receiptHash(pr.body) },
+        // Through `reviewerClock`, the one place that rule lives, rather than raw. Recovery happens because the operator
+        // lost state: a crash, a machine move. An unfloored clock stopped a PR whose last round comment was older than
+        // `stall_hours` with `reviewer-silent` on the FIRST tick after the daemon came back, for silence that accrued
+        // while no daemon was running to ask, and cost the operator a `register` to resume. The floor gives a recovered
+        // entry the same grace a freshly nudged one gets; the ask is not older than the nudge window, because whatever
+        // happened before this boot, the daemon is only asking now.
+        rereview: { at: reviewerClock({ config, pushedAt: later(lastOwn, pr.createdAt), floorAt: nowIso() }), nudged: false },
+        last: { at: nowIso(), event: "recovered from GitHub" },
+      }); } catch (e) {
+        // A CLI may have reserved this ID during the reads above. Never let one conflict prevent daemon startup.
+        log.warn(`reconcile ${repo}#${pr.number}: ${e.message}, ignored`); continue;
+      }
+      added.push(id);
+      log.info(`${id}: recovered from ${pr.url}`);
+    }
+  }
+  return added;
+}
+
+/**
+ * Start a daemon in the background and return once it is actually up, or null when one already is.
+ *
+ * `start` calls this because the two commands are one intention: a session that opens a pull request nobody watches
+ * is a silent stall, and an operator who has to remember a second command in a second terminal will sometimes not.
+ * The child is detached with its output to the log, so it outlives the terminal that ran `start`.
+ *
+ * It waits for verified process ownership, published before the first GitHub probe. A daemon still loading config
+ * has not acquired its lock and does not yet count as started.
+ */
+export async function upInBackground(ctx, { bin = process.execPath, script = fileURLToPath(new URL("../../bin/gallivant.mjs", import.meta.url)), waitMs = 10_000, sleep = ms => new Promise(r => setTimeout(r, ms)), spawnFn = spawn } = {}) {
+  assertUnpinnedHome(ctx.home);
+  const existing = readDaemon(ctx.home);
+  assertDaemonUsable(existing, { starting: true });
+  if (existing?.alive) return null;
+  const out = openSync(join(ctx.home, "daemon.log"), "a", 0o600);
+  let child;
+  let spawnError = null;
+  try {
+    child = spawnFn(bin, [script, "up"], { detached: true, stdio: ["ignore", out, out], env: { ...process.env, GALLIVANT_HOME: ctx.home } });
+    child.on?.("error", e => { spawnError = e; });
+    child.unref();
+  } finally { closeSync(out); }
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    assertUnpinnedHome(ctx.home);
+    const d = readDaemon(ctx.home);
+    assertDaemonUsable(d, { starting: true });
+    if (d?.alive) return d;
+    if (spawnError) throw new Error(`the daemon could not start: ${spawnError.message}; see ${join(ctx.home, "daemon.log")}`);
+    if (child.exitCode !== null) throw new Error(`the daemon exited immediately (code ${child.exitCode}); see ${join(ctx.home, "daemon.log")}`);
+    await sleep(200);
+  }
+  child.kill?.("SIGTERM");
+  throw new Error(`the daemon did not report itself within ${Math.round(waitMs / 1000)}s; startup was cancelled; see ${join(ctx.home, "daemon.log")}`);
+}
+
+export async function up(ctx, { once = false } = {}) {
+  const { home, config, gh, notify, log, clock = Date } = ctx;
+  const existing = readDaemon(home);
+  if (existing?.alive && existing.pid !== process.pid) throw new Error(`daemon already running (pid ${existing.pid})`);
+  if (existing?.unverified) throw new Error(`daemon pid ${existing.pid} has an unverifiable process identity; verify and stop the older daemon before restarting`);
+  const { owner, release } = acquireDaemon(home);
+  let ownLogin = null;
+  let timer = null;
+  const cleanup = () => {
+    if (timer) clearTimeout(timer);
+    try { writeJsonAtomic(daemonPath(home), { ...readJson(daemonPath(home), {}), ...owner, stoppedAt: nowIso() }); } catch { /* exiting */ }
+    try { release(); } catch { /* stale lock can be recovered next boot */ }
+    process.off("SIGINT", stop); process.off("SIGTERM", stop); process.off("exit", cleanup);
+  };
+  const stop = () => { cleanup(); process.exit(0); };
+  process.on("SIGINT", stop); process.on("SIGTERM", stop); process.on("exit", cleanup);
+  try {
+    // What code this daemon is actually running, recorded once at boot. `status` compares it with the code on disk and
+    // says so when they differ: node caches modules at import, so a daemon started before an upgrade goes on executing
+    // the old code with no symptom of its own. See `codeStamp` in lib/fs.mjs for the run this cost.
+    const bootCode = codeStamp();
+    // The live pid always wins over whatever a previous daemon left in the file.
+    // Health is a convenience for `status`, not part of the loop. A home that cannot be written must not stop the
+    // daemon doing the work it was started for. It matters twice over here: the recovery path below writes health
+    // again from inside its own catch, so an unguarded write there would escape the handler meant to keep one bad
+    // tick from killing the process.
+    const health = patch => {
+      try { writeJsonAtomic(daemonPath(home), { ...readJson(daemonPath(home), {}), ...patch, ...owner, login: ownLogin, stoppedAt: null, version: VERSION, code: bootCode }); }
+      catch (e) { log.warn(`cannot write ${daemonPath(home)} (${e.code || e.message}); status will not see this tick`); }
+    };
+    health({ starting: true });
+    ownLogin = await gh.user();
+    const providerHealth = makeProviderHealth({ home, clock, limits: config.execution, probe: (provider, account, signal) => checkHarness(provider, config, { signal }) });
+    const githubHealth = makeProviderHealth({ home, file: join(home, "github-health.json"), clock,
+      limits: { ...config.execution, progressMs: config.poll_seconds * 1000 },
+      probe: (_provider, _account, signal) => checkGh(gh, { signal }) });
+    const tickImpl = makeTick({ ...ctx, ownLogin, providerHealth });
+    health({ starting: false });
+    keepAwake();
+
+    const recovered = await reconcile(ctx, ownLogin);
+    if (recovered.length) log.info(`recovered ${recovered.length} PR(s)`);
+    const tickMs = Math.min(config.poll_seconds * 1000, config.execution?.progressMs || EXECUTION_LIMITS.progressMs);
+
+    /** One tick, with every failure caught: a daemon that dies on one bad tick is worse than one that logs it. */
+    const loop = async () => {
+      try {
+        const scopes = Object.keys(config.harness).map(h => [h, config.harness[h]?.account || "operator"]);
+        // Provider checks and GitHub/progress work use separate lanes. Failed or
+        // due/pending health reads fence only that account/provider, even before
+        // refresh gets a worker; the previous healthy cache cannot authorize work.
+        const refreshing = providerHealth.refresh(scopes);
+        const [results] = await Promise.all([tickImpl.tick(), refreshing, githubHealth.refresh([["gh", ownLogin]])]);
+        const probes = { gh: githubHealth.get("gh", ownLogin), ...Object.fromEntries(scopes.map(([h, a]) => [h, providerHealth.get(h, a)])) };
+        for (const [k, p] of Object.entries(probes)) if (!p.ok) await notify.error(`${k} not ready`, `${probeFix(k, p)} (${p.detail})`);
+        const errors = results.filter(r => !r.ok).length;
+        health({ lastTick: nowIso(clock), nextTick: new Date(clock.now() + tickMs).toISOString(), probes, entries: results.length, errors });
+      } catch (e) {
+        log.error(`tick failed: ${e.stack || e.message}`);
+        health({ lastTick: nowIso(clock), nextTick: new Date(clock.now() + tickMs).toISOString(), lastError: e.message });
+      }
+      if (once) return;
+      // A referenced timer is what keeps the process alive between ticks; --once returned before scheduling one.
+      timer = setTimeout(loop, tickMs);
+    };
+    log.info(`daemon up as ${ownLogin}, polling every ${config.poll_seconds}s`);
+    await loop();
+    if (once) cleanup();
+  } catch (e) { cleanup(); throw e; }
+}
+
+/** On a Mac, hold off idle sleep for as long as the daemon lives. No-op elsewhere or when caffeinate is missing. */
+function keepAwake() {
+  if (process.platform !== "darwin") return;
+  try { const child = spawn("caffeinate", ["-i", "-w", String(process.pid)], { detached: true, stdio: "ignore" }); child.on("error", () => {}); child.unref(); } catch { /* optional */ }
+}

package/lib/commands/why.mjs

@@ -0,0 +1,143 @@
+// `gallivant why <handle>`: the reason a PR stopped, what was dispatched, what the harness last said, any permission
+// denials, and APort audit lines from the run's window. Reads files; never calls GitHub.
+import { resolveHandle, shortRepo } from "../state.mjs";
+import { adapterFor } from "../harness.mjs";
+import { prdDivergence, divergenceReason, renderDivergence, prdDecision, sourceDivergence } from "../prd.mjs";
+import { contract } from "../fs.mjs";
+import { aportDirFor, auditEntries } from "../aport.mjs";
+import { READY_LABEL_WRITE, COMPLETION_GATE } from "../tick.mjs";
+import { READY_LABEL } from "../gh.mjs";
+import { executionRunner } from "../execution.mjs";
+import { networkRecoveryDetail } from "../network_recovery.mjs";
+import { redact } from "../execution_io.mjs";
+
+export function why(ctx, { handle }) {
+  const { config, state, runnerFor, readPrd = () => null } = ctx;
+  const id = resolveHandle(state.entries(), handle);
+  const e = state.get(id);
+  const runner = executionRunner(ctx, id);
+  const runId = e.last?.run || runner.current()?.id || null;
+  const job = runId ? runner.read(runId) : null;
+  const lines = runId && !runner.outcome ? runner.lines(runId) : [];
+  const outcome = redact(runId && runner.outcome ? runner.outcome(runId) : lines.length ? adapterFor(e.harness).outcome(lines) : null);
+  const out = [];
+  out.push(`${id}  ${e.state}${e.reason ? ` (${e.reason})` : ""}  ${e.harness}  round ${e.iteration}/${config.max_iterations}`);
+  if (e.url) out.push(`PR: ${e.url}`);
+  if (e.network_retry) out.push(`network: ${networkRecoveryDetail(e.network_retry)}; first failure ${e.network_retry.first_at}; automatic recovery is bounded to one hour. Recheck does not restart an agent.`);
+  if (e.execution) out.push(`provider: ${e.execution.providerState}; observed ${e.execution.observedAt ?? "unknown"}; reconciled ${e.execution.reconciledAt ?? "never"}; next ${e.execution.nextAttemptAt ?? "unknown"}; action ${e.execution.recoveryAction ?? "none"}`);
+  if (e.control) out.push(`operator request: ${e.control.action} ${e.control.status}${e.control.message ? ` — ${e.control.message}` : " (waiting for the daemon and any active run)"}`);
+  // The branch this pull request targets. Printed whether or not the PR exists yet, because the case worth catching is
+  // the one before it exists: a branch cut from the wrong base and a session told to open against the wrong base are
+  // both this line being wrong, and both cost a whole run to find out any other way.
+  if (e.base) out.push(`base: ${e.base}  (the branch this PR targets, and the one merged in before each round)`);
+  // A merge the daemon made is a change to this branch's history that nobody typed, so it is reported rather than left in
+  // the log: an operator reading a diff they did not expect needs to know where the extra commit came from.
+  if (e.base_merge) {
+    out.push(e.base_merge.conflict
+      ? `base merge FAILED at ${e.base_merge.at}: origin/${e.base_merge.base} could not be merged into ${e.branch} (${e.base_merge.why}). The merge was aborted, so the checkout is clean.`
+      : `base merge: origin/${e.base_merge.base} was merged into ${e.branch} at ${e.base_merge.at}${e.base_merge.sha ? ` as ${e.base_merge.sha.slice(0, 7)}` : ""}${e.base_merge.onto ? `, onto ${e.base_merge.onto.slice(0, 7)}` : ""}. History was added to, never rewritten: no rebase, no force-push.`);
+  }
+  // A kill is the one stop an operator cannot reconstruct from anything else on this screen: `state` says needs-human,
+  // `reason` says timeout, and the exit is 137, none of which says what the run was doing when SIGKILL landed. The run
+  // this block was written for had finished: four commits made, its tests green, and the session writing a commit
+  // message. So the limit it exceeded is named, and so is where that limit was set, because raising the wrong one of
+  // the global and the repository's own is the obvious next mistake.
+  if (e.timeout) {
+    const where = e.timeout.source === "task" ? "the remaining authorized task runtime allowance" : e.timeout.source === "repo" ? `configured for ${shortRepo(e.repo)}` : "the global run_timeout_minutes";
+    out.push(`killed: ran ${e.timeout.ran_minutes}m and exceeded its ${e.timeout.limit}m timeout (${where}). SIGKILL, so the session had no chance to finish what it was doing; the run log below is the last thing it did.`);
+    if (e.timeout.source === "task") out.push("  Raising repository or global timeouts cannot extend the saved task allowance; inspect the original authorization before requesting further work.");
+    // Work the kill left behind, uncommitted first because it is the fragile half and the half nothing else reports. A
+    // run killed one tool call before `git commit` has an unpushed count of zero and a tree full of work, so a commit
+    // count alone would have said "nothing stranded" about the worst case there is.
+    const { modified = 0, untracked = 0, unpushed = 0 } = e.timeout;
+    if (modified || untracked) {
+      out.push(`  UNCOMMITTED WORK IN THE WORKTREE: ${modified} modified, ${untracked} untracked, held by no commit and in no PR.`,
+        "  A SIGKILL can land between the last edit and `git commit`, and this one did. Nothing on GitHub reflects these files.",
+        `  Read them before anything else touches that directory: \`git -C ${e.worktree || "<worktree>"} status\`.`,
+        "  Do NOT delete or recreate the checkout: `gallivant resume` rebuilds a missing worktree without asking, which would discard this.");
+    }
+    if (unpushed) out.push(`  ${unpushed} commit${unpushed === 1 ? "" : "s"} had been made and not pushed, so that work is in the worktree only. \`gallivant resume\` pushes them rather than redoing them.`);
+    if (!modified && !untracked && !unpushed) out.push("  the worktree was clean and nothing was committed unpushed, so the kill stranded no work.");
+  }
+  if (e.gate_skipped) out.push(`completion gate: NOT RUN (${e.gate_skipped}); no acceptance criterion was evaluated for this PR`);
+
+  // The brief against the operator's own copy, with every difference spelled out. This is the place the whole diff goes:
+  // `status` has one line per row and the tracker has a paragraph, and neither of those can hold five criteria. It is
+  // printed for a stopped entry and for a running one alike, because an operator who edited the brief two minutes ago
+  // will ask `why` before the daemon's next tick has had a chance to stop anything.
+  //
+  // What the gate does about it is stated outright rather than left to be inferred, because the useful thing to know is
+  // not that the files differ, it is that no decision is being made about either of them until a person says which brief
+  // is the brief.
+  // The carried files, before the brief's own divergence, because a document that moved is the cheaper thing to check
+  // and an operator reading this wants both in one place. It is its own block rather than folded into the brief's four
+  // verdicts: a document has two states, the snapshot's bytes or not, since nothing validates its shape.
+  const carried = sourceDivergence({ id, entry: e, readSource: ctx.readSource });
+  if (carried.changed.length || carried.missing.length) {
+    out.push("", `${carried.checked.length} file${carried.checked.length === 1 ? "" : "s"} carried with this brief, and not all of them still match:`);
+    for (const f of carried.changed) out.push(`  changed  ${f}`);
+    for (const f of carried.missing) out.push(`  gone     ${f}`);
+    out.push("  The session was given the snapshot's copy, so it is working from what was carried and not from what is",
+      "  in your tree now. A changed file is a decision about which version is the brief; a file that is gone is a",
+      "  question about whether the work still stands.");
+  }
+
+  const div = divergenceFor(ctx, id, e, readPrd);
+  if (divergenceReason(div)) {
+    out.push("", `the brief has changed since this run started (${divergenceReason(div)}): ${div.why}`);
+    out.push(renderDivergence(div));
+    if (div.verdict === "changed") {
+      out.push("  The completion gate is judging NEITHER brief: the snapshot is one the operator has moved on from, and",
+        "  the edited copy names criteria this session was never given and has not attested. Decide which is the brief:",
+        `    gallivant resume ${e.pr ? `${shortRepo(e.repo)}#${e.pr}` : id} --resnapshot   # the edit is the brief; the session is told what moved`,
+        `    (or put the brief back the way it was, and the next tick carries on)`);
+    }
+    if (div.verdict === "illegal") out.push(`  ${div.path} would be refused by \`gallivant start\` as it stands. Fix it, then \`gallivant ready\` it again.`);
+    if (div.verdict === "gone") out.push("  Restore the file, or `gallivant remove` the entry if the work is no longer wanted.");
+    // A decision id that moved says the operator re-ran `ready`, which is a deliberate re-blessing of the brief rather
+    // than a stray edit. It is reported and never relied on: `ready` leaves it untouched on a brief that was already
+    // ready, and a hand-edit that misses the frontmatter leaves it identical, so it can only ever add confidence to an
+    // answer the contract comparison has already given.
+    const now = div.repo ? prdDecision(div.repo) : null;
+    if (e.prd_decision && now && e.prd_decision !== now) out.push(`  and it was re-readied: aport_decision ${e.prd_decision} became ${now}, so the edit was blessed by \`gallivant ready\`.`);
+    else if (e.prd_decision && now === e.prd_decision) out.push(`  aport_decision is unchanged (${e.prd_decision}), so the edit has not been through \`gallivant ready\`.`);
+  }
+  if (e.retry) out.push(`waiting on ${e.retry.op === COMPLETION_GATE ? "completion verification" : "GitHub"}: ${e.retry.op} has failed ${e.retry.count} tick${e.retry.count === 1 ? "" : "s"} in a row; the entry stops with "stuck" if it keeps failing`);
+  if (e.retry?.op === COMPLETION_GATE) out.push(`  checks green and reviewer clear; completion verification is pending: ${e.retry.error ?? "no decision from the gate"}`);
+  // The one retry whose op is not a step toward a fix round: everything a person waits for has already happened and
+  // only the label that says so will not write, which is worth spelling out where the operator is already reading.
+  if (e.retry?.op === READY_LABEL_WRITE) out.push(`  this PR is otherwise ready: checks green, reviewer clear, receipt accepted. Only the ${READY_LABEL} label will not write.`);
+  // The round comment is the announcement of a round that is already counted, so the operator needs both halves: the
+  // work is on the branch and charged, and the PR does not say so. The second half matters because the count on GitHub
+  // is what a recovery rebuilds from, so an unposted marker is a round a recovery after this would not see.
+  if (e.round_comment) {
+    const recovered = e.iteration - 1;
+    out.push(`  round ${e.iteration} is counted and its push is on the branch; only the comment announcing it is missing, so a recovery from GitHub would count ${recovered} round${recovered === 1 ? "" : "s"} until it posts.`);
+  }
+  if (e.worktree) out.push(`worktree: ${contract(e.worktree)}`);
+  if (e.session) out.push(runner.capabilities?.transport === "remote" ? `session: ${e.session} (owned by ${e.harness}; use its recorded recovery action)` : `session: ${e.session}  (by hand: ${adapterFor(e.harness).attach({ pr: e.pr, session: e.session })} in the worktree)`);
+  if (e.last) out.push(`last event: ${e.last.event}${e.last.at ? ` at ${e.last.at}` : ""}${e.last.exit != null ? `, exit ${e.last.exit}` : ""}${e.last.error ? `, error: ${e.last.error}` : ""}`);
+  if (job) out.push(`run: ${contract(runner.dirOf(job.id))}  ${job.exit === null ? "running" : `exited ${job.exit}`}${job.killed ? " (killed)" : ""}`);
+  if (outcome) {
+    if (outcome.cost != null) out.push(`cost: $${outcome.cost.toFixed(2)}`);
+    // Each denial carries the call that was denied and, where the run's own stream recorded it, the guardrail's reason
+    // on the line beneath. Both come from the same log: the APort audit file printed below names the pattern that fired
+    // and never the path it fired on, so the pairing here is the only place an operator can see a broad pattern catching
+    // a legitimate read. A denial whose reason the stream did not carry prints as the call alone.
+    if (outcome.denials?.length) out.push("permission denials (the call, and the guardrail's reason where the run recorded it):", ...outcome.denials.map(d => `  - ${d}`));
+    if (outcome.lastMessage) out.push("", "harness said:", indent(outcome.lastMessage.trim().slice(-2000)));
+  }
+  if (job) {
+    const audit = auditEntries(aportDirFor(config.harness?.claude?.settings), { fromMs: job.startedAt, toMs: job.endedAt || Date.now(), filter: /allow=false|den|block|warn/i }).slice(-40);
+    if (audit.length) out.push("", "APort audit (run window):", ...audit.map(l => "  " + l));
+  }
+  return out.join("\n");
+}
+
+const indent = s => s.split("\n").map(l => "  " + l).join("\n");
+
+/** Never fatal, for the same reason `status`'s is not: `why` is what an operator runs when something is already wrong. */
+function divergenceFor(ctx, id, entry, readPrd) {
+  try { return prdDivergence({ id, entry, readPrd }); }
+  catch (e) { return { verdict: "unknown", why: e.message, diff: [] }; }
+}