@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/aport.mjs

@@ -0,0 +1,95 @@
+// Reading what APort's installer leaves on disk: the mode file next to a harness settings file, and the audit log.
+// One parser for each, shared by context, doctor and why, so all three agree on quoting and timestamps.
+import { join, dirname } from "node:path";
+import { readdirSync } from "node:fs";
+import { readText } from "./fs.mjs";
+
+/** The APort state directory for a Claude settings file: <dir of settings>/aport. */
+export const aportDirFor = settingsPath => (settingsPath ? join(dirname(settingsPath), "aport") : null);
+
+/** `guardrail-mode.env` as a key/value map. Values may be bare, double- or single-quoted. */
+export function readGuardrailEnv(aportDir) {
+  const out = {};
+  if (!aportDir) return out;
+  for (const line of (readText(join(aportDir, "guardrail-mode.env"), "") || "").split("\n")) {
+    const m = line.match(/^\s*([A-Z0-9_]+)=(.*)$/);
+    if (!m) continue;
+    let v = m[2].trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    out[m[1]] = v;
+  }
+  return out;
+}
+
+/** Summary of the mode file: { mode: "api"|"local"|null, agentId, apiKey, apiUrl, enforcement }. */
+export function guardrailMode(aportDir) {
+  const env = readGuardrailEnv(aportDir);
+  return {
+    mode: env.APORT_GUARDRAIL_MODE?.toLowerCase() || null,
+    agentId: env.APORT_AGENT_ID || null,
+    apiKey: env.APORT_API_KEY || null,
+    apiUrl: env.APORT_API_URL || null,
+    // Match hook-runtime.sh; the current name takes precedence over legacy aliases.
+    enforcement: env.APORT_ENFORCEMENT_MODE || env.APORT_ENFORCEMENT || env.APORT_GUARDRAIL_ENFORCEMENT || "enforce",
+  };
+}
+
+/**
+ * Audit-log lines whose timestamp falls in [fromMs, toMs]. The hook stamps `[2026-09-24 03:48:31]` in UTC without a
+ * zone marker; ISO stamps are accepted too. A minute of slack covers clock rounding.
+ */
+export function auditEntries(aportDir, { fromMs, toMs = Date.now(), filter = null } = {}) {
+  if (!aportDir) return [];
+  let files = [];
+  try { files = readdirSync(aportDir).filter(f => /audit/i.test(f)); } catch { return []; }
+  const out = [];
+  for (const f of files) {
+    for (const line of (readText(join(aportDir, f), "") || "").split("\n")) {
+      const t = auditStamp(line);
+      if (t === null || t < fromMs - 60_000 || t > toMs + 60_000) continue;
+      if (filter && !filter.test(line)) continue;
+      out.push(line.slice(0, 220));
+    }
+  }
+  return out;
+}
+
+/**
+ * How the guardrail's own decisions came out, read from `session-decisions.jsonl`.
+ *
+ * The distinction this exists to draw: `oap.blocked_pattern` is the hook deciding NO, and `oap.evaluation_error` is
+ * the hook failing to decide at all and denying because it fails closed. A run cannot tell those apart, and neither
+ * could an operator: both arrive at the session as "APort denied this tool call", so a week of rate limits from
+ * aport.io reads as a policy that is too tight, and the operator loosens a policy that was never the problem.
+ *
+ * Measured on one machine's history: of 60 denials, 15 were evaluation errors. Thirteen were HTTP 429 ("Too many
+ * failed attempts. Account temporarily blocked") which denied ordinary work for about three minutes straight, and the
+ * rest were the hook's own request failing schema validation on fields it builds itself.
+ *
+ * Counts only, never the message, because a reason can carry a command line and this is printed by `doctor`.
+ */
+export function decisionCounts(aportDir, { file = "session-decisions.jsonl" } = {}) {
+  const out = { total: 0, allowed: 0, denied: 0, codes: {}, evaluationErrors: 0 };
+  if (!aportDir) return out;
+  for (const line of (readText(join(aportDir, file), "") || "").split("\n")) {
+    if (!line.trim()) continue;
+    let d;
+    try { d = JSON.parse(line).decision; } catch { continue; }
+    if (!d) continue;
+    out.total++;
+    if (d.allow) out.allowed++; else out.denied++;
+    for (const r of d.reasons || []) {
+      if (!r?.code) continue;
+      out.codes[r.code] = (out.codes[r.code] || 0) + 1;
+      if (r.code === "oap.evaluation_error" && !d.allow) out.evaluationErrors++;
+    }
+  }
+  return out;
+}
+
+const auditStamp = line => {
+  const m = line.match(/^\[?(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2}(?:\.\d+)?)Z?\]?/);
+  if (!m) return null;
+  const t = Date.parse(`${m[1]}T${m[2]}Z`);
+  return Number.isFinite(t) ? t : null;
+};

