@uchibeke/gallivant 0.2.0 → 0.3.0

package/lib/state.mjs

@@ -1,13 +1,17 @@
+import { repositoryIdentity, savedRepository } from "./repository.mjs";
 // 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 { openSync, closeSync, unlinkSync, statSync, readFileSync, writeFileSync } from "node:fs";
 import { readJson, writeJsonAtomic, gallivantHome } from "./fs.mjs";
+import { reviewHistoryStore } from "./review_history.mjs";
 import { later } from "./time.mjs";
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { assertReviewPolicy } from "./review_policy.mjs";
 
 export const STATES = Object.freeze({
   running: "running",           // start run in progress, no PR yet
@@ -18,6 +22,7 @@ export const STATES = Object.freeze({
 });
 
 export const statePath = (home = gallivantHome()) => join(home, "state.json");
+export const supportedStateVersion = version => version === 1 || version === 2;
 
 /**
  * The repository name without its owner, for a handle a person reads: `acme/widget` is `widget`. Anything that is
@@ -26,34 +31,55 @@ export const statePath = (home = gallivantHome()) => join(home, "state.json");
  * `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; };
+export const shortRepo = nameWithOwner => { const s = String(nameWithOwner ?? ""); return s.split("/").at(-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);
+export const handleFor = (id, entry) => {
+  if (!entry.pr) return id;
+  let repo = shortRepo(entry.repo);
+  try { const identity = repositoryIdentity(entry.repo); if (identity.host !== "github.com") repo = identity.remoteIdentity; } catch { /* Display opaque historical handles safely. */ }
+  return `${repo}#${entry.pr}`;
+};
 
 /** 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}`;
+export const entryId = (nameWithOwner, prdId) => `${repositoryIdentity(nameWithOwner).key}/${prdId}`;
+
+/** An existing predecessor is observed, never adopted into a chain's owned steps. */
+export const matchesChainAnchor = (anchor, entry) => !!entry
+  && ["repo", "base", "branch", "pr", "url"].every(key => entry[key] === anchor[key]);
 
 /** 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("/", "__");
+export const idSlug = id => id.split("/").length === 4 ? `host~${id.split("/").map(encodeURIComponent).join("~")}` : 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. */
+// A live owner can hold the lock longer than the stale interval during the
+// one-time migration of large histories. PID reuse may delay recovery, but it
+// must never permit a second writer while the recorded owner is still alive.
+function lockOwnerAlive(lock) {
+  try {
+    const { pid } = JSON.parse(readFileSync(lock, "utf8"));
+    if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+    try { process.kill(pid, 0); return true; }
+    catch (error) { return error.code !== "ESRCH"; }
+  } catch { return false; } // historical empty lock files retain old recovery behavior
+}
+
+/** Hold an exclusive lock file for the duration of `fn`. Waits up to five seconds; recover stale dead-owner locks. */
 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 */ } }
+      try { writeFileSync(fd, JSON.stringify({ pid: process.pid })); 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; }
+      try { if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS && !lockOwnerAlive(lock)) { 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);
     }
