agent-coord-mcp 0.26.21 → 0.26.23

package/src/capabilities.ts

@@ -47,6 +47,11 @@ import {
   type TransportKind,
 } from "./transports/index.js";
 import { readAllTransportMarkers } from "./tools/registry.js";
+import { queueWriteSchema } from "./tools/queue-write.js";
+import { treeProvenance } from "./tools/tree-provenance.js";
+import { detectSpread } from "./server-spread.js";
+import { HerdrTransport, herdrKeyName } from "./transports/herdr.js";
+import { HERDR } from "./transports/types.js";
 
 export type ProbeResult = {
   id: string;
@@ -59,6 +64,69 @@ export type ProbeResult = {
 
 type Probe = { id: string; since: string; run: () => { present: boolean; evidence: string } };
 
+/**
+ * ⛔⛆⛆ THE PROBE DECISIONS ARE EXPORTED AS PURE PREDICATES, AND THE MUTATION
+ * MATRIX IS WHY.
+ *
+ * Their first form computed `present` inline and built an evidence string from
+ * the same raw values. Deleting a conjunct from `present` reddened NOTHING: the
+ * tests asserted the EVIDENCE TEXT, which the mutation did not touch, and the
+ * probe's own fixed input could not produce the rejected case. ⭐⭐ ***A
+ * predicate that cannot be handed the input it is supposed to reject is not
+ * guarded — it is decorative, which is the defect one row over and the same
+ * shape this row is about.***
+ *
+ * Exported so a control can pass the failing shape directly.
+ */
+export function retagAccepted(parse: (v: string) => boolean): boolean {
+  // BOTH halves matter: the new member must parse AND a pre-existing one must
+  // still parse. Without the control a schema that accepted ANY string would pass.
+  return parse("retag") === true && parse("reprioritise") === true;
+}
+
+/**
+ * `#283`'s load-bearing property, and it is NOT "it answered": an unfetchable
+ * tree must report `"unknown"` and NEVER `0`. A distance of `0` from an
+ * unfetched ref and from a fetched one are byte-identical and mean opposite
+ * things — so a numeric `behind` on a tree that was never fetched is the exact
+ * failure the verb exists to prevent.
+ */
+export function treeProvenanceRefusesZero(r: { behind: number | "unknown"; fetched: boolean; stale: boolean }): boolean {
+  return r.behind === "unknown" && r.fetched === false && r.stale === false;
+}
+
+/**
+ * `#293`'s load-bearing property (0.26.22): a seat that publishes NO module path
+ * makes the fleet `CANNOT_COMPARE` — it is never dropped from the population so
+ * the readable rest can answer `AGREED`. ⛔ BOTH CONTROLS ARE CONJUNCTS ON
+ * PURPOSE: readable seats on one side of the install must still `AGREED` and on
+ * two sides must still `DIVERGED`, or a detector that answered
+ * `CANNOT_COMPARE` for everything would pass this probe while detecting nothing.
+ *
+ * ⭐ AND THIS PROBE EXISTS BECAUSE THE GATE ONE ROW OVER FIRED ON ITS OWN PR:
+ * `#293` bumped `0.26.22` with behaviour and no probe, `main` moved under
+ * `#292`, and qa measured `probedThrough 0.26.21 < running 0.26.22 → ok:false`.
+ * The remedy is the probe, not a softer comparison — softening it would turn
+ * the verb back into the label read ⟨q-1c8e35f9⟩ exists to end.
+ */
+/**
+ * ⟨q-8a3f1c05⟩ / #303 — IN-FLIGHT IS DERIVED FROM THE SEAM, NOT MATCHED ON A GLYPH.
+ * A 0.26.21 server read `⛔ Blocked — was 🚧 until the base went red` as IN FLIGHT
+ * (the regex `/🚧|🔍/` matched the mention); the seam's `workStateOf` reads the
+ * LEADING glyph and answers blocked. All three conjuncts matter: the old answer
+ * for the blocked row must be refused AND the two genuine in-flight states must
+ * still read in flight, or a predicate that answers false to everything passes.
+ * The version label did not move for #303 (still 0.26.22), so `check-probe-coverage`
+ * could not see the behaviour arrive — this probe is what sees it.
+ */
+export function inFlightDerivedFromSeam(inFlight: (status: string) => boolean): boolean {
+  return inFlight("⛔ Blocked — was 🚧 until the base went red") === false && inFlight("🔍 In Review") === true && inFlight("🚧 In Progress") === true;
+}
+
+export function spreadPoisonedByUnreadableSeat(states: { unreadable: string; agreed: string; diverged: string }): boolean {
+  return states.unreadable === "CANNOT_COMPARE" && states.agreed === "AGREED" && states.diverged === "DIVERGED";
+}
+
 /**
  * Each probe calls a behaviour that did not exist before its release and
  * reports what it observed. A probe that could pass without the code being
@@ -124,6 +192,104 @@ const PROBES: Probe[] = [
       };
     },
   },
+  /**
+   * ⛔⛆⛆ THE PROBES BELOW CLOSE THE WINDOW ⟨q-1c8e35f9⟩ MEASURED.
+   *
+   * Before them the newest `since` was `0.26.15`, so `capabilities` answered
+   * `ok · missing: []` identically on every version from `0.26.16` to `0.26.21`
+   * — the whole set the fleet was about to install.
+   *
+   * ⚠ AND THE TRAP THE ROW NAMES IS THE ONE TO AVOID WHILE WRITING THESE:
+   * `away-means-david-away` EXISTS, its NAME matches the changed area, and its
+   * ASSERTION predates the change — it tests `0.26.13`'s refusal list, not
+   * `#216`'s query mode. ⭐⭐ ***A probe whose name matches while its assertion
+   * predates reads as coverage and is not. So each probe below asserts a
+   * behaviour that DID NOT EXIST before its own `since`, and would throw or
+   * return `false` on the release before it.***
+   */
+  {
+    // #284 — `queue_write` gained `op: "retag"`. On 0.26.20 the enum has three
+    // members and parsing `"retag"` throws, which is the probe's whole point.
+    id: "queue-write-retag",
+    since: "0.26.21",
+    run: () => {
+      const parse = (v: string) => queueWriteSchema.op.safeParse(v).success === true;
+      const present = retagAccepted(parse);
+      return {
+        present,
+        evidence: `queue_write op accepts "retag": ${parse("retag")} (control "reprioritise": ${parse("reprioritise")}) -> present=${present}`,
+      };
+    },
+  },
+  {
+    // #283 — every `repo`-taking verb reports the tree it read. The load-bearing
+    // property is NOT that it answers, it is that an unfetchable tree yields
+    // `"unknown"` and NEVER `0`: a distance of 0 from an unfetched ref and from a
+    // fetched one are byte-identical and mean opposite things.
+    id: "tree-provenance-unknown-not-zero",
+    since: "0.26.21",
+    run: () => {
+      const r = treeProvenance("/nonexistent-path-for-capability-probe");
+      const present = treeProvenanceRefusesZero(r);
+      return {
+        present,
+        evidence: `unreachable tree -> behind=${JSON.stringify(r.behind)} fetched=${r.fetched} stale=${r.stale} -> present=${present}`,
+      };
+    },
+  },
+  {
+    // #293 — `detectSpread` did not exist before 0.26.22. The property is not
+    // "it answers": an UNREADABLE seat must poison the verdict rather than be
+    // dropped, while readable seats still resolve to AGREED / DIVERGED.
+    id: "server-spread-unreadable-poisons",
+    since: "0.26.22",
+    run: () => {
+      const installed = { mtime: 1_000, module: "/installed-for-capability-probe" };
+      const a = { agentId: "a", serverStartedAt: 2_000, serverModule: installed.module };
+      const b = { agentId: "b", serverStartedAt: 3_000, serverModule: installed.module };
+      const older = { agentId: "older", serverStartedAt: 500, serverModule: installed.module };
+      const mute = { agentId: "mute" };
+      const states = {
+        unreadable: detectSpread([a, mute], installed).state,
+        agreed: detectSpread([a, b], installed).state,
+        diverged: detectSpread([a, older], installed).state,
+      };
+      const present = spreadPoisonedByUnreadableSeat(states);
+      return {
+        present,
+        evidence: `unreadable seat -> ${states.unreadable} · same side -> ${states.agreed} · two sides -> ${states.diverged} -> present=${present}`,
+      };
+    },
+  },
+  {
+    // #303 (shipped under 0.26.22, no bump) — `isInFlightStatus` derives from the seam.
+    id: "in-flight-derives-from-seam",
+    since: "0.26.22",
+    run: () => {
+      const blocked = isInFlightStatus("⛔ Blocked — was 🚧 until the base went red");
+      const review = isInFlightStatus("🔍 In Review");
+      const present = inFlightDerivedFromSeam(isInFlightStatus);
+      return { present, evidence: `"⛔ Blocked — was 🚧 …" in flight: ${blocked} (0.26.21 said true) · "🔍 In Review": ${review} -> present=${present}` };
+    },
+  },
+  {
+    // Phase 5.4 Task 4 (0.26.23) — the herdr transport exists and refuses by name: a scripted
+    // dead pane reads dead from herdr's own reply, and a tmux key name is refused, not typed.
+    id: "herdr-transport-registered",
+    since: "0.26.23",
+    run: () => {
+      const scripted = new HerdrTransport({
+        run: (a) => (a[0] === "status"
+          ? { ok: true, status: 0, stdout: "server:\n  status: running\n", stderr: "" }
+          : { ok: false, status: 0, stdout: "", stderr: "", json: { error: { code: "pane_not_found", message: "pane w0:p0 not found" } }, error: { code: "pane_not_found", message: "pane w0:p0 not found" } }),
+        sleep: () => {},
+      });
+      const key = herdrKeyName("C-u");
+      const exists = scripted.paneExists("w0:p0");
+      const present = scripted.kind === HERDR && exists === false && key.ok === false;
+      return { present, evidence: `HerdrTransport.kind=${scripted.kind} · scripted pane_not_found -> paneExists=${exists} · herdrKeyName("C-u").ok=${key.ok} -> present=${present}` };
+    },
+  },
   {
     id: "record-authority",
     since: "0.24.0",
@@ -184,13 +350,82 @@ export type CapabilityReport = {
    */
   answeredBy: { pid: number; startedAtIso: string; module: string; versionLabel: string };
   probes: ProbeResult[];
+  /** Whether the probes reach the version this process claims to be. */
+  coverage: {
+    probedThrough: string | null;
+    running: string;
+    covered: boolean;
+    verdict: string;
+  };
   missing: string[];
+  /** Every probe passed AND the probes reach the running version. */
   ok: boolean;
   /** Absent only if the probe itself threw — see `probeTransport`. */
   transport?: TransportCapability;
   note: string;
 };
 
+/**
+ * ⛔⛆⛆ `missing: []` MEANS TWO DIFFERENT THINGS AND THIS SEPARATES THEM.
+ *
+ * "Nothing is missing" and "nothing was tested" produce the SAME answer today.
+ * ⭐⭐ ***Measured 2026-09-14: `capabilities` answered `ok · missing: []`
+ * IDENTICALLY on `0.26.20` and `0.26.21` — the probe set stops at `since
+ * 0.26.15`, so every version the fleet was about to install was unprobed, and
+ * the verb the fleet reaches for to prove a restart took could not see the three
+ * changes it would have been asked to certify.***
+ *
+ * That is `0`-vs-`unknown` inside the instrument the six delivery states END on:
+ * while this is blind, `observed` is unmeasurable BY CONSTRUCTION and every
+ * "delivered" claim in the fleet rests on a version LABEL.
+ *
+ * ⚠ THE COMPARISON IS AGAINST THE LABEL, WHICH IS NOT EVIDENCE — and that is
+ * deliberate rather than sloppy. The label is the only statement of intent
+ * available about what this process is SUPPOSED to be; the probes are the only
+ * evidence about what it IS. Comparing them is precisely how a divergence
+ * becomes visible, and this function says which side is which rather than
+ * blending them.
+ */
+function coverageOf(probes: ProbeResult[], versionLabel: string) {
+  const cmp = (a: string, b: string) => {
+    const pa = a.split(".").map((n) => Number.parseInt(n, 10));
+    const pb = b.split(".").map((n) => Number.parseInt(n, 10));
+    for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+      const x = Number.isFinite(pa[i]) ? pa[i] : 0;
+      const y = Number.isFinite(pb[i]) ? pb[i] : 0;
+      if (x !== y) return x < y ? -1 : 1;
+    }
+    return 0;
+  };
+  const sinces = probes.map((p) => p.since).filter((v) => /^\d+(\.\d+)*$/.test(v));
+  const probedThrough = sinces.length ? sinces.reduce((hi, v) => (cmp(v, hi) > 0 ? v : hi)) : null;
+  const labelUsable = /^\d+(\.\d+)*$/.test(versionLabel);
+
+  if (!probedThrough || !labelUsable) {
+    return {
+      probedThrough,
+      running: versionLabel,
+      covered: false as const,
+      verdict:
+        `COVERAGE UNKNOWN — ${!probedThrough ? "no probe declares a numeric `since`" : "the version label is not numeric"}. ` +
+        `Unknown is not covered: this cannot be read as "nothing is missing".`,
+    };
+  }
+  const covered = cmp(probedThrough, versionLabel) >= 0;
+  return {
+    probedThrough,
+    running: versionLabel,
+    covered,
+    verdict: covered
+      ? `PROBES REACH THE RUNNING VERSION — newest probe \`since ${probedThrough}\`, label \`${versionLabel}\`. ` +
+        `So \`missing: []\` here means TESTED-AND-PRESENT rather than untested.`
+      : `UNPROBED WINDOW \`${probedThrough}\` → \`${versionLabel}\` — every behaviour introduced after ` +
+        `\`${probedThrough}\` is UNTESTED by this verb. \`missing: []\` below therefore does NOT mean "nothing is ` +
+        `missing"; it means "nothing in that window was looked at". A restart certified on this answer certifies the ` +
+        `versions it can see and is silent about the ones it cannot.`,
+  };
+}
+
 export function probeCapabilities(context: { module: string; versionLabel: string }): CapabilityReport {
   const probes: ProbeResult[] = PROBES.map((p) => {
     try {
@@ -205,7 +440,9 @@ export function probeCapabilities(context: { module: string; versionLabel: strin
     }
   });
   const missing = probes.filter((p) => !p.present).map((p) => p.id);
+  const coverage = coverageOf(probes, context.versionLabel);
   return {
+    coverage,
     answeredBy: {
       pid: process.pid,
       startedAtIso: new Date(Date.now() - Math.round(process.uptime() * 1000)).toISOString(),
@@ -214,7 +451,14 @@ export function probeCapabilities(context: { module: string; versionLabel: strin
     },
     probes,
     missing,
-    ok: missing.length === 0,
+    /**
+     * ⛔ `ok` NOW REQUIRES COVERAGE AS WELL AS PRESENCE. It previously meant
+     * "no probe failed", which on an unprobed version is "no probe ran" — the
+     * reading this row exists to stop. A reader asking "is this server good?"
+     * gets `false` when the honest answer is "I cannot tell", and `coverage`
+     * says which of the two it is.
+     */
+    ok: missing.length === 0 && coverage.covered,
     note:
       "Every line above was produced by CALLING the code in this process. `versionLabel` is a label someone typed " +
       "into package.json and is context, never evidence — a published tarball has already been observed carrying a " +
@@ -227,6 +471,8 @@ export function probeCapabilities(context: { module: string; versionLabel: strin
 /* ── the verb ──────────────────────────────────────────────────────────────── */
 
 import { resolveServerIdentity } from "./server-identity.js";
+import { seatBuildOf, installedFrom, psReader, type SeatBuild } from "./tools/seat-build.js";
+import { isInFlightStatus } from "./tools/stall.js";
 
 export const capabilitiesSchema = {} as const;
 
@@ -274,11 +520,47 @@ export async function probeTransport(): Promise<TransportCapability> {
   };
 }
 
+/**
+ * ⟨q-8a3f1c05⟩ — EVERY LIVE SEAT'S BUILD STATE, STATED. The restart operation read
+ * `capabilities` to certify a stage and it could not see a pusher; this is that verb
+ * answering the question it was asked. `seats[]` carries each live seat's PUSHER half
+ * (keyed by the `--agent` on its own command line, against the installed hook's mtime);
+ * `answering` carries the SERVER half of the one process that can know it — this one.
+ * Servers carry no `--agent`, so no other seat's server is observable from here, and
+ * each seat entry says so rather than borrowing its marker's attach-time stamp.
+ */
+export async function seatBuilds(): Promise<{ installed: { module: string; hookPath: string; hookMtime: string | null; buildMtime: string | null }; answering: SeatBuild["server"]; seats: SeatBuild[]; note: string }> {
+  const id = resolveServerIdentity();
+  const installed = installedFrom(id.path);
+  const startedAt = Date.now() - Math.round(process.uptime() * 1000);
+  const answering = seatBuildOf({ agentId: "(answering process)", marker: undefined, installed, ps: psReader, server: { pid: process.pid, startedAt, buildMtime: installed.buildMtime } }).server;
+  const seats: SeatBuild[] = [];
+  try {
+    for (const { marker, live } of await readAllTransportMarkers()) {
+      if (!live) continue;
+      seats.push(seatBuildOf({ agentId: marker.agentId, marker, installed, ps: psReader, server: null }));
+    }
+  } catch {
+    /* an unreadable transports dir yields no seats — an empty list, not a healthy fleet */
+  }
+  const toIso = (ms: number | null) => (ms === null ? null : new Date(ms).toISOString());
+  return {
+    installed: { module: installed.module, hookPath: installed.hookPath, hookMtime: toIso(installed.hookMtime), buildMtime: toIso(installed.buildMtime) },
+    answering,
+    seats,
+    note:
+      "seats[] states each live seat's PUSHER against the installed hook's own mtime (hooks/tmux-pusher.mjs, read directly), " +
+      "keyed by the --agent on the pusher's command line. The SERVER half is known only for the answering process " +
+      "(`answering`): servers carry no --agent, so another seat's server cannot be keyed from ps — ask that seat's own " +
+      "`status`, which states both halves for itself. A seat that reads current here and stale in its own status is half-restarted.",
+  };
+}
+
 export async function capabilitiesTool() {
   const id = resolveServerIdentity();
   const report = probeCapabilities({ module: id.path, versionLabel: id.version });
   try {
-    return { ...report, transport: await probeTransport() };
+    return { ...report, transport: await probeTransport(), seats: await seatBuilds() };
   } catch (e) {
     // A THROWN TRANSPORT PROBE IS NOT A BROKEN VERB. An unknown configured value
     // refuses at startup by design, and this verb is exactly what an operator

package/src/closing-line.ts

@@ -0,0 +1,85 @@
+/*
+ * ⟨q-fee7239f⟩ — A CLOSING LINE STATES AN ARTEFACT IT HAS NOT READ.
+ *
+ * Measured 2026-09-14 in one clock: #318 merged 18:12:42Z · "Remote branch
+ * deleted" posted 18:12:53.626Z · head_ref_deleted 18:13:27Z — the claim
+ * preceded its artefact by 33.4s; #319 by 61.7s. Then qa re-read
+ * `git ls-remote --heads origin` after #321 and withdrew the same line for
+ * FIVE merges (#309 #311 #315 #317 #321) where the remote was NEVER deleted:
+ * `gh --delete-branch` had not deleted the remote when the local delete
+ * errored, and the closing line reported THE FLAG IT PASSED rather than the
+ * remote it never read. A closing line already verifies the squash by content;
+ * the ref gets the same rule. The grammar admits exactly two forms for a
+ * deletion: a post-delete observation — `remote ref read: 0 refs at <ts>` —
+ * or the weaker `delete requested`, which claims no state. A closing that
+ * asserts deletion in any other wording is refused at the send, by the same
+ * check that requires a DONE to cite its PR, naming both forms.
+ *
+ * Dated adoption floor: qa's 18:36:30.939Z message — "From here every closing
+ * line reads the remote before claiming a delete". Closings at or before it
+ * are LISTED, never raised.
+ */
+export const CLOSING_GRAMMAR_ADOPTED_MS = 1789410990939; // 2026-09-14T18:36:30.939Z
+
+/** A merge-closing line: a `done` whose text says MERGED. */
+export const isMergeClosing = (text: string): boolean => /\bMERGED\b/.test(text);
+/**
+ * A deletion CLAIM is a statement, read by POSITION: the wording at the start
+ * of a sentence. The same words quoted mid-sentence — qa's own correction says
+ * `My "remote branch deleted" lines … were wrong` — are a mention, not a claim.
+ */
+export const DELETE_CLAIM = /(?:^|[.;!]\s+|\n\s*)(?:(?:Remote|Local and remote|Remote and local) (?:branch|ref) deleted|Deleted the remote (?:branch|ref))\b/;
+/** The observation form: what `git ls-remote --heads origin <branch>` returned, and when. */
+export const REMOTE_READ = /remote ref read:\s*(\d+)\s*refs?\s+at\s+(\S+?)(?=[.;,)]?(?:\s|$))/i;
+/** The weaker form: a command was issued; the state is left unclaimed. */
+export const DELETE_REQUESTED = /\bdelete requested\b/i;
+export const ACCEPTED_FORMS = "`remote ref read: 0 refs at <ISO ts>` (an `ls-remote` observation taken AFTER the delete) or `delete requested` (a command issued; state unclaimed)";
+
+export type ClosingLine = {
+  merged: boolean;
+  claimsDelete: boolean;
+  form: "read" | "requested" | null;
+  read?: { refs: number; at: string };
+};
+export function closingLineOf(text: string): ClosingLine {
+  const merged = isMergeClosing(text);
+  const claimsDelete = DELETE_CLAIM.test(text);
+  const r = REMOTE_READ.exec(text);
+  const form: ClosingLine["form"] = r ? "read" : DELETE_REQUESTED.test(text) ? "requested" : null;
+  return { merged, claimsDelete, form, ...(r ? { read: { refs: Number(r[1]), at: r[2]! } } : {}) };
+}
+/** The refusal: a merge closing that asserts deletion without either accepted form. */
+export function checkClosingLine(text: string): { ok: true; closing: ClosingLine } | { ok: false; error: string; closing: ClosingLine } {
+  const closing = closingLineOf(text);
+  if (closing.merged && closing.claimsDelete && closing.form === null) {
+    return {
+      ok: false,
+      closing,
+      error:
+        `a merge-closing line asserts a branch deletion it has not shown it read — "Remote branch deleted" reports a flag passed, not a remote observed (2 of 2 measured were premature, 5 of 7 were false). ` +
+        `State the deletion in one of the two accepted forms: ${ACCEPTED_FORMS}.`,
+    };
+  }
+  return { ok: true, closing };
+}
+
+export type Closing = { pr: number | null; from: string; ts: number; claimsDelete: boolean; form: ClosingLine["form"]; beforeAdoption: boolean };
+/** Every merge closing in a log, judged; `beforeAdoption` for those at or before the floor. */
+export function closingsIn(logText: string, floorMs: number = CLOSING_GRAMMAR_ADOPTED_MS): Closing[] {
+  const out: Closing[] = [];
+  for (const l of logText.split("\n")) {
+    if (!l.trim()) continue;
+    let o: { ts?: number; from?: string; text?: string; record?: { type?: string; cites?: { ref?: string }[] } };
+    try { o = JSON.parse(l); } catch { continue; }
+    if (o.record?.type !== "done") continue;
+    const text = String(o.text ?? "");
+    const c = closingLineOf(text);
+    if (!c.merged) continue;
+    const cited = (o.record.cites ?? []).map((x) => (String(x?.ref ?? "").match(/#(\d+)/) ?? [])[1]).find(Boolean);
+    const inText = (text.match(/MERGED[^\n]*?#(\d+)/) ?? [])[1];
+    const pr = cited ?? inText;
+    const ts = Number(o.ts ?? 0);
+    out.push({ pr: pr ? Number(pr) : null, from: String(o.from ?? ""), ts, claimsDelete: c.claimsDelete, form: c.form, beforeAdoption: ts <= floorMs });
+  }
+  return out.sort((a, b) => a.ts - b.ts);
+}

package/src/commit-cite.ts

@@ -0,0 +1,58 @@
+/**
+ * ⟨q-cc0819dc⟩ — A `done` MAY CITE A COMMIT WHEN THE WORK HAS NO PR BY RULE.
+ *
+ * Docs-direct work (queue curation, canon, board moves) is pushed straight to the shared
+ * branch by policy; the `done` gate demanded a `{kind:'pr'}` cite, so the compliant path did
+ * not exist and the aide downgraded to `fyi` (2026-09-12 15:50). The fix accepts a commit
+ * cite — and only a commit that is REAL: a fabricated sha must not become a citable DONE.
+ *
+ * What "real" means here, stated so the ancestry call below is not mistaken for a merge test:
+ *   is this exact commit object reachable from origin/main in `repo`? A docs-direct push puts
+ *   THE COMMIT ITSELF on the shared branch, so reachability is the right question for it — this
+ *   is not "was this branch's work squashed in", which `--is-ancestor` cannot answer
+ *   (docs/LANDEDNESS.md); a squash-merged PR is cited by its PR, never by its branch sha.
+ *
+ * Full 40-hex only, REFUSED rather than normalised: a prefix is a claim about a sha the
+ * joiners (verdict/landing/closure readers) compare in full; normalising here would write a
+ * sha the sender never saw. No network: one local `git` in `repo`, which the caller passes
+ * because the send path has no repository of its own.
+ */
+import { execFileSync } from "node:child_process";
+
+export const FULL_SHA = /^[0-9a-f]{40}$/;
+export const SHARED_BRANCH_CANDIDATES = ["origin/main", "origin/master"];
+
+export type CommitCiteVerdict =
+  | { ok: true; sha: string; branch: string }
+  | { ok: false; why: string };
+
+function git(repo: string, args: string[]): { status: number; out: string } {
+  try {
+    const out = execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return { status: 0, out: out.trim() };
+  } catch (e) {
+    return { status: Number((e as { status?: number }).status ?? 1), out: "" };
+  }
+}
+
+/** Verify one commit cite against the shared branch of `repo`. */
+export function verifyCommitCite(ref: string, repo: string | undefined): CommitCiteVerdict {
+  const sha = String(ref ?? "").trim();
+  if (!FULL_SHA.test(sha)) {
+    return { ok: false, why: `commit cite '${sha}' is not a full 40-hex sha — refused, not normalised: a prefix is a claim the joiners compare in full` };
+  }
+  if (!repo) {
+    return { ok: false, why: `commit cite ${sha.slice(0, 7)} cannot be verified without \`repo\` — pass the repository whose origin/main carries it (no network is used)` };
+  }
+  if (git(repo, ["rev-parse", "--verify", "--quiet", `${sha}^{commit}`]).status !== 0) {
+    return { ok: false, why: `commit ${sha.slice(0, 7)} does not exist in ${repo} — a sha the repository has never seen cannot be a citable DONE` };
+  }
+  for (const branch of SHARED_BRANCH_CANDIDATES) {
+    if (git(repo, ["rev-parse", "--verify", "--quiet", branch]).status !== 0) continue;
+    // Is the cited commit reachable from the shared branch? (the reachability question,
+    // asked of the commit object itself — see the header for why that is the right one here)
+    if (git(repo, ["merge-base", "--is-ancestor", sha, branch]).status === 0) return { ok: true, sha, branch };
+    return { ok: false, why: `commit ${sha.slice(0, 7)} exists but is not reachable from ${branch} — work that is done is on the shared branch; a commit that is not is not done` };
+  }
+  return { ok: false, why: `${repo} has no origin/main or origin/master to verify commit ${sha.slice(0, 7)} against — fetch the shared branch first` };
+}