agent-coord-mcp 0.26.19 → 0.26.21

package/src/tools/registry.ts

@@ -1,4 +1,5 @@
 import { detachAgentTool } from "./transport.js";
+import { isLocallyProbeable, isRemoteTmuxKind, targetOf } from "../transports/index.js";
 import { readAway, secondCoordinatorRefusal } from "./away.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
@@ -419,6 +420,36 @@ export async function listAgentsTool() {
   return { agents, evicted, proseOnly };
 }
 
+/**
+ * EVERY marker on disk, READ-ONLY.
+ *
+ * `loadLiveTransports` below deletes any marker it judges not-live, which is
+ * right for the delivery paths that own that garbage collection and WRONG for a
+ * diagnostic: `capabilities` must be able to describe the fleet without changing
+ * it. Using the reaping loader from a read-only verb made a mixed-fleet check
+ * delete the very marker it was reporting (caught by its own test — the second
+ * disagreeing agent vanished between write and read).
+ *
+ * Liveness is reported per marker rather than filtered on, because a STALE marker
+ * naming a different transport is more alarming than a live one, not less: it is
+ * a seat that may come back on the wrong transport. Filtering it out would make
+ * the remote kind — whose liveness is heartbeat-based and therefore absent
+ * without a registry entry — systematically invisible to this check.
+ */
+export async function readAllTransportMarkers(): Promise<
+  { marker: TransportMarker; live: boolean }[]
+> {
+  const out: { marker: TransportMarker; live: boolean }[] = [];
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+  const now = Date.now();
+  for (const fname of await listTransportFiles()) {
+    const marker = await readJson<TransportMarker | null>(path.join(TRANSPORT_DIR, fname), null);
+    if (!marker) continue; // unparseable: nothing to attribute, and not ours to delete
+    out.push({ marker, live: isMarkerLive(marker, reg, now) });
+  }
+  return out;
+}
+
 export async function loadLiveTransports(): Promise<Map<string, TransportMarker>> {
   const out = new Map<string, TransportMarker>();
   const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
@@ -439,7 +470,7 @@ export async function loadLiveTransports(): Promise<Map<string, TransportMarker>
 // remote markers (tmux-push-remote, pid 0 on a foreign host) can't be — so we
 // trust the registry heartbeat the remote pusher refreshes (within STALE_MS).
 export function isMarkerLive(marker: TransportMarker, reg: AgentRegistry, now: number): boolean {
-  if (marker.transport === "tmux-push-remote") {
+  if (isRemoteTmuxKind(marker.transport)) {
     const entry = reg[marker.agentId];
     return !!entry && now - entry.lastHeartbeat < STALE_MS;
   }
@@ -523,13 +554,13 @@ export async function liveClaimEvidence(agentId: string, now: number): Promise<C
   if (marker && isMarkerLive(marker, reg, now)) {
     markerLive = true;
     reasons.push(
-      `live ${marker.transport} transport (pid ${marker.pid}${marker.tmuxTarget ? `, pane ${marker.tmuxTarget}` : ""})`,
+      `live ${marker.transport} transport (pid ${marker.pid}${targetOf(marker) ? `, pane ${targetOf(marker)}` : ""})`,
     );
     if (
-      marker.transport === "tmux-push" &&
-      marker.tmuxTarget &&
+      isLocallyProbeable(marker.transport) &&
+      targetOf(marker) &&
       process.env.TMUX_PANE &&
-      marker.tmuxTarget === process.env.TMUX_PANE
+      targetOf(marker) === process.env.TMUX_PANE
     ) {
       samePane = true;
     }

package/src/tools/shared.ts

@@ -88,42 +88,18 @@ export type AgentEntry = {
   proseOnly?: { since: number; reason?: string };
 };
 
-export type TransportMarker = {
-  agentId: string;
-  transport: string;
-  pid: number;
-  tmuxTarget?: string;
-  since: number;
-  // Remote pushers run on a different machine; the local pid is meaningless,
-  // so we tag the host and use heartbeat-based liveness instead of pidAlive.
-  host?: string;
-  // mtime of the pusher script the daemon loaded into memory at spawn time
-  // (epoch ms). When the on-disk script is upgraded but the daemon isn't
-  // restarted, doctor() compares this to the current mtime to flag a stale
-  // pusher — the class of bug that silently dropped /clear /compact in v0.8.1.
-  // Absent on markers written by older versions (treated as "unknown, skip").
-  scriptMtime?: number;
-  // Build identity (newest dist mtime, sampled at that server's module load)
-  // of the MCP server whose attach_agent stamped this marker. A marker
-  // stamped by a server predating the current on-disk build was written by
-  // attach/stamp logic the rebuild replaced — doctor's provenance check flags
-  // it for a session restart + re-attach. Absent on markers written by older
-  // versions (treated as "unknown, skip", deliberately mirroring scriptMtime).
-  serverBuildMtime?: number;
-  // Does this transport carry ROOM traffic, or DMs only?
-  //
-  // A pusher started with `--no-room` delivers inbox messages and nothing
-  // else, and until this field existed the marker looked identical to a full
-  // one — so `status` said `attached: true` and an agent sat with its room
-  // feed off while every reading said healthy. That is how worker-2 missed
-  // its channel traffic.
-  //
-  // ABSENT MEANS UNKNOWN, NEVER "ON" — deliberately mirroring scriptMtime and
-  // serverBuildMtime above. A marker from an older pusher cannot tell us, and
-  // reporting an unasked question as full capability is the defect this field
-  // exists to remove.
-  rooms?: boolean;
-};
+/**
+ * THE MARKER TYPE NOW LIVES IN THE SEAM, and is re-exported here so the dozens
+ * of `from "./shared.js"` imports keep working.
+ *
+ * It was defined here, and the transport extraction gave it a second definition
+ * in `transports/types.ts` — two structurally-similar types that a consumer
+ * could satisfy while missing a field, which is the duplication this task exists
+ * to remove rather than double. One definition, one home: the transport layer,
+ * which is what the field describes. The nine fields and their comments moved
+ * with it verbatim, including `target`'s dual-write rule.
+ */
+export type { TransportMarker } from "../transports/types.js";
 
 /**
  * How to REPORT a transport's room capability.

package/src/tools/stall.ts

@@ -15,6 +15,7 @@
  * from "nothing ran". A check that only speaks when it fires cannot be told from
  * a broken one.
  */
+import { isLocallyProbeable } from "../transports/index.js";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import path from "node:path";
@@ -311,7 +312,7 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
       // agent with no transport, or a REMOTE one where the heartbeat genuinely
       // is the liveness mechanism, still HITs on a dead heartbeat.
       const marker = liveTransports.get(agentId);
-      if (age > limit && marker && marker.transport === "tmux-push") {
+      if (age > limit && marker && isLocallyProbeable(marker.transport)) {
         unmeasurable.push({
           agentId,
           value: marker.transport,

package/src/tools/transport.ts

@@ -1,4 +1,16 @@
 import { loadLiveTransports, isMarkerLive, isPidAlive } from "./registry.js";
+import {
+  TMUX_PUSH,
+  registerTmuxHost,
+  type TmuxHost,
+  isLocallyProbeable,
+  isTmuxKind,
+  paneExists,
+  probePane,
+  tmuxVersion,
+  targetOf,
+  tmuxAvailable,
+} from "../transports/index.js";
 import { newestMtimeUnder, onDiskBuildMtime, onDiskSourceMtime, SERVER_BUILD_MTIME, SERVER_BUILD_SHA, BUILD_DIR } from "../build.js";
 import { prefixOf, prefixVerdict } from "../prefix.js";
 import { execFileSync } from "node:child_process";
@@ -119,17 +131,11 @@ export async function pingTool(args: { from: string; to: string; echo?: boolean
   let paneAlive: boolean | undefined;
   if (marker) {
     transportLive = isMarkerLive(marker, reg, now);
-    if (transportLive && marker.transport === "tmux-push" && marker.tmuxTarget) {
+    if (transportLive && isLocallyProbeable(marker.transport) && targetOf(marker)) {
       // The pusher can outlive its pane (agent window closed) — probe the pane.
-      // `has-session` VALIDATES THE TARGET; `display-message -p -t <target> "ok"`
-      // DOES NOT — tmux exits 0 for any target, including a pane killed a moment
-      // ago, so the probe had ZERO discriminating power and reported every dead
-      // pane alive. Pinned to the BEHAVIOUR, not a version: measured identical on
-      // tmux 3.6b and 3.7b, and a version-pinned claim rots on the next upgrade.
-      // Positive control, both directions: bogus target -> has-session exit 1,
-      // display-message exit 0; live pane -> both exit 0.
-      const probe = spawnSync("tmux", ["has-session", "-t", marker.tmuxTarget]);
-      paneAlive = probe.status === 0;
+      // Why `has-session` and not `display-message`, with the positive control
+      // both ways, is documented once on `paneExists`.
+      paneAlive = paneExists(targetOf(marker)!);
     }
   }
 
@@ -146,7 +152,7 @@ export async function pingTool(args: { from: string; to: string; echo?: boolean
   // same shape as `stall_clock_status` before Task 13.1. A REMOTE pusher, or
   // an agent with no probeable marker at all, has no pid to fall back on —
   // there heartbeat genuinely IS the liveness mechanism, unchanged.
-  const heartbeatIsValidSignal = !marker || marker.transport !== "tmux-push";
+  const heartbeatIsValidSignal = !marker || !isLocallyProbeable(marker.transport);
   const alive = reachable || (heartbeatIsValidSignal && heartbeatFresh);
 
   let echoSent = false;
@@ -196,7 +202,7 @@ export const CONTROL_COMMANDS = ["clear", "compact", "reload-skills"] as const;
 // Transports whose pusher can actually TYPE a slash command into a live CLI.
 // A control command is meaningless to a plain MCP poller, so send_command is
 // gated to agents currently attached over one of these.
-const TMUX_TRANSPORTS = new Set(["tmux-push", "tmux-push-remote"]);
+
 
 // Normalize "clear" / "/clear" / "  /Clear " → "clear"; null if not allowlisted.
 function normalizeControlCommand(raw: string): string | null {
@@ -208,7 +214,7 @@ function normalizeControlCommand(raw: string): string | null {
 async function liveTmuxTargets(): Promise<Map<string, TransportMarker>> {
   const all = await loadLiveTransports();
   const out = new Map<string, TransportMarker>();
-  for (const [id, m] of all) if (TMUX_TRANSPORTS.has(m.transport)) out.set(id, m);
+  for (const [id, m] of all) if (isTmuxKind(m.transport)) out.set(id, m);
   return out;
 }
 
@@ -645,19 +651,13 @@ export async function attachAgentTool(args: {
     };
   }
 
-  // Validate target exists.
-  // `has-session` VALIDATES THE TARGET; `display-message -p -t <target> "ok"`
-  // DOES NOT — tmux exits 0 for any target, including a pane killed a moment
-  // ago, so the probe had ZERO discriminating power and reported every dead
-  // pane alive. Pinned to the BEHAVIOUR, not a version: measured identical on
-  // tmux 3.6b and 3.7b, and a version-pinned claim rots on the next upgrade.
-  // Positive control, both directions: bogus target -> has-session exit 1,
-  // display-message exit 0; live pane -> both exit 0.
-  const probe = spawnSync("tmux", ["has-session", "-t", target]);
-  if (probe.status !== 0) {
+  // Validate target exists. The probe's discriminating power, and the control
+  // that proves it, are documented once on `paneExists`.
+  const targetProbe = probePane(target);
+  if (!targetProbe.exists) {
     return {
       ok: false,
-      error: `tmux target '${target}' not found: ${(probe.stderr ?? "").toString().trim()}`,
+      error: `tmux target '${target}' not found: ${targetProbe.stderr}`,
     };
   }
 
@@ -723,8 +723,14 @@ export async function attachAgentTool(args: {
   const scriptMtime = newestPusherSourceMtime();
   const marker: TransportMarker = {
     agentId: args.agentId,
-    transport: "tmux-push",
+    transport: TMUX_PUSH,
     pid,
+    // DUAL-WRITTEN, and the duplication is the point. `target` is what every
+    // consumer now reads (`targetOf`); `tmuxTarget` is what the code a merge
+    // revert restores reads. Writing only the new field would leave markers the
+    // old server cannot parse, and that failure does not degrade gracefully —
+    // it silences every attached lane at once.
+    target,
     tmuxTarget: target,
     since: Date.now(),
     scriptMtime,
@@ -749,7 +755,7 @@ export async function attachAgentTool(args: {
   return {
     ok: true,
     agentId: args.agentId,
-    transport: "tmux-push",
+    transport: TMUX_PUSH,
     tmuxTarget: target,
     pid,
     log,
@@ -1171,6 +1177,53 @@ async function scanStaleLocks(olderThanMs: number, now: number): Promise<{ path:
   return out;
 }
 
+/* ── wiring the seam's TMUX HOST (Phase 5.4 Task 3) ─────────────────────────── */
+
+/**
+ * The process-layer half of `TmuxTransport`, supplied by the module that owns
+ * pusher spawn, receipts and marker files.
+ *
+ * ⚠ SCOPE, STATED RATHER THAN IMPLIED: Task 3 puts the seam in the IDENTITY and
+ * DIAGNOSIS path — `capabilities` asks the live transport what it is, and the
+ * mixed-fleet check reads markers through it. DELIVERY STILL RUNS THROUGH THE
+ * EXISTING CODE PATHS. Task 2's gate was that nothing changes, and rerouting
+ * every push through a new object would change the thing most likely to break
+ * quietly. So the four delivery methods below THROW rather than no-op: a host
+ * that silently accepted a push and dropped it would be the one failure this
+ * fleet cannot observe, and an explicit throw is reachable only from code that
+ * has not been written yet.
+ */
+const TMUX_HOST: TmuxHost = {
+  attach: async () => {
+    throw new Error("TmuxTransport.attach is not the delivery path yet — call attachAgentTool (Phase 5.4 Task 3 wires identity only)");
+  },
+  detach: async () => {
+    throw new Error("TmuxTransport.detach is not the delivery path yet — call detachAgentTool");
+  },
+  push: async () => {
+    throw new Error("TmuxTransport.push is not the delivery path yet — delivery runs through the pusher process");
+  },
+  sendControl: async () => {
+    throw new Error("TmuxTransport.sendControl is not the delivery path yet — call sendCommandTool");
+  },
+  /**
+   * Is the pusher behind this marker still running? Reuses `isPusherProcess`,
+   * which checks the COMMAND of the pid rather than merely that a pid exists —
+   * a recycled pid belonging to something else is not a live pusher.
+   */
+  pusherAlive: (marker) => isPusherProcess(marker.pid),
+  killPusher: (marker) => {
+    try {
+      process.kill(marker.pid, "SIGTERM");
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+registerTmuxHost(TMUX_HOST);
+
 export const doctorSchema = {
   fix: z.boolean().optional(),
   maxFileBytes: z.number().int().positive().optional(),
@@ -1231,7 +1284,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       const file = path.join(TRANSPORT_DIR, fname);
       const marker = await readJson<TransportMarker | null>(file, null);
       if (!marker || !isMarkerLive(marker, reg, now)) continue;
-      if (marker.transport !== "tmux-push") continue; // remote = can't verify (documented limit: can't stat another host)
+      if (!isLocallyProbeable(marker.transport)) continue; // remote = can't verify (documented limit: can't stat another host)
       if (marker.scriptMtime === undefined) {
         // ABSENCE IS NOT EXEMPTION. The field's own writer once dropped it,
         // and the silent skip here meant the check was disabled by the very
@@ -1339,7 +1392,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       const file = path.join(TRANSPORT_DIR, fname);
       const marker = await readJson<TransportMarker | null>(file, null);
       if (!marker || !isMarkerLive(marker, reg, now)) continue;
-      if (marker.transport !== "tmux-push") continue; // remote = can't verify (documented limit: can't stat another host)
+      if (!isLocallyProbeable(marker.transport)) continue; // remote = can't verify (documented limit: can't stat another host)
       if (marker.serverBuildMtime === undefined) {
         // ABSENCE IS NOT EXEMPTION — flipped in the same commit as the
         // scriptMtime absence above, so the two checks can never disagree
@@ -1434,7 +1487,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       const file = path.join(TRANSPORT_DIR, fname);
       const marker = await readJson<TransportMarker | null>(file, null);
       if (!marker || !isMarkerLive(marker, reg, now)) continue;
-      if (marker.transport !== "tmux-push") continue; // remote: the script lives on another host
+      if (!isLocallyProbeable(marker.transport)) continue; // remote: the script lives on another host
       const { scriptMtime, serverBuildMtime, agentId } = marker;
       if (scriptMtime === undefined || serverBuildMtime === undefined || onDiskScript === undefined || onDiskServer === undefined) {
         // A pane missing either stamp cannot be classified. Saying so is the
@@ -1475,20 +1528,20 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   {
     // Without a tmux binary we can't tell "wedged" from "can't probe" — skip
     // rather than flag every local marker as dead.
-    const tmuxAvailable = spawnSync("tmux", ["-V"]).status === 0;
+    const tmuxIsAvailable = tmuxAvailable();
     const wedged: { agentId: string; pid: number; file: string; target: string; isPusher: boolean }[] = [];
-    if (tmuxAvailable) {
+    if (tmuxIsAvailable) {
       for (const fname of await listTransportFiles()) {
         const file = path.join(TRANSPORT_DIR, fname);
         const marker = await readJson<TransportMarker | null>(file, null);
         if (!marker || !isMarkerLive(marker, reg, now)) continue;
-        if (marker.transport !== "tmux-push") continue; // remote = no local pane to probe
+        if (!isLocallyProbeable(marker.transport)) continue; // remote = no local pane to probe
         if (!marker.tmuxTarget) continue; // no target recorded, can't probe
         // has-session actually validates the target and fails on a dead
         // pane/session; `display-message -p -t <target> <literal>` does NOT
         // (tmux 3.6b exits 0 for any target, even a just-killed one, when
         // the format string has no #{...} needing that target resolved).
-        const probe = spawnSync("tmux", ["has-session", "-t", marker.tmuxTarget]);
+        const probe = { status: paneExists(targetOf(marker)!) ? 0 : 1 };
         if (probe.status === 0) continue; // pane alive
         // The marker's pid being alive does not make it OUR pid — see
         // isPusherProcess. Record the verdict now so `fix` only ever signals
@@ -1523,7 +1576,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       level: wedged.length ? "warn" : "ok",
       detail: wedged.length
         ? `${wedged.length} local pusher(s) alive (pid) but their tmux pane is gone — looks attached, delivers nothing. ${fix ? "Reaped (SIGTERM + marker cleared)." : "Run doctor with fix:true to SIGTERM and clear the marker."}`
-        : tmuxAvailable
+        : tmuxIsAvailable
           ? "no wedged local pushers (pid-alive, pane-dead)"
           : "tmux not available — skipped wedged-pusher pane probe",
       fixable: true,
@@ -1768,9 +1821,8 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
     // Without a tmux binary we cannot probe a pane at all — every stale
     // agent is reported as an orphan candidate rather than silently split,
     // same posture `wedged-local-pushers` takes.
-    const tmuxAvailable = spawnSync("tmux", ["-V"]).status === 0;
-    const paneAlive = (target: string): boolean =>
-      tmuxAvailable && spawnSync("tmux", ["has-session", "-t", target]).status === 0;
+    const tmuxIsAvailable = tmuxAvailable();
+    const paneAlive = (target: string): boolean => tmuxIsAvailable && paneExists(target);
 
     const paneConfirmed: string[] = [];
     const orphans: string[] = [];
@@ -1779,8 +1831,9 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       if (now - a.lastHeartbeat <= EVICT_MS) continue;
       const age = `${Math.floor((now - a.lastHeartbeat) / 3600000)}h`;
       const marker = markerByAgent.get(id);
-      if (marker?.transport === "tmux-push" && marker.tmuxTarget && paneAlive(marker.tmuxTarget)) {
-        paneConfirmed.push(`${id} (${age}, pane '${marker.tmuxTarget}' still current)`);
+      const markerTarget = marker ? targetOf(marker) : undefined;
+      if (isLocallyProbeable(marker?.transport) && markerTarget && paneAlive(markerTarget)) {
+        paneConfirmed.push(`${id} (${age}, pane '${markerTarget}' still current)`);
       } else {
         orphans.push(`${id} (${age})`);
       }
@@ -1808,7 +1861,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       level: orphans.length ? "warn" : "ok",
       detail: orphans.length
         ? `${orphans.length} stale agent(s) have no live tmux pane behind them — permanent, will not clear on their own (unregister or let eviction drop them)`
-        : tmuxAvailable
+        : tmuxIsAvailable
           ? `no orphans among ${stale.length} stale agent(s)${stale.length ? " — all pane-confirmed current" : ""}`
           : "tmux not available — could not distinguish orphans from pane-confirmed stale agents",
       fixable: false,
@@ -2026,8 +2079,8 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   // identity is walk-up-to-.git + rev-parse (kit monorepo root); omitted
   // entirely when there is no checkout — never invented.
   {
-    const tmuxProbe = spawnSync("tmux", ["-V"]);
-    const tmuxOk = tmuxProbe.status === 0;
+    const tmuxReported = tmuxVersion();
+    const tmuxOk = tmuxReported !== undefined;
     const ident = resolveServerIdentity();
     const loc = ident.branch && ident.sha
       ? `path=${ident.path} version=${ident.version} ${ident.branch}@${ident.sha.slice(0, 12)}`
@@ -2045,7 +2098,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       check: "environment",
       level: tmuxOk ? "ok" : "warn",
       detail: tmuxOk
-        ? `root=${ROOT}; node=${process.execPath}; ${loc}; tmux=${(tmuxProbe.stdout ?? "").toString().trim() || "present"}`
+        ? `root=${ROOT}; node=${process.execPath}; ${loc}; tmux=${tmuxReported || "present"}`
         : `root=${ROOT}; node=${process.execPath}; ${loc}; tmux NOT on PATH — the tmux-push transport will not work`,
       fixable: false,
       items,

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;
+}