@@ -62,13 +88,66 @@ function withLock(file, fn) {
 
 export function makeState(home = gallivantHome()) {
   const file = statePath(home);
-  const load = () => {
+  const historyStore = reviewHistoryStore(home);
+  let cached = null;
+  const signature = () => {
+    try { const s = statSync(file, { bigint: true }); return `${s.dev}:${s.ino}:${s.size}:${s.mtimeNs}:${s.ctimeNs}`; }
+    catch { return null; }
+  };
+  const read = () => {
+    const before = signature();
+    if (before && cached?.signature === before) return cached.value;
     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" });
+    if (!supportedStateVersion(s.version)) 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" });
+    for (const e of Object.values(s.entries)) if (e.reviewPolicy) assertReviewPolicy(e.reviewPolicy);
+    const identities = new Set();
+    for (const [id, entry] of Object.entries(s.entries)) {
+      if (!entry.repo) continue;
+      const repository = savedRepository(entry);
+      const expected = `${repository.key}/`;
+      if (repository.host !== "github.com" && !id.toLowerCase().startsWith(expected)) throw new Error("Ambiguous saved entry ID; back up state and reconcile its qualified repository before restarting. Do not redispatch.");
+      if (entry.pr) {
+        const key = `${repository.remoteIdentity}#${entry.pr}`;
+        if (identities.has(key)) throw new Error("Duplicate saved PR identity; back up state and reconcile its entries and cursors before restarting. Do not redispatch.");
+        identities.add(key);
+      }
+    }
+    for (const chain of Object.values(s.chains || {})) if (chain.repo) savedRepository(chain);
+    const after = signature();
+    cached = before && before === after ? { signature: after, value: s } : null;
     return s;
   };
-  const save = s => writeJsonAtomic(file, s, 0o600);
+  // Public reads and mutation callbacks receive detached values, as they did
+  // when each read parsed a fresh file. Atomic replacement by another process
+  // changes the signature and forces validation of the new registry.
+  const load = () => structuredClone(read());
+  const save = s => {
+    // Archive before publishing references. Unchanged summaries do not read or
+    // serialize full historical evidence, even across process restarts.
+    let hasArchivedHistory = false;
+    const entries = Object.fromEntries(Object.entries(s.entries).map(([id, entry]) => {
+      if (!Array.isArray(entry.reviewHistory)) return [id, entry];
+      const lastByKey = new Map(), reviewHistory = [];
+      for (const item of entry.reviewHistory) {
+        const archived = historyStore.archive(item), marker = archived?._gallivantReviewArchive?.digest;
+        if (marker) hasArchivedHistory = true;
+        // Repeated persistence of the same key/version is redundant, but an
+        // earlier identical version after an intervening disposition is not:
+        // e.g. pending -> intent -> pending represents a proven unsent retry.
+        if (marker && typeof archived.key === "string") {
+          if (lastByKey.get(archived.key) === marker) continue;
+          lastByKey.set(archived.key, marker);
+        }
+        reviewHistory.push(archived);
+      }
+      return [id, { ...entry, reviewHistory }];
+    }));
+    // Version 2 fences older processes that do not understand the compact
+    // references. Never downgrade, even if the last archived entry is removed.
+    const compact = { ...s, version: hasArchivedHistory ? 2 : s.version, entries };
+    cached = null; writeJsonAtomic(file, compact, 0o600); return compact;
+  };
   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) => {
@@ -77,27 +156,46 @@ export function makeState(home = gallivantHome()) {
   return {
     file,
     load,
-    entries: () => Object.entries(load().entries),
-    get: id => load().entries[id] || null,
+    entries: () => Object.entries(read().entries).map(([id, entry]) => [id, structuredClone(entry)]),
+    get: id => { const entry = read().entries[id]; return entry ? structuredClone(entry) : null; },
+    reviewHistory: id => (read().entries[id]?.reviewHistory || []).map(item => structuredClone(historyStore.hydrate(item))),
+    reviewHistoryRecord: (id, key) => { const item = read().entries[id]?.reviewHistory?.findLast(record => record.key === key); return item ? structuredClone(historyStore.hydrate(item)) : 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,
+    findByPr: (repo, pr) => { const found = Object.entries(read().entries).find(([, e]) => savedRepository(e).remoteIdentity === repositoryIdentity(repo).remoteIdentity && e.pr === pr); return found ? structuredClone(found) : null; },
     put: (id, entry) => locked(() => {
       const s = load();
       assertCanPut(s, id);
-      s.entries[id] = entry; save(s); return entry;
+      if (isDeepStrictEqual(s.entries[id], entry)) return structuredClone(entry);
+      s.entries[id] = entry; return structuredClone(save(s).entries[id]);
+    }),
+    update: (id, patch) => locked(() => {
+      // Only the selected entry is exposed to a mutation callback. Cloning the
+      // entire registry here makes every small update copy unrelated review
+      // histories, which can be hundreds of megabytes. Keep the cached root
+      // untouched and detach the selected entry before invoking user code.
+      const original = read(), entry = original.entries[id];
+      if (!entry) throw new Error(`no entry ${id}`);
+      const current = structuredClone(entry);
+      const updated = { ...current, ...(typeof patch === "function" ? patch(current) : patch) };
+      // Compare under the lock against freshly observed state, not a caller's
+      // cache. A no-op neither rewrites the registry nor migrates its format.
+      if (isDeepStrictEqual(entry, updated)) return updated;
+      const next = { ...original, entries: { ...original.entries, [id]: updated } };
+      return structuredClone(save(next).entries[id]);
     }),
-    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`);
+      if (!Object.hasOwn(s.entries, id)) return;
       delete s.entries[id]; save(s);
     }),
-    chains: () => Object.entries(load().chains || {}),
-    getChain: name => load().chains?.[name] || null,
+    chains: () => Object.entries(read().chains || {}).map(([name, chain]) => [name, structuredClone(chain)]),
+    getChain: name => { const chain = read().chains?.[name]; return chain ? structuredClone(chain) : null; },
     createChain: chain => locked(() => {
       const s = load();
       if (s.chains?.[chain.name]) throw new Error(`chain ${chain.name} already exists`);
+      if (chain.after && !matchesChainAnchor(chain.after, s.entries[chain.after.id])) throw new Error("chain predecessor identity changed while queueing");
       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`);
       }
@@ -106,11 +204,13 @@ export function makeState(home = gallivantHome()) {
     updateChain: (name, patch) => locked(() => {
       const s = load(), cur = s.chains?.[name];
       if (!cur) throw new Error(`no chain ${name}`);
+      const before = structuredClone(cur);
       s.chains[name] = { ...cur, ...(typeof patch === "function" ? patch(cur) : patch) };
+      if (isDeepStrictEqual(before, s.chains[name])) return s.chains[name];
       save(s); return s.chains[name];
     }),
-    startClaim: id => load().starts?.[id] || null,
-    assertCanRegister: id => assertCanPut(load(), id),
+    startClaim: id => { const claim = read().starts?.[id]; return claim ? structuredClone(claim) : null; },
+    assertCanRegister: id => assertCanPut(read(), 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);
@@ -118,6 +218,7 @@ export function makeState(home = gallivantHome()) {
       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`);
+        if (c.after && (!c.after.merged || !matchesChainAnchor(c.after, s.entries[c.after.id]))) throw new Error("chain predecessor merge or identity is no longer approved");
       } 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;
@@ -136,12 +237,23 @@ export function makeState(home = gallivantHome()) {
       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`);
+      if (chain && c.after && (!c.after.merged || !matchesChainAnchor(c.after, s.entries[c.after.id]))) throw new Error("chain predecessor merge or identity is no longer approved");
     }),
     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];
     }),
