@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/state.mjs

@@ -0,0 +1,246 @@
+// The registry: one entry per PRD or registered PR, keyed by `<owner>/<repo>/<prd id>`.
+//
+// The file is a cache with cursors. Identity (which PR, which session) can be rebuilt from GitHub; counters and
+// cursors can be rebuilt by counting the daemon's own comments. Every write is atomic and every read-modify-write
+// holds a lock file, so the CLI and the daemon cannot lose each other's updates.
+import { join, basename } from "node:path";
+import { openSync, closeSync, unlinkSync, statSync } from "node:fs";
+import { readJson, writeJsonAtomic, gallivantHome } from "./fs.mjs";
+import { later } from "./time.mjs";
+import { randomUUID } from "node:crypto";
+
+export const STATES = Object.freeze({
+  running: "running",           // start run in progress, no PR yet
+  prOpen: "pr-open",            // watched
+  ready: "ready-for-human",     // watched, waiting for a person to merge
+  needsHuman: "needs-human",    // stopped with a reason
+  done: "done",                 // merged or closed
+});
+
+export const statePath = (home = gallivantHome()) => join(home, "state.json");
+
+/**
+ * The repository name without its owner, for a handle a person reads: `acme/widget` is `widget`. Anything that is
+ * not `owner/name` degrades to what it was given rather than to `undefined`, and a missing repo to the empty string
+ * rather than a throw. Both used to reach the operator: the ntfy title said `undefined#3` and told them to run
+ * `gallivant why undefined#3`, and the throw happened inside `needsHuman` after the labels were written but before
+ * the notification, where the tick's per-entry catch swallowed it and a stopped PR notified nobody at all.
+ */
+export const shortRepo = nameWithOwner => { const s = String(nameWithOwner ?? ""); return s.split("/")[1] || s; };
+
+/** `<repo>#<pr>` when there is a PR, else the registry id. */
+export const handleFor = (id, entry) => (entry.pr ? `${shortRepo(entry.repo)}#${entry.pr}` : id);
+
+/** Registry id: a pure function of the repository and the PRD, so every path keyed by it agrees. */
+export const entryId = (nameWithOwner, prdId) => `${nameWithOwner.toLowerCase()}/${prdId}`;
+
+/** The PRD id is the last segment of the registry id. */
+export const prdIdOf = id => id.split("/").pop();
+
+/** A filesystem-safe form of the id for run and snapshot folders. */
+export const idSlug = id => id.replaceAll("/", "__");
+
+const LOCK_WAIT_MS = 5_000;
+const LOCK_STALE_MS = 30_000;
+
+/** Hold an exclusive lock file for the duration of `fn`. Waits up to five seconds; a lock older than thirty is stale. */
+function withLock(file, fn) {
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      const fd = openSync(lock, "wx");
+      try { return fn(); } finally { closeSync(fd); try { unlinkSync(lock); } catch { /* gone */ } }
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      try { if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) { unlinkSync(lock); continue; } } catch { continue; }
+      if (Date.now() > deadline) throw new Error(`state is locked by another gallivant process (${lock})`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+    }
+  }
+}
+
+export function makeState(home = gallivantHome()) {
+  const file = statePath(home);
+  const load = () => {
+    const s = readJson(file, { version: 1, entries: {} });
+    if (s.version !== 1) throw Object.assign(new Error(`unsupported registry version ${s.version}; stop the coordinator, back up ${home}, and install a compatible package or restore its matching backup; do not redispatch`), { code: "STATE_VERSION" });
+    for (const e of Object.values(s.entries)) if (e.execution && e.execution.version !== 1) throw Object.assign(new Error("unsupported execution state version; restore a compatible package/backup before restarting"), { code: "EXECUTION_VERSION" });
+    return s;
+  };
+  const save = s => writeJsonAtomic(file, s, 0o600);
+  const locked = fn => withLock(file, fn);
+  const owner = (s, id) => Object.values(s.chains || {}).find(c => !["done", "cancelled"].includes(c.status) && c.steps.some(step => step.id === id));
+  const assertCanPut = (s, id) => {
+    if (s.starts?.[id] || (!s.entries[id] && owner(s, id))) throw new Error(`${id} is reserved for a start or chain`);
+  };
+  return {
+    file,
+    load,
+    entries: () => Object.entries(load().entries),
+    get: id => load().entries[id] || null,
+    /** The entry that watches this PR, if any. */
+    findByPr: (repo, pr) => Object.entries(load().entries).find(([, e]) => e.repo === repo.toLowerCase() && e.pr === pr) || null,
+    put: (id, entry) => locked(() => {
+      const s = load();
+      assertCanPut(s, id);
+      s.entries[id] = entry; save(s); return entry;
+    }),
+    update: (id, patch) => locked(() => { const s = load(); const cur = s.entries[id]; if (!cur) throw new Error(`no entry ${id}`); s.entries[id] = { ...cur, ...(typeof patch === "function" ? patch(cur) : patch) }; save(s); return s.entries[id]; }),
+    remove: id => locked(() => {
+      const s = load();
+      const chain = owner(s, id);
+      if (chain) throw new Error(`${id} belongs to chain ${chain.name}; cancel the chain before forgetting its run`);
+      delete s.entries[id]; save(s);
+    }),
+    chains: () => Object.entries(load().chains || {}),
+    getChain: name => load().chains?.[name] || null,
+    createChain: chain => locked(() => {
+      const s = load();
+      if (s.chains?.[chain.name]) throw new Error(`chain ${chain.name} already exists`);
+      for (const step of chain.steps) {
+        if (s.entries[step.id] || s.starts?.[step.id] || owner(s, step.id)) throw new Error(`${step.id} already exists, is starting, or belongs to another chain`);
+      }
+      s.chains = { ...s.chains, [chain.name]: chain }; save(s); return chain;
+    }),
+    updateChain: (name, patch) => locked(() => {
+      const s = load(), cur = s.chains?.[name];
+      if (!cur) throw new Error(`no chain ${name}`);
+      s.chains[name] = { ...cur, ...(typeof patch === "function" ? patch(cur) : patch) };
+      save(s); return s.chains[name];
+    }),
+    startClaim: id => load().starts?.[id] || null,
+    assertCanRegister: id => assertCanPut(load(), id),
+    // This lock covers CLI starts and chain dispatches. Never hold it across a probe, clone or spawn.
+    claimStart: (id, chain = null, task = null) => locked(() => {
+      const s = load(), reserved = owner(s, id);
+      if (s.entries[id] || s.starts?.[id]) throw new Error(`${id} already exists or has an unresolved start; inspect it before retrying`);
+      if (chain) {
+        const c = s.chains?.[chain.name], step = c?.steps[chain.index];
+        if (c?.status !== "active" || c.index !== chain.index || step?.id !== id || step.dispatch !== chain.dispatch) throw new Error(`chain ${chain.name} no longer authorizes this start`);
+      } else if (reserved) throw new Error(`${id} is reserved by chain ${reserved.name}`);
+      const claim = { token: randomUUID(), chain: chain?.name || null, ...(task ? { task } : {}), at: new Date().toISOString() };
+      s.starts = { ...s.starts, [id]: claim }; save(s); return claim;
+    }),
+    releaseStart: (id, token) => locked(() => {
+      const s = load();
+      if (s.starts?.[id]?.token === token) { delete s.starts[id]; save(s); }
+    }),
+    markStartClone: (id, token, clone) => locked(() => {
+      const s = load();
+      if (s.starts?.[id]?.token !== token || s.entries[id]) throw new Error(`${id}: start claim changed before clone`);
+      s.starts[id] = { ...s.starts[id], clone: { ...clone, at: new Date().toISOString() } };
+      save(s);
+    }),
+    validateStart: (id, token, chain = null) => locked(() => {
+      const s = load(), c = chain && s.chains?.[chain.name];
+      if (s.starts?.[id]?.token !== token || s.entries[id]) throw new Error(`${id}: start claim changed before spawn`);
+      if (chain && (c?.status !== "active" || c.index !== chain.index || c.steps[chain.index]?.dispatch !== chain.dispatch)) throw new Error(`chain ${chain.name} no longer authorizes this start`);
+    }),
+    putStarted: (id, entry, token) => locked(() => {
+      const s = load();
+      if (s.starts?.[id]?.token !== token || s.entries[id]) throw new Error(`${id}: start claim changed; inspect the spawned run`);
+      s.entries[id] = { ...entry, start_token: token }; delete s.starts[id]; save(s); return s.entries[id];
+    }),
+  };
+}
+
+/**
+ * Resolve what the operator typed to a registry id. Accepts the id itself, a PRD path, or `repo#pr` where repo is
+ * the short name or owner/name. Bare PR numbers are refused because they are ambiguous across repos.
+ */
+export function resolveHandle(entries, handle) {
+  if (!handle) throw new Error("handle required: <owner>/<repo>/<prd id>, <prd path>, or <repo>#<pr>");
+  if (/^\d+$/.test(handle)) throw new Error(`"${handle}" is ambiguous across repos; use <repo>#${handle}`);
+  const direct = entries.find(([id]) => id === handle.toLowerCase() || id === handle);
+  if (direct) return direct[0];
+  const m = handle.match(/^([\w.-]+(?:\/[\w.-]+)?)#(\d+)$/);
+  if (m) {
+    const [, repo, n] = m;
+    const key = repo.toLowerCase();
+    const hit = entries.find(([, e]) => e.pr === Number(n) && (e.repo === key || shortRepo(e.repo) === key));
+    if (hit) return hit[0];
+    throw new Error(`no entry for ${handle}`);
+  }
+  const prdId = basename(handle).replace(/\.md$/, "");
+  const byPrd = entries.filter(([id]) => id.endsWith(`/${prdId}`));
+  if (byPrd.length === 1) return byPrd[0][0];
+  if (byPrd.length > 1) throw new Error(`"${handle}" matches ${byPrd.map(([id]) => id).join(", ")}; use the full id`);
+  throw new Error(`no entry for ${handle}`);
+}
+
+/**
+ * The event cursor, in one place, so every writer obeys the same rule.
+ *
+ * `since` is the boundary and `dispatched` the keys already handled *at* that boundary. GitHub timestamps have
+ * one-second precision, so the comparison in `deriveEvents` is inclusive of `since` and `dispatched` is the only
+ * thing that keeps an event from being sent twice. The two therefore move together: any move to a different
+ * instant clears the list, and a move that stays inside the same second keeps it and adds to it. Everything else
+ * about the cursor (`fixed_sha`, `checks_sha`, `receipt_hash`) is carried through untouched.
+ *
+ * The cursor never goes backwards, and that is enforced here rather than asked of each caller. Three callers pass a
+ * candidate boundary from a different source: the newest event dispatched, the head commit's committer date, and a
+ * local clock reading. Only the first was guarded. A committer date older than the cursor (a force-push to an
+ * earlier commit, a push of a commit made days ago) or a clock a second behind GitHub's would move `since` back,
+ * and `advanceCursor` would then clear `dispatched` because the instant changed, so the event that started the
+ * round became new again and was dispatched a second time in the same pass, with a round burned for it. A candidate
+ * before the cursor leaves both fields alone: nothing new was read, so nothing is newly handled.
+ */
+export function advanceCursor(cursor = {}, candidate, keys = []) {
+  const since = later(candidate, cursor.since);
+  // A candidate strictly before the cursor is refused outright: the boundary does not move and the keys are not
+  // recorded either, because nothing was newly read to record. Only a candidate at the cursor's own instant unions
+  // into `dispatched`; one past it replaces the list, since a different second has nothing to remember.
+  if (candidate && cursor.since && Date.parse(candidate) < Date.parse(cursor.since)) return { ...cursor, since };
+  const same = cursor.since && since && Date.parse(cursor.since) === Date.parse(since);
+  const dispatched = same ? [...new Set([...(cursor.dispatched || []), ...keys])] : [...new Set(keys)];
+  return { ...cursor, since, dispatched };
+}
+
+/**
+ * A fresh entry, so every field exists and `status` never has to guess.
+ * cursor.since: events at or after this time are new. cursor.dispatched: the event keys already dispatched at
+ * exactly `since`, which is what makes the inclusive comparison safe. cursor.fixed_sha: the head the loop last acted
+ * on, so a change in it is a push nobody told the loop about. It is the head when the last run started, which is how
+ * a run that pushed is recognised, and the head an entry was judged ready on, which is how a push after that is.
+ * cursor.checks_sha: the head whose failing checks were already dispatched. cursor.receipt_hash: the completion
+ * receipt when the last run started. last.run: the run this entry dispatched; the tick settles that run and no other.
+ * retry: `{ op, count }` while one GitHub write the tick declines a step for keeps failing, null otherwise. It is the
+ * bound on those waits: `tick.mjs` stops the entry with `stuck` once one operation has failed enough ticks in a row,
+ * and clears the field the moment the write lands, so an entry that recovers is never stopped for the ticks it lost.
+ */
+export function newEntry({ prd, harness, session = null, repo, branch, worktree, pr = null, url = null, state, nowIso, checkout = null, prdFingerprint = null, prdDecision = null, base = null, sources = [] }) {
+  return {
+    prd, harness, session, repo: repo.toLowerCase(), branch, worktree, pr, url, state,
+    // The branch this pull request targets, recorded because it is what the daemon merges in before every fix round
+    // and what `status` and `why` print so an operator can see what a PR will target before it is opened. Null on an
+    // entry that never learned one, which is every entry `register` and `reconcile` build before they read the PR's own
+    // `baseRefName`; null means "ask the PR", never "assume the default branch".
+    base,
+    // Where the OPERATOR's copy of the brief lives, and what the snapshot's contract looked like when it was taken.
+    // `checkout` is what makes the comparison possible at all: `join(checkout, prd)` is the file to compare the snapshot
+    // against, and `entry.prd` is relative, so without this half there is nothing to join it to. Null on an entry that
+    // never saw the operator's tree, which is every entry `register` and `reconcile` build, and null is what makes the
+    // comparison answer "unknown" rather than stopping a recovered PR for a tree it was never told about.
+    //
+    // `prd_fingerprint` and `prd_decision` are the contract and the readiness decision the snapshot carries, recorded at
+    // the same moment as the snapshot itself. They are a record rather than an input: the comparison recomputes both
+    // fingerprints from the two files, because the snapshot on disk is the thing the gate actually reads and a stored
+    // fingerprint that disagreed with it would be worse than no fingerprint at all. What they are for is telling an
+    // operator what moved: `why` compares `prd_decision` with the brief's current `aport_decision` to say whether the edit
+    // went through `gallivant ready`.
+    checkout, prd_fingerprint: prdFingerprint, prd_decision: prdDecision,
+    // The files this brief carries, recorded so the daemon can compare them without re-reading the brief. Empty on
+    // every entry `register` and `reconcile` build, which is correct: a PR adopted from GitHub carries nothing, because
+    // nothing was carried into it.
+    sources,
+    iteration: 0,
+    cursor: { since: nowIso, dispatched: [], fixed_sha: null, checks_sha: null, receipt_hash: null },
+    rereview: { at: null, nudged: false },
+    reason: null,
+    retry: null,
+    last: null,
+    created_at: nowIso,
+    updated_at: nowIso,
+  };
+}

package/lib/task_allowance.mjs

@@ -0,0 +1,31 @@
+import { executionError } from "./execution_io.mjs";
+// Scoped consumers pin their authorized implementation allowance in task metadata.
+// Legacy/operator entries keep their existing configured behavior.
+export function taskExecutionConfig(config, task, execution = null, { excludeRunId = null } = {}) {
+  const allowance = task?.deliveryAllowance;
+  if (!allowance) return config;
+  if (!Number.isFinite(allowance.budgetUsd) || allowance.budgetUsd <= 0 || !Number.isFinite(allowance.runtimeMs) || allowance.runtimeMs <= 0) throw executionError("EXECUTION_ALLOWANCE", "Saved task allowance is exhausted or invalid; inspect its original authorization");
+  let spent = 0, elapsedMs = 0;
+  if (execution) {
+    const ledger = execution.state?.();
+    if (!ledger && execution.current()) throw executionError("EXECUTION_ALLOWANCE", "Scoped continuation requires the durable execution ledger; inspect the original runtime binding");
+    for (const op of Object.values(ledger?.operations || {})) {
+      if (op.runId === excludeRunId) continue;
+      if (execution.capabilities?.transport !== "remote") {
+        if (!Number.isFinite(op.costUsd)) throw executionError("EXECUTION_ALLOWANCE", "Previous local cost is unknown; reconcile it before authorizing another run");
+        spent += op.costUsd;
+      }
+      const job = execution.read(op.runId);
+      if (!job || !Number.isFinite(job.endedAt) || !Number.isFinite(job.startedAt) || job.endedAt < job.startedAt) throw executionError("EXECUTION_ALLOWANCE", "Previous execution duration is unknown; reconcile it before authorizing another run");
+      elapsedMs += job.endedAt - job.startedAt;
+    }
+  }
+  if (spent >= allowance.budgetUsd || elapsedMs >= allowance.runtimeMs) throw executionError("EXECUTION_ALLOWANCE", "Saved task allowance is exhausted; no further run was dispatched");
+  return { ...config, max_budget_usd: Math.min(config.max_budget_usd, allowance.budgetUsd - spent), run_timeout_minutes: Math.min(config.run_timeout_minutes, (allowance.runtimeMs - elapsedMs) / 60000) };
+}
+export function taskProviderAllowance(allowance, task) {
+  if (!task?.deliveryAllowance) return allowance;
+  const cap = task.deliveryAllowance.budgetUsd;
+  if (!Number.isFinite(cap) || cap <= 0 || !allowance || allowance.reservedUsd > cap) throw executionError("EXECUTION_ALLOWANCE", "Provider reservation exceeds the saved task allowance; configure a smaller bounded reservation");
+  return { ...allowance, remainingUsd: Math.min(allowance.remainingUsd, cap) };
+}

package/lib/task_completion.mjs

@@ -0,0 +1,61 @@
+// Portable milestones, with one currently supported observation adapter. A
+// target selects what is fulfilled; it never grants merge/deployment authority.
+import { ownerDeliveryEvidence, matchingDeliveryEvidence } from "./owner_delivery.mjs";
+import { controlPending } from "./control_contract.mjs";
+import { executionLive } from "./execution_contract.mjs";
+import { learningDeliveryPending } from "./learning_contract.mjs";
+import { networkRecoveryPending, networkRecoveryDetail } from "./network_recovery.mjs";
+export const COMPLETION_SCHEMA = Object.freeze({ type: "object", properties: {
+  target: { type: "string", enum: ["delivery_ready", "integrated"] },
+}, required: ["target"], additionalProperties: false });
+export const COMPLETION_CAPABILITIES = Object.freeze({ version: 1, defaultTarget: "delivery_ready", targets: [
+  { id: "delivery_ready", label: "Ready for handoff", description: "The current delivery passes the existing checks, reviewer and completion gate.", adapter: "github-pull-request" },
+  { id: "integrated", label: "Merged", description: "Keep watching the qualified delivery until an authorized person or system merges it. This does not authorize a merge.", adapter: "github-pull-request" },
+] });
+export function completionPolicy(value) {
+  if (value === undefined) return { version: 1, target: "delivery_ready" };
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length !== 1 || !Object.hasOwn(value, "target") || !COMPLETION_SCHEMA.properties.target.enum.includes(value.target)) {
+    throw Object.assign(new Error("completion must select a supported target: delivery_ready or integrated; it does not grant integration authority"), { code: "TASK_INPUT" });
+  }
+  return { version: 1, target: value.target };
+}
+export function completionView(policy, entry = null, ownerDelivery = null, current = null) {
+  const selected = policy || entry?.task?.completion || { version: 1, target: "delivery_ready" };
+  const descriptor = COMPLETION_CAPABILITIES.targets.find(target => target.id === selected.target);
+  const evidence = entry?.completionEvidence || {};
+  const legacy = !policy && !entry?.task?.completion;
+  let status = "pending", reason = null;
+  if (entry?.dispatch_stopped || ["cancelled", "cancellation-requested"].includes(entry?.reason)) { status = "cancelled"; reason = "Further dispatch is stopped; provider cancellation may still require confirmation."; }
+  else if (evidence.terminal?.state === "CLOSED") { status = "blocked"; reason = "The delivery was closed without integration."; }
+  else if (networkRecoveryPending(entry)) { status = "pending"; reason = networkRecoveryDetail(entry.network_retry); }
+  else if (evidence.integration?.qualified === true) status = "fulfilled";
+  else if (evidence.terminal?.state === "MERGED") { status = "unverified"; reason = evidence.integration?.reason || "Integration was observed without a matching qualified delivery."; }
+  else if (entry?.state === "ready-for-human" && matchingDeliveryEvidence(entry)) status = selected.target === "integrated" ? "awaiting_integration" : "fulfilled";
+  else if (entry?.state === "needs-human") { status = "blocked"; reason = entry.reason || "The delivery needs human attention."; }
+  else if (entry && ["ready-for-human", "done"].includes(entry.state)) { status = "unverified"; reason = "No canonical completion evidence is recorded for this delivery."; }
+  const ownership = ownerDelivery || entry?.task?.ownerDelivery;
+  const obligations = ownerDeliveryEvidence(ownership, entry, status);
+  if (obligations.some(o => o.status !== "fulfilled") && ["fulfilled", "awaiting_integration"].includes(status)) { status = "unverified"; reason = "The owner publication obligation lacks matching coordinator delivery evidence."; }
+  if (["fulfilled", "awaiting_integration"].includes(status) && completionWorkPending(entry, current)) { status = "pending"; reason = "Owned execution still requires reconciliation or collection."; }
+  return { ...selected, label: descriptor?.label || null, description: descriptor?.description || null, status, adapter: "github-pull-request", legacy, evidence, reason,
+    ...(ownership ? { obligations } : {}),
+    monitoring: Boolean(entry && (networkRecoveryPending(entry) || ["pr-open", "ready-for-human", "running"].includes(entry.state)) && !stopsAutomation(entry, selected, status, legacy, current)), mergeAuthorized: false };
+}
+
+const completionWorkPending = (entry, current) => Boolean(executionLive(entry) || executionLive(current) || current?.running ||
+  current && current.id === entry?.last?.run && entry.last.exit == null);
+const stopsAutomation = (entry, selected, status, legacy, current) => Boolean(entry?.state === "ready-for-human" && !legacy &&
+  selected.version === 1 && selected.target === "delivery_ready" && status === "fulfilled" && matchingDeliveryEvidence(entry) && !controlPending(entry.control) && !completionWorkPending(entry, current));
+export function completionStopsAutomation(entry, current = null) {
+  // Malformed saved ownership remains unqualified and is handled per entry by
+  // the normal tick. It must neither suppress work nor abort the entire sweep.
+  try {
+    const view = completionView(null, entry, null, current);
+    return stopsAutomation(entry, view, view.status, view.legacy, current);
+  } catch { return false; }
+}
+// Hosts consume the engine's decision, rather than interpreting ready as active
+// forever. Other terminal/paused states retain the existing scheduling contract.
+export function coordinatorEntryActive(entry, current = null) {
+  return Boolean(entry && (learningDeliveryPending(entry) || networkRecoveryPending(entry) || !["done", "needs-human"].includes(entry.state) && !completionStopsAutomation(entry, current)));
+}