package/lib/attribution.mjs

@@ -0,0 +1,95 @@
+// Harness attribution in a commit message, and the `commit-msg` hook that refuses it.
+//
+// Commits use the operator's configured identity. Their message must also describe the change without runner
+// branding or model attribution. This rule applies to all adapters through one installed Git hook.
+//
+// This is a HOOK and not a line in the prompt, and the choice is the whole design. A prompt is a request a session can
+// forget. A hook fires on whatever process runs
+// `git commit`, so one mechanism covers all five adapters and the sixth nobody has written yet, with no per-harness
+// code and nothing to keep in step. It fails the commit rather than editing the message, because silently rewriting what
+// a session wrote would leave it believing it committed something it did not.
+//
+// `.git/hooks` rather than a directory in the checkout. A relative `core.hooksPath` would also work and would keep
+// `runEnv` free of absolute paths, but it puts a directory INSIDE the working tree, where it shows up as untracked in
+// `git status`, in the `git diff --check` the briefs run, and in the uncommitted-work count a timeout kill now reports.
+// A hook that makes a clean tree look dirty would be traded away by the first session that wanted a clean `git status`.
+// `.git/hooks` is git's own default path, needs no config at all, is already outside the working tree, and dies with
+// the clone. Nothing is added to `runEnv`, which keeps its no-absolute-paths property intact.
+
+/**
+ * The trailers that are refused, matched at the start of a line and case-insensitively.
+ *
+ * Deliberately narrow. It matches a `Co-Authored-By:` trailer naming a harness or its vendor, and the two forms Claude
+ * Code appends to bodies it writes. It does NOT match a bare mention of a harness anywhere in a message, and that is a
+ * requirement rather than an oversight: this repository has `lib/harness.mjs`, five adapters and a doctor check, so
+ * "fix: claude adapter drops the session id" is a commit that must go through. A matcher that blocked it would be worse
+ * than the trailer it was trying to stop, because the way around it is to describe the change dishonestly.
+ */
+const VENDORS = "claude|anthropic|codex|openai|gemini|google|opencode|goose";
+export const ATTRIBUTION_PATTERNS = [
+  // Public output uses neutral wording even when the underlying checkout/session keeps a legacy name.
+  /^.*gallivant.*$/im,
+  // A co-author trailer naming any of them, anywhere on the line: the vendor may be in the name, the email or both.
+  new RegExp(String.raw`^\s*co-authored-by:.*(?:${VENDORS}).*$`, "im"),
+  // The footer Claude Code adds to messages and PR bodies, in both the forms it writes.
+  new RegExp(String.raw`^\s*(?:🤖\s*)?generated with\b.*(?:${VENDORS}).*$`, "im"),
+  new RegExp(String.raw`^\s*🤖\s*generated with.*$`, "im"),
+];
+
+/**
+ * The offending line of a message, or null when there is none. The LINE and not just a boolean, because the whole value
+ * of failing early is an error a session can act on: "rejected" with no reason gets the identical message retried.
+ *
+ * Comment lines are ignored. `git commit` passes the message file with its own `#` commentary still in it, and the
+ * template shown on a conflict lists the co-authors of the commits being merged.
+ */
+export function attributionIn(message) {
+  const body = String(message ?? "")
+    .split("\n")
+    .filter(l => !l.trimStart().startsWith("#"))
+    .join("\n");
+  for (const re of ATTRIBUTION_PATTERNS) {
+    const m = body.match(re);
+    if (m) return m[0].trim();
+  }
+  return null;
+}
+
+/** The message the hook prints on a refusal. One place, so the test and the script cannot drift. */
+export const attributionError = line => [
+  /gallivant/i.test(line)
+    ? "This commit message names the task runner, which is not permitted in public output."
+    : "This commit message credits an AI harness, which is not permitted on this project.",
+  `  offending line: ${line}`,
+  "  Remove that line from the message and commit again. Everything else about the commit is fine:",
+  "  Preserve accurate technical details and describe the change without runner branding or model attribution.",
+  "  The commit is authored by the operator, and the harness that wrote it is recorded in the run log, not in the history.",
+].join("\n");
+
+/**
+ * The `commit-msg` hook, as the text of the file. Self-contained node with no imports, because it runs as its own
+ * process inside a sandboxed checkout that cannot read this repository: a `require` of anything here would fail at
+ * commit time, on the operator's machine, for a reason nothing would explain. So the matcher is inlined, and
+ * `test/attribution.test.mjs` asserts the inlined copy agrees with `attributionIn` on every case rather than trusting
+ * that they were kept in step by hand.
+ *
+ * Exits 1 on a match, which is what makes `git commit` create no commit object at all.
+ */
+export const COMMIT_MSG_HOOK = `#!/usr/bin/env node
+// Written by Gallivant (lib/attribution.mjs). Refuses a commit message that credits an AI harness.
+// Self-contained on purpose: this runs inside a sandboxed checkout that cannot read Gallivant's own source.
+// Dynamic import works whether the checkout's package.json declares module or commonjs.
+import("node:fs").then(({ readFileSync }) => {
+const ATTRIBUTION_PATTERNS = ${JSON.stringify(ATTRIBUTION_PATTERNS.map(re => [re.source, re.flags]))}.map(([source, flags]) => new RegExp(source, flags));
+${attributionIn.toString()}
+const attributionError = ${attributionError.toString()};
+let text = "";
+try { text = readFileSync(process.argv[2], "utf8"); } catch { process.exit(0); }
+const line = attributionIn(text);
+if (line) {
+  process.stderr.write(attributionError(line) + "\\n");
+  process.exit(1);
+}
+process.exit(0);
+});
+`;

