agent-coord-mcp 0.26.20 → 0.26.21

package/src/tools/records.ts

@@ -15,6 +15,8 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
+
+import { treeProvenance } from "./tree-provenance.js";
 import {
   parseWorkDoc,
   renderWorkDoc,
@@ -34,6 +36,8 @@ import {
   type DoneEntry,
 } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
+import { ROOT } from "../store.js";
+import { verdictsFor, gatedAt } from "../gated-head.js";
 import { boardRefFor, classifyBoardRef } from "./board-ref.js";
 import { haltState, isInFlightStatus } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
@@ -387,8 +391,15 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
     };
   }
   const repo = args.repo ?? process.cwd();
+  // ⛔⛆ SAY WHICH TREE THIS ANSWER CAME FROM (⟨q-c1af2db3⟩). This verb reads
+  // `docs/QUEUE.md` out of a working tree nobody owns, and a stale one produced
+  // a confidently wrong routing decision in both directions inside ten minutes —
+  // a row ruled un-claimable from a stale file, and a worker told to hold on a
+  // row that was already split. The answer was well-formed and said nothing
+  // about its source, which is what made it invisible.
+  const tree = treeProvenance(repo);
   const q = readDoc(repo, QUEUE_DOC);
-  if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'` };
+  if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'`, tree };
   const items = queueItemsOf(q.doc);
   // The seam's own count of unticked rows — the number every axis must add back
   // up to. Taken BEFORE any exclusion so it cannot inherit one.