+    // Progress polling must not clone the full captured source and review history.
+    reviewActivityEntry: id => {
+      const entry = read().entries[id]; if (!entry) return null;
+      const p = entry.reviewPolicy, r = entry.firstPartyReview;
+      return { reviewPolicy: p ? { version: p.version, mode: p.mode } : null,
+        firstPartyReview: r ? { status: r.status, phase: r.phase, error: r.error,
+          pieces: (r.pieces || []).map(piece => ({ status: piece.status })),
+          result: r.result ? { verdict: r.result.verdict, findingsCount: Array.isArray(r.result.findings) ? r.result.findings.length : 0 } : null,
+          disposition: r.disposition ? { status: r.disposition.status } : null } : null };
+    },
   };
 }
 
@@ -154,12 +266,13 @@ export function resolveHandle(entries, handle) {
   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+)$/);
+  const m = handle.match(/^([\w.-]+(?:\/[\w.-]+){0,2})#(\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];
+    const hits = entries.filter(([, e]) => e.pr === Number(n) && (e.repo === key || savedRepository(e).remoteIdentity === key || shortRepo(e.repo) === key || savedRepository(e).path === key));
+    if (hits.length > 1) throw new Error(`Ambiguous handle; use a qualified host/owner/repository#${n}: ${hits.map(([, e]) => `${savedRepository(e).remoteIdentity}#${n}`).join(", ")}`);
+    if (hits.length === 1) return hits[0][0];
     throw new Error(`no entry for ${handle}`);
   }
   const prdId = basename(handle).replace(/\.md$/, "");
@@ -211,7 +324,7 @@ export function advanceCursor(cursor = {}, candidate, keys = []) {
  */
 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,
+    prd, harness, session, repo: repositoryIdentity(repo).key, host: repositoryIdentity(repo).host, 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

package/lib/task_completion.mjs

@@ -1,3 +1,4 @@
+import { completionAdapter } from "./host_definitions.mjs";
 // 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";
@@ -9,8 +10,8 @@ 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" },
+  { id: "delivery_ready", label: "Ready for handoff", description: "The current delivery passes the existing checks, reviewer and completion gate.", adapter: completionAdapter() },
+  { 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: completionAdapter() },
 ] });
 export function completionPolicy(value) {
   if (value === undefined) return { version: 1, target: "delivery_ready" };
@@ -37,7 +38,7 @@ export function completionView(policy, entry = null, ownerDelivery = null, curre
   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,
+  return { ...selected, label: descriptor?.label || null, description: descriptor?.description || null, status, adapter: observedAdapter(entry), 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 };
 }
@@ -45,6 +46,7 @@ export function completionView(policy, entry = null, ownerDelivery = null, curre
 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 &&
+  entry.reviewPolicy?.version !== 1 &&
   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
@@ -59,3 +61,5 @@ export function completionStopsAutomation(entry, current = null) {
 export function coordinatorEntryActive(entry, current = null) {
   return Boolean(entry && (learningDeliveryPending(entry) || networkRecoveryPending(entry) || !["done", "needs-human"].includes(entry.state) && !completionStopsAutomation(entry, current)));
 }
+
+function observedAdapter(entry) { try { return completionAdapter(entry?.repo); } catch { return null; } }