package/lib/block.mjs

@@ -0,0 +1,89 @@
+// Recovery identity in the PR body. The neutral record is versioned canonical JSON, transported as base64url.
+// This is encoding, not secrecy or authorization: all decoded fields retain the legacy strict validation.
+import { HARNESSES } from "./config.mjs";
+import { isSessionFor } from "./harness.mjs";
+import { BLOCK_OPEN, BLOCK_OPENS, BRANCH_PREFIXES } from "./public-format.mjs";
+import { normalizeReceipt } from "./deliverable.mjs";
+
+const CLOSE = "-->";
+const FIELDS = ["prd", "harness", "session", "branch"];
+const RULES = {
+  prd: v => /^[a-z0-9][a-z0-9_./-]*\.md$/.test(v) && !v.split("/").includes("..") && !v.includes("//"),
+  harness: v => HARNESSES.includes(v),
+  session: (v, fields) => v === null || isSessionFor(fields.harness, v),
+  branch: v => BRANCH_PREFIXES.some(prefix => v.startsWith(prefix) && /^[a-z0-9][a-z0-9-]*$/.test(v.slice(prefix.length))),
+};
+
+// Require the opening marker to occupy a complete line. Old round/nudge/reset comments share the old prefix but
+// are not identities, and must never be mistaken for a recovery block or removed when a body is normalized.
+const OPEN_RE = new RegExp("^(?:" + BLOCK_OPENS.join("|") + ")[ \\t]*(?=\\r?$)", "gm");
+function blocks(body) {
+  return [...body.matchAll(OPEN_RE)].map(match => ({ start: match.index, open: match[0].trimEnd(), end: body.indexOf(CLOSE, match.index + match[0].length) }));
+}
+
+export function renderBlock({ prd, harness, session, branch }) {
+  const data = Buffer.from(JSON.stringify({ version: 1, prd, harness, session: session ?? null, branch }), "utf8").toString("base64url");
+  return `${BLOCK_OPEN}\n${data}\n${CLOSE}`;
+}
+
+/** Parsed and validated fields, or null with a reason when anything is off. */
+export function parseBlock(body) {
+  const text = String(body || "");
+  const found = blocks(text);
+  if (!found.length) return { block: null, reason: "no block" };
+  if (found.length !== 1) return { block: null, reason: "multiple recovery blocks" };
+  const { start, open, end } = found[0];
+  if (end < 0) return { block: null, reason: "unterminated block" };
+  const payload = text.slice(start + open.length, end).trim();
+  let fields;
+  if (open === BLOCK_OPEN) {
+    if (payload.length > 8192 || !/^[A-Za-z0-9_-]+$/.test(payload)) return { block: null, reason: "invalid recovery record encoding" };
+    try {
+      const bytes = Buffer.from(payload, "base64url");
+      if (bytes.toString("base64url") !== payload) throw new Error("noncanonical encoding");
+      const value = JSON.parse(bytes.toString("utf8"));
+      if (!value || typeof value !== "object" || Array.isArray(value) || value.version !== 1
+          || Object.keys(value).some(k => !["version", ...FIELDS].includes(k))) throw new Error("unknown recovery record schema");
+      fields = Object.fromEntries(FIELDS.filter(k => Object.hasOwn(value, k)).map(k => [k, value[k]]));
+    } catch { return { block: null, reason: "invalid recovery record" }; }
+  } else {
+    fields = {};
+    for (const line of payload.split("\n")) {
+      const match = line.trim().match(/^(prd|harness|session|branch):\s*(\S+)$/);
+      if (!match) continue;
+      if (Object.hasOwn(fields, match[1])) return { block: null, reason: `duplicate ${match[1]}` };
+      fields[match[1]] = match[2];
+    }
+    if (fields.session === "none") fields.session = null;
+  }
+  for (const key of FIELDS) {
+    const value = fields[key];
+    if (value === undefined) return { block: null, reason: `missing ${key}` };
+    if ((key === "session" && value === null) || (typeof value === "string" && RULES[key](value, fields))) continue;
+    return { block: null, reason: `invalid ${key}: ${String(value).slice(0, 40)}` };
+  }
+  return { block: fields, reason: null };
+}
+
+/** Replace one known block (valid or not), or append one. Ambiguous identities are never silently discarded. */
+export function upsertBlock(body, block) {
+  const text = String(body || "");
+  const found = blocks(text);
+  if (found.length > 1) throw new Error("multiple recovery blocks; keep exactly one identity");
+  if (found.length) {
+    const { start, end } = found[0];
+    if (end < 0) throw new Error("unterminated recovery block; repair the body before updating identity");
+    return text.slice(0, start) + renderBlock(block) + text.slice(end + CLOSE.length);
+  }
+  return `${text.replace(/\s+$/, "")}\n\n${renderBlock(block)}\n`;
+}
+
+/** Migrate machine-owned formatting only. Never redact a title, prose, evidence, source path or URL. */
+export function normalizePublicBody(body, { identity = null, taskId = null } = {}) {
+  let text = normalizeReceipt(body, taskId);
+  const parsed = parseBlock(text);
+  if (identity) text = upsertBlock(text, identity);
+  else if (parsed.block) text = upsertBlock(text, parsed.block);
+  else if (parsed.reason !== "no block") throw new Error(parsed.reason);
+  return text;
+}