@@ -533,6 +544,10 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   // the severity finding one file over. Say the axis is uninformative instead.
   const undiscriminating = silent.length === open.length && open.length > 1;
   return {
+    // ⛔ THE PROVENANCE TRAVELS WITH THE ANSWER, not in a second call. A
+    // routing answer whose tree is unnamed is the defect this row exists for.
+    tree,
+    ...(tree.warning ? { staleWarning: tree.warning } : {}),
     ok: true as const,
     project: args.project,
     open: open.length,
@@ -822,7 +837,29 @@ export const landSchema = {
   result: z.string().optional(),
 };
 
-export async function landTool(args: {
+/**
+ * What the recording step needs to know about a merge: which head actually
+ * landed, and when. Injected so the report is provable without the network.
+ */
+export type MergeFacts = { headRefOid: string; mergedAt: string } | null;
+export type ReadMergeFacts = (repo: string, n: string) => MergeFacts;
+const ghMergeFacts: ReadMergeFacts = (repo, n) => {
+  try {
+    const out = execFileSync("gh", ["pr", "view", n, "--json", "headRefOid,mergedAt"], {
+      cwd: repo,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const j = JSON.parse(out) as { headRefOid?: string; mergedAt?: string };
+    if (!j.headRefOid || !j.mergedAt) return null;
+    return { headRefOid: String(j.headRefOid), mergedAt: String(j.mergedAt) };
+  } catch {
+    return null;
+  }
+};
+
+export async function landTool(
+  args: {
   project: string;
   pr: string;
   queueItemId?: string;
@@ -830,7 +867,10 @@ export async function landTool(args: {
   base?: string;
   write?: boolean;
   result?: string;
-}) {
+},
+  readMergeFacts: ReadMergeFacts = ghMergeFacts,
+  readVerdictLog: ReadVerdictLog = roomLog,
+) {
   const repo = args.repo ?? process.cwd();
   const base = args.base ?? "main";
   const n = prNumber(args.pr);
@@ -945,8 +985,41 @@ export async function landTool(args: {
   const bareRef = !/[\w.-]+\/[\w.-]+#\d+/.test(String(args.pr));
   const summary = originalText !== null ? summarize(originalText) : null;
 
+  /*
+   * ⛔⛆⛆ THE ROW'S ID LEADS THE ENTRY, BECAUSE A TRUNCATED HEADLINE CANNOT CARRY IT
+   * — `⟨q-d046204d⟩`.
+   *
+   * `summarize` cuts at 96 characters and appends `…`. The sigil was never omitted
+   * from these entries: IT WAS CUT, because in the row it sits later than the
+   * truncation point. So the entry came out with a PERFECT `ref` slot and a `text`
+   * that names no row — and `closingRefs` needs BOTH halves, so the row reads
+   * untied and `main` goes red. `⟨q-c1af2db3⟩` at `17a9ffc` is that, measured.
+   *
+   * ⭐⭐ THE FIX IS POSITION, NOT LENGTH. Putting the id BEFORE the summary takes it
+   * out of the truncated region BY CONSTRUCTION, so it survives any headline length
+   * — where raising `max` only moves the cliff. The row is explicit that "write
+   * longer headlines" is not an acceptable fix, and it is right: a length that is
+   * enough today is a truncation tomorrow.
+   *
+   * ✅ AND THE CONSUMER ALREADY EXPECTS THIS SPELLING. `doneRecordsDelivery` strips
+   * a leading `⟨q-…⟩` before comparing, and says why: "an entry written as `⟨id⟩
+   * <summary>` and one written as `<summary>` agree". So the composed-summary arm
+   * keeps matching and this needed no change there.
+   *
+   * ⚠ THIS IS NOT THE ARM `⟨q-4a1e70c5⟩` REMOVED, and the difference is the whole
+   * reason this is safe. That arm INFERRED delivery from a sigil appearing ANYWHERE
+   * in an entry — a reader-side guess that produced eleven false positives, because
+   * this repo's canon requires entries to cite item ids for other reasons. This
+   * writes the id in a DETERMINISTIC LEADING POSITION so the tie can be read. It
+   * infers nothing, and re-reading a sigil as "delivered" is still wrong.
+   *
+   * The id is the ITEM's, taken from the record rather than re-derived: `target` is
+   * non-null whenever `summary` is, since the summary comes from its text.
+   */
   const doneLine =
-    already || !summary ? null : `- [x] ${summary} — ${args.pr} · ${new Date().toISOString().slice(0, 10)}`;
+    already || !summary || !target
+      ? null
+      : `- [x] ⟨${target.id}⟩ ${summary} — ${args.pr} · ${new Date().toISOString().slice(0, 10)}`;
 
   // APPEND TO DONE.md — the half this verb exists for.
   //
@@ -1034,12 +1107,53 @@ export async function landTool(args: {
     }
   }
 
+  /*
+   * ⛔⛆ SECOND LINE: WAS THE THING MERGED THE THING GATED? (kit#268, ⟨q-6a4f0c38⟩)
+   *
+   * `merge` refuses this BEFORE the fact and is the control that prevents. This
+   * one runs after, and its job is different: it is how the fleet LEARNS a
+   * crossing happened anyway — through a merge done by hand, by `gh` directly,
+   * or by a seat that never called the verb.
+   *
+   * It REPORTS and never refuses. A closure is not the right place to litigate a
+   * merge that already happened: the verdict is QA's artefact, the merge may have
+   * been someone else's, and blocking the record would leave the work landed and
+   * unrecorded — strictly worse than landed and recorded with a flag on it.
+   *
+   * ⚠ AND IT SAYS SO WHEN IT COULD NOT LOOK. An omitted field reads as "fine".
+   */
+  const gatedHead = (() => {
+    const mf = readMergeFacts(repo, n);
+    if (!mf) return { checked: false as const, note: `could not read #${n}'s merged head and merge time — whether the merged head was gated is UNKNOWN, not clean.` };
+    const log = readVerdictLog(args.project);
+    if (log === null) return { checked: false as const, note: `could not read the verdict log for '${args.project}' — whether #${n}'s merged head was gated is UNKNOWN, not clean.` };
+    const at = Date.parse(mf.mergedAt);
+    if (!Number.isFinite(at)) return { checked: false as const, note: `#${n} reports an unparseable mergedAt ('${mf.mergedAt}') — cannot place the merge in time.` };
+    const { verdicts, unparsed } = verdictsFor(log, n);
+    const a = gatedAt(verdicts, mf.headRefOid, at);
+    if (a.gated) {
+      return { checked: true as const, gated: true as const, head: mf.headRefOid.slice(0, 8), by: { from: a.by.from, sha: a.by.head.slice(0, 8) } };
+    }
+    return {
+      checked: true as const,
+      gated: false as const,
+      head: mf.headRefOid.slice(0, 8),
+      reason: a.reason,
+      gatedInstead: (a.crossed ?? []).map((c) => c.gatedSha.slice(0, 8)),
+      note:
+        `UNGATED MERGE RECORDED: #${n} merged ${mf.headRefOid.slice(0, 8)} and ${a.reason}. ` +
+        `The record is written — this is a report, not a refusal — but the merge was not covered by a verdict when it happened.` +
+        (unparsed ? ` (${unparsed} log line(s) unreadable and skipped.)` : ""),
+    };
+  })();
+
   return {
     ok: true as const,
     project: args.project,
     pr: `#${n}`,
     comparedAgainst: ref,
     landedIn: landedIn.slice(0, 8),
+    gatedHead,
     // THE ABSORBING WRITER LEARNS IT ABSORBED SOMETHING. The aide's
     // diff-before-rename guard REFUSES on a foreign change; this REPORTS one it
     // fixed, so a foreign row cannot pass silently in either direction.
@@ -1151,13 +1265,15 @@ export type PrFacts = {
   state: string;
   mergeable: string;
   checks: unknown[];
+  /** The branch tip RIGHT NOW — what would actually be merged (⟨q-6a4f0c38⟩). */
+  headRefOid?: string;
   /** Unified diff of the PR, for the ticked-box audit. */
   diff?: string;
   /** Everything that will survive the merge as a citation: title + commit subjects + body. */
   citationText?: string;
 };
 const ghFacts = (repo: string, n: string): PrFacts => {
-  const out = execFileSync("gh", ["pr", "view", n, "--json", "state,mergeable,statusCheckRollup"], {
+  const out = execFileSync("gh", ["pr", "view", n, "--json", "state,mergeable,statusCheckRollup,headRefOid"], {
     cwd: repo,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"],
@@ -1181,6 +1297,7 @@ const ghFacts = (repo: string, n: string): PrFacts => {
   return {
     state: String(j.state ?? ""),
     mergeable: String(j.mergeable ?? ""),
+    headRefOid: String(j.headRefOid ?? ""),
     checks: (j.statusCheckRollup as unknown[]) ?? [],
     diff: gh(["pr", "diff", n]),
     citationText: [String(meta.title ?? ""), subjects, String(meta.body ?? "")].join("\n"),
@@ -1206,10 +1323,28 @@ const ghMerge: DoMerge = (repo, n, method) => {
   });
 };
 
+/**
+ * The room log, injected for the same reason `doMerge` is: a test must be able to
+ * drive every refusal branch without this host's ~/agent-coord.
+ *
+ * Returns null when the log cannot be read — distinct from "" (read, and empty),
+ * because "no verdicts recorded" and "could not look" are different answers and
+ * only one of them is safe to merge on.
+ */
+export type ReadVerdictLog = (project: string) => string | null;
+const roomLog: ReadVerdictLog = (project) => {
+  try {
+    return readFileSync(path.join(ROOT, "rooms", `${project}.jsonl`), "utf8");
+  } catch {
+    return null;
+  }
+};
+
 export async function mergeTool(
   args: { project: string; pr: string; repo?: string; method?: string; write?: boolean },
   facts: (repo: string, n: string) => PrFacts = ghFacts,
   doMerge: DoMerge = ghMerge,
+  readVerdictLog: ReadVerdictLog = roomLog,
 ) {
   const repo = args.repo ?? process.cwd();
   const n = prNumber(args.pr);
@@ -1318,8 +1453,55 @@ export async function mergeTool(
   if (f.mergeable === "CONFLICTING")
     return { ok: false as const, error: `#${n} is CONFLICTING with its base.`, verdict };
 
+  /*
+   * ⛔⛆ THE THING MERGED MUST BE THE THING GATED — kit#268, ⟨q-6a4f0c38⟩.
+   *
+   * A PASS was posted for `6051193` at 10:23:14Z; the merge ran 8 seconds later
+   * and took `1d6deab`, because the author force-pushed in between. Checks were
+   * green on BOTH heads, so every refusal above passed honestly. Nothing asked
+   * the only question that mattered: is the head in front of me the head the
+   * verdict named?
+   *
+   * THIS IS THE FIRST-LINE CONTROL because it PREVENTS. The recording step can
+   * only report afterwards. It sits before the dry-run return on purpose: a dry
+   * run must say it would refuse, or the preview disagrees with the act.
+   */
+  const head = f.headRefOid ?? "";
+  if (!head) {
+    return {
+      ok: false as const,
+      error: `could not read #${n}'s current head — NOT read, which is not the same as read and matching the verdict.`,
+      verdict,
+    };
+  }
+  const log = readVerdictLog(args.project);
+  if (log === null) {
+    return {
+      ok: false as const,
+      error:
+        `could not read the verdict log for project '${args.project}' — so whether #${n}'s head ${head.slice(0, 7)} ` +
+        `was ever gated is UNKNOWN, and unknown is not gated.`,
+      verdict,
+    };
+  }
+  const { verdicts, unparsed } = verdictsFor(log, n);
+  const gate = gatedAt(verdicts, head, Date.now());
+  if (!gate.gated) {
+    const named = (gate.crossed ?? []).map((c) => c.gatedSha.slice(0, 7)).join(", ");
+    return {
+      ok: false as const,
+      error:
+        `#${n}'s head is ${head.slice(0, 7)} and ${gate.reason}. ` +
+        (named ? `Gated instead: ${named}. ` : "") +
+        `Re-gate this head before merging — a PASS that must be re-issued is cheap, a merge nobody gated is not.` +
+        (unparsed ? ` (${unparsed} log line(s) unreadable and skipped.)` : ""),
+      verdict,
+      gatedHead: { head, gated: false as const, reason: gate.reason },
+    };
+  }
+
   if (!args.write)
-    return { ok: true as const, merged: false as const, verdict, note: `#${n} would merge: all ${checks.length} check(s) pass. Pass write:true to apply.` };
+    return { ok: true as const, merged: false as const, verdict, note: `#${n} would merge: all ${checks.length} check(s) pass, and head ${head.slice(0, 7)} is gated by a PASS from ${gate.by.from}. Pass write:true to apply.` };
 
   doMerge(repo, n, args.method ?? "squash");
   return { ok: true as const, merged: true as const, verdict };

package/src/tools/tree-provenance.ts

@@ -0,0 +1,136 @@
+/**
+ * ⟨q-c1af2db3⟩ — WHICH TREE DID THIS VERB JUST READ, AND HOW OLD IS IT?
+ *
+ * ⛔ THE BUG THIS EXISTS FOR ROUTED THE FLEET. `next_unblocked` reads
+ * `docs/QUEUE.md` out of whatever working tree it is handed, and that tree
+ * belongs to nobody: its freshness is a property of whoever last worked in it.
+ * Measured 2026-09-12 16:36 — the primary checkout sat FOUR commits behind
+ * `origin/main`, its `QUEUE.md` had zero hits for a tag committed six minutes
+ * earlier, and the verb returned the PRE-EDIT text as `next`.
+ *
+ * ⛆ AND THE HARM LANDED IN BOTH DIRECTIONS INSIDE TEN MINUTES: a row was ruled
+ * un-claimable from an observation that was actually a stale file, and a worker
+ * was told to hold on a row that was already split. ⭐ ***A true conclusion
+ * reached through an untrue reading is the shape, and here the INSTRUMENT
+ * supplied the untrue reading — the answer was well-formed, internally
+ * consistent, `accounting.reconciles` was TRUE, and nothing in it said which
+ * tree it read.***
+ *
+ * ⛔⛆⛆ THE TRAP THAT BREAKS THE OBVIOUS FIX, AND IT IS WHY THIS FETCHES:
+ *
+ *     a checkout that has not fetched CANNOT REPORT that it has not fetched.
+ *
+ * `git rev-list --left-right --count origin/main...HEAD` in an unfetched clone
+ * compares HEAD against a STALE `origin/main` ref and returns `0  0` — *"I am
+ * perfectly current"* — while the real remote has moved. Measured: HEAD
+ * `1cab5c2`, its own `origin/main` also `1cab5c2`, true `origin/main` `558365d`,
+ * three commits behind, reported as ZERO. ⭐⭐ ***A distance of `0` from an
+ * unfetched ref and a distance of `0` from a fetched one are BYTE-IDENTICAL and
+ * mean opposite things. That distinction is the whole point of this module: the
+ * ref is fetched IN THIS CALL, and when the fetch fails the answer is
+ * `"unknown"` and never `0`.***
+ *
+ * ⚠ AND FETCHING IS NOT THE FIX — that is the row's named anti-control.
+ * Fetching updates REFS; the verb reads the TREE, which is still stale
+ * afterwards. So a fetch only makes the staleness *legible*; the caller must
+ * still refuse or flag. This module reports; it never silently repairs, because
+ * making someone else's working tree current is a destructive write into a
+ * checkout a seat may be mid-work in.
+ */
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+export type TreeProvenance = {
+  /** The tree actually read, resolved — not the string the caller passed. */
+  path: string;
+  head: string | null;
+  /** The ref the distance is measured against, e.g. `origin/main`. */
+  base: string;
+  baseSha: string | null;
+  /**
+   * Commits the tree is behind `base`.
+   *
+   * ⛔ `"unknown"` WHEN THE REF COULD NOT BE FRESHENED IN THIS CALL. Never `0`
+   * in that case: `0` is a claim of currency and an unfetched ref cannot make it.
+   */
+  behind: number | "unknown";
+  /** Whether the ref this distance rests on was freshened in THIS call. */
+  fetched: boolean;
+  fetchError?: string;
+  dirty: boolean | "unknown";
+  /** True only when the tree is MEASURABLY behind a ref fetched in this call. */
+  stale: boolean;
+  /** Present whenever the answer cannot be trusted as current. */
+  warning?: string;
+};
+
+const run = (repo: string, args: string[]): string | null => {
+  try {
+    return execFileSync("git", args, {
+      cwd: repo,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 20_000,
+    }).trim();
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * What the caller needs to say out loud about the tree it just read.
+ *
+ * @param repo the working tree a verb was handed
+ * @param baseBranch the branch the tree should be current with
+ */
+export function treeProvenance(repo: string, baseBranch = "main"): TreeProvenance {
+  const resolved = run(repo, ["rev-parse", "--show-toplevel"]) ?? path.resolve(repo);
+  const base = `origin/${baseBranch}`;
+  const head = run(resolved, ["rev-parse", "HEAD"]);
+  const status = run(resolved, ["status", "--porcelain"]);
+
+  // ⛔ FETCH FIRST, AND THE ORDER IS THE POINT. Every number below is worthless
+  // if it rests on a ref the tree last updated at some unknown past moment.
+  const fetched = run(resolved, ["fetch", "--quiet", "origin", baseBranch]) !== null;
+
+  const out: TreeProvenance = {
+    path: resolved,
+    head,
+    base,
+    baseSha: null,
+    behind: "unknown",
+    fetched,
+    dirty: status === null ? "unknown" : status.length > 0,
+    stale: false,
+  };
+
+  if (!fetched) {
+    out.fetchError = `could not fetch origin/${baseBranch} — the distance cannot be computed`;
+    out.warning =
+      `TREE FRESHNESS UNKNOWN: ${resolved} could not reach origin/${baseBranch} in this call, so its ` +
+      `distance is UNKNOWN rather than 0. A checkout that has not fetched cannot report that it has not ` +
+      `fetched — an unfetched ref answers "0 behind" and means nothing.`;
+    return out;
+  }
+
+  out.baseSha = run(resolved, ["rev-parse", base]);
+  const counts = run(resolved, ["rev-list", "--left-right", "--count", `${base}...HEAD`]);
+  const behind = counts ? Number(counts.split(/\s+/)[0]) : NaN;
+  if (!Number.isFinite(behind)) {
+    out.warning = `TREE FRESHNESS UNKNOWN: could not count ${base}...HEAD in ${resolved}.`;
+    return out;
+  }
+
+  out.behind = behind;
+  out.stale = behind > 0;
+  if (out.stale) {
+    // ⚠ FETCHING DID NOT FIX THE TREE — it only made this sentence possible.
+    // The file the verb read is still the old one.
+    out.warning =
+      `STALE TREE: ${resolved} is ${behind} commit(s) behind ${base} (HEAD ${head?.slice(0, 7)}, ` +
+      `${base} ${out.baseSha?.slice(0, 7)}). The answer above was read from THAT tree's files, so a row ` +
+      `filed or amended on ${base} since is invisible here and a superseded row can be offered as current. ` +
+      `Fetching refreshed the REF, not the working tree.`;
+  }
+  return out;
+}