package/lib/capabilities.mjs

@@ -0,0 +1,3 @@
+// Public stable export of the existing registry; import does not probe accounts.
+export { capabilitiesFor, executionCapabilities, preparationCapability } from "./harness.mjs";
+export { NODE_RUNTIME_REQUIREMENTS } from "./runtime_node.mjs";

package/lib/chains.mjs

@@ -0,0 +1,222 @@
+// Linear, operator-approved plans. The normal start/tick machinery still owns every individual run.
+import { randomUUID } from "node:crypto";
+import { requestFor } from "./sources/index.mjs";
+import { resolveBase } from "./config.mjs";
+import { entryId } from "./state.mjs";
+import { prdIdFromBranch } from "./git.mjs";
+import { repoFromUrl } from "./gh.mjs";
+import { start } from "./commands/start.mjs";
+import { validateStartRequest, captureStartInput, contentDigest, checkBaseFiles } from "./start_contract.mjs";
+
+const MAX_FAILURES = 5;
+const flights = new Map();
+const stamp = () => new Date().toISOString();
+const validName = name => {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name || "") || name.length > 80) throw new Error("chain name must be 1–80 lowercase letters, digits and single dashes");
+};
+const uncertain = id => `Unresolved start for ${id}. Inspect gallivant why, the runner logs and worktree before recovery; --retry never clears a start claim or launches a second process. Cancel this chain if a new plan is needed.`;
+
+async function planStep(ctx, path, askedBase) {
+  const request = await requestFor(path, ctx);
+  validateStartRequest(request, ctx.config, path);
+  const { base } = resolveBase({ config: ctx.config, repo: request.repo, defaultBranch: request.defaultBranch, asked: askedBase });
+  if (!base) throw new Error(`no base branch for ${request.repo}`);
+  const input = captureStartInput(request, base);
+  return { request, input, step: {
+    id: entryId(request.repo, request.id), path: request.path, checkout: request.checkout, relPath: request.relPath,
+    harness: request.harness, digest: input.digest, baseFiles: {}, dispatch: null, entry: null, merged: null,
+  }, repo: request.repo.toLowerCase(), base };
+}
+
+async function approveBaseFiles(ctx, plans) {
+  const { repo, base } = plans[0];
+  if (!await ctx.gh.branchExists(repo, base)) throw new Error(`base ${repo}:${base} is missing or GitHub is unavailable`);
+  const sha = await ctx.gh.refSha(repo, base);
+  if (!/^[a-f0-9]{40,64}$/.test(sha || "")) throw new Error(`GitHub did not return a base commit for ${repo}:${base}`);
+  const files = new Map();
+  for (const plan of plans) {
+    for (const [path] of plan.input.files) {
+      if (!files.has(path)) files.set(path, contentDigest(await ctx.gh.fileAtStrict(repo, path, sha)));
+      plan.step.baseFiles[path] = files.get(path);
+    }
+  }
+}
+
+export async function queueChain(ctx, { name, paths, base = null }) {
+  validName(name);
+  if (!Array.isArray(paths) || paths.length < 2) throw new Error("a chain needs at least two ready PRD paths in execution order");
+  const plans = [];
+  for (const path of paths) plans.push(await planStep(ctx, path, base));
+  const first = plans[0];
+  if (plans.some(p => p.repo !== first.repo || p.base !== first.base || p.step.checkout !== first.step.checkout)) throw new Error("a chain must use one repository checkout and one base branch");
+  if (new Set(plans.map(p => p.step.id)).size !== plans.length) throw new Error("a chain cannot contain duplicate PRDs");
+  await approveBaseFiles(ctx, plans);
+  return ctx.state.createChain({ name, repo: first.repo, base: first.base, status: "active", index: 0,
+    steps: plans.map(p => p.step), reason: null, failures: 0, created_at: stamp(), updated_at: stamp() });
+}
+
+export function cancelChain(ctx, name) {
+  return ctx.state.updateChain(name, c => {
+    if (c.status === "done") throw new Error(`chain ${name} is already done`);
+    return { status: "cancelled", reason: "Cancelled by operator; existing runs are preserved", updated_at: stamp() };
+  });
+}
+
+export async function retryChain(ctx, { name, resnapshot = false }) {
+  const c = ctx.state.getChain(name);
+  if (!c) throw new Error(`no chain ${name}`);
+  if (c.status !== "stopped") throw new Error(`chain ${name} is ${c.status}; --retry is for a stopped chain`);
+  for (const step of c.steps) {
+    if (ctx.state.startClaim(step.id) || (step.dispatch && !ctx.state.get(step.id))) throw new Error(uncertain(step.id));
+  }
+  const steps = structuredClone(c.steps);
+  if (resnapshot) {
+    const plans = [];
+    for (let i = c.index; i < steps.length; i++) {
+      if (steps[i].entry || steps[i].dispatch) continue;
+      const p = await planStep(ctx, steps[i].path, c.base);
+      if (p.repo !== c.repo || p.step.id !== steps[i].id || p.step.checkout !== steps[i].checkout) throw new Error("resnapshot cannot change a chain's repository or task identity");
+      plans.push(p);
+      steps[i] = p.step;
+    }
+    if (plans.length) await approveBaseFiles(ctx, plans);
+  }
+  return ctx.state.updateChain(name, current => {
+    if (JSON.stringify(current) !== JSON.stringify(c)) throw new Error("chain changed while retrying; inspect it again");
+    return { steps, status: "active", failures: 0, reason: null, updated_at: stamp() };
+  });
+}
+
+// Never resurrect cancellation or apply an old tick's result to a different milestone.
+function saveActive(ctx, c, patch) {
+  return ctx.state.updateChain(c.name, current => current.status === "active" && current.index === c.index
+    ? { ...patch, updated_at: stamp() } : {});
+}
+
+async function stop(ctx, c, reason) {
+  const saved = saveActive(ctx, c, { status: "stopped", reason });
+  if (saved.status !== "stopped") return;
+  ctx.log.warn(`chain ${c.name}: ${reason}`);
+  await ctx.notify?.error?.(`chain ${c.name} stopped`, `${reason}\nInspect: gallivant chain ${c.name}`).catch(() => {});
+}
+
+function matchesEntry(c, step, entry) {
+  // Creation writes the current prefix; persisted runs keep their original branch. Decode through the shared
+  // current/legacy convention and require the exact approved task slug, without weakening the other identity pins.
+  return entry && entry.chain?.name === c.name && entry.chain?.index === c.index && entry.chain?.dispatch === step.dispatch
+    && entry.repo === c.repo && entry.base === c.base && prdIdFromBranch(entry.branch) === step.id.split("/").pop()
+    && entry.checkout === step.checkout && entry.prd === step.relPath
+    && entry.start_token && (!step.entry || step.entry.token === entry.start_token);
+}
+
+async function tickChain(ctx, c) {
+  let step = c.steps[c.index];
+  if (step.dispatch) {
+    const entry = ctx.state.get(step.id);
+    if (!matchesEntry(c, step, entry)) { await stop(ctx, c, entry ? `${step.id}: registered run identity changed; inspect before continuing` : uncertain(step.id)); return; }
+    if (step.entry?.pr && entry.pr !== step.entry.pr) { await stop(ctx, c, `${step.id}: predecessor PR identity changed`); return; }
+    // Capture the token immediately, and the PR identity once the normal tick discovers it.
+    if (!step.entry || (!step.entry.pr && entry.pr)) {
+      const steps = structuredClone(c.steps);
+      steps[c.index].entry = { token: entry.start_token, pr: entry.pr || null };
+      c = saveActive(ctx, c, { steps }); step = c.steps[c.index];
+      if (c.status !== "active") return;
+    }
+    // The normal run remains the recovery surface. Never have two milestone agents mutating dependent work.
+    if (!entry.pr || (entry.last?.run && entry.last.exit == null) || ctx.runnerFor(step.id).current()?.running) return;
+    const pr = await ctx.gh.prView(c.repo, entry.pr);
+    const identity = repoFromUrl(pr.url);
+    if (identity?.repo !== c.repo || identity.number !== entry.pr || pr.number !== entry.pr
+      || pr.headRefName !== entry.branch || pr.isCrossRepository !== false || pr.baseRefName !== c.base) {
+      await stop(ctx, c, `${step.id}: PR identity or intended base changed`); return;
+    }
+    if (pr.state === "CLOSED") { await stop(ctx, c, `${step.id}: PR #${entry.pr} was closed without merging; reopen and register the PR before retrying, or cancel this chain`); return; }
+    if (pr.state !== "MERGED") { if (c.failures) saveActive(ctx, c, { failures: 0, reason: null }); return; }
+    const sha = pr.mergeCommit?.oid;
+    if (!/^[a-f0-9]{40,64}$/.test(sha || "") || !pr.mergedAt || !await ctx.gh.containsCommit(c.repo, c.base, sha)) {
+      await stop(ctx, c, `${step.id}: merge commit is missing from the intended base ${c.base}`); return;
+    }
+    const steps = structuredClone(c.steps);
+    steps[c.index].merged = { pr: entry.pr, sha, at: pr.mergedAt };
+    const index = c.index + 1;
+    saveActive(ctx, c, { steps, index, status: index === steps.length ? "done" : "active", reason: null, failures: 0 });
+    return; // At most one transition per chain per tick; another tick starts the successor.
+  }
+
+  if (ctx.state.get(step.id) || ctx.state.startClaim(step.id)) { await stop(ctx, c, uncertain(step.id)); return; }
+  const p = await planStep(ctx, step.path, c.base);
+  if (p.input.digest !== step.digest) { await stop(ctx, c, `${step.id}: queued PRD or sources changed; review them, then gallivant chain ${c.name} --retry --resnapshot`); return; }
+  const after = c.steps.slice(0, c.index).map(s => s.merged?.sha);
+  for (const sha of after) {
+    if (!sha || !await ctx.gh.containsCommit(c.repo, c.base, sha)) { await stop(ctx, c, `predecessor merge is no longer in ${c.base}; inspect the base history`); return; }
+  }
+  // Fail before cloning for a normal source collision; start rechecks against the actual clone to close the race.
+  const baseSha = await ctx.gh.refSha(c.repo, c.base);
+  await checkBaseFiles(p.input, step.baseFiles, path => ctx.gh.fileAtStrict(c.repo, path, baseSha));
+  const dispatch = randomUUID();
+  c = ctx.state.updateChain(c.name, current => {
+    if (current.status !== "active" || current.index !== c.index || current.steps[current.index].dispatch) return {};
+    const steps = structuredClone(current.steps); steps[current.index].dispatch = dispatch;
+    return { steps, updated_at: stamp() };
+  });
+  if (c.status !== "active" || c.steps[c.index].dispatch !== dispatch) return;
+  step = c.steps[c.index];
+  try {
+    await start(ctx, { path: step.path, base: c.base, chain: { name: c.name, index: c.index, dispatch, digest: step.digest, baseFiles: step.baseFiles, after } });
+  } catch (error) {
+    const entry = ctx.state.get(step.id);
+    // A post-registration failure (for example config persistence) still owns a valid run. Reconcile next tick.
+    if (matchesEntry(c, step, entry)) { ctx.log.warn(`chain ${c.name}: run registered; ${error.message}`); return; }
+    if (!ctx.state.startClaim(step.id)) {
+      const steps = structuredClone(c.steps); steps[c.index].dispatch = null;
+      c = saveActive(ctx, c, { steps });
+    }
+    await stop(ctx, c, `${step.id}: ${error.message}${ctx.state.startClaim(step.id) ? `\n${uncertain(step.id)}` : ""}`);
+  }
+}
+
+export async function tickChains(ctx) {
+  // up owns the cross-process daemon lock; this also serializes overlapping callers in tests/embedders.
+  const key = ctx.state.file;
+  if (flights.has(key)) return flights.get(key);
+  const work = (async () => {
+    const results = [];
+    for (const [, chain] of ctx.state.chains()) {
+      if (chain.status !== "active") continue;
+      try { await tickChain(ctx, chain); results.push({ chain: chain.name, ok: true }); }
+      catch (error) {
+        const current = ctx.state.getChain(chain.name);
+        const failures = (current.failures || 0) + 1;
+        if (error.code === "CHAIN_INPUT_CHANGED") await stop(ctx, current, error.message);
+        else if (failures >= MAX_FAILURES) await stop(ctx, current, `${error.message} (${failures} failed checks; retry after fixing)`);
+        else saveActive(ctx, current, { failures, reason: `${error.message} (retrying ${failures}/${MAX_FAILURES})` });
+        ctx.log.warn(`chain ${chain.name}: ${error.message}`);
+        results.push({ chain: chain.name, ok: false, error: error.message });
+      }
+    }
+    return results;
+  })();
+  flights.set(key, work);
+  try { return await work; } finally { flights.delete(key); }
+}
+
+export function chainRows(ctx) {
+  return ctx.state.chains().map(([name, c]) => {
+    const step = c.steps[c.index], entry = step ? ctx.state.get(step.id) : null;
+    return { name, status: c.status, repo: c.repo, base: c.base, completed: c.index, total: c.steps.length,
+      current: step?.id || null, reason: c.reason || (c.status === "done" ? "all milestones merged" : entry ? (entry.reason || (entry.pr ? `waiting for PR #${entry.pr} to merge` : "waiting for the current run")) : "queued"),
+      url: entry?.url || null };
+  });
+}
+
+export function renderChains(ctx, name = null) {
+  const rows = chainRows(ctx).filter(c => !name || c.name === name);
+  if (name && !rows.length) throw new Error(`no chain ${name}`);
+  const lines = rows.map(c => `${c.name}: ${c.status} — ${c.completed}/${c.total} merged -> ${c.repo}:${c.base}${["done", "cancelled"].includes(c.status) ? "" : ` — ${c.reason}`}`);
+  if (name) {
+    const c = ctx.state.getChain(name);
+    c.steps.forEach((s, i) => lines.push(`  ${i + 1}. ${s.id} — ${s.merged ? `merged #${s.merged.pr}` : s.dispatch ? "started" : "queued"}\n     ${s.path}`));
+    if (c.status === "stopped") lines.push(`Inspect the reason, then: gallivant chain ${name} --retry`);
+  }
+  return lines.join("\n") || "No chains queued.";
+}