agent-coord-mcp 0.26.19 → 0.26.21

package/dist/transports/tmux.js

@@ -0,0 +1,140 @@
+/**
+ * THE TMUX TRANSPORT — every `tmux` shell-out in this package, in one file.
+ *
+ * Before this, `spawnSync("tmux", …)` appeared at 7 sites in `tools/transport.ts`
+ * and the `has-session` caveat below was written out TWICE, verbatim, at two of
+ * them. A rule duplicated in two comments is a rule that will be re-derived
+ * wrongly at the third site somebody adds.
+ *
+ * WHAT THIS FILE DOES NOT DO, on purpose: spawn or reap the pusher process,
+ * read receipts, or schedule reminders. Delivery is a second process for THIS
+ * transport and will not be for a socket one, so that machinery stays with the
+ * tools that own it and reaches this file through `TmuxHost` below. An interface
+ * that baked in a pusher could not host an implementation that has none.
+ */
+import { spawnSync } from "node:child_process";
+import { TMUX_PUSH, isLocallyProbeable, isTmuxKind, targetOf } from "./types.js";
+/** `tmux -V` — is tmux on this host at all? */
+export function tmuxAvailable() {
+    return spawnSync("tmux", ["-V"]).status === 0;
+}
+/**
+ * DOES THIS TARGET EXIST? The only tmux probe with discriminating power.
+ *
+ * `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 that probe had ZERO discriminating power and reported every dead pane
+ * alive. Pinned to the BEHAVIOUR, not a version: measured identical on tmux
+ * 3.6b, 3.7b. A version-pinned claim rots on the next upgrade.
+ *
+ * Positive control, both directions, re-run on tmux 3.7b while extracting this:
+ * bogus target `%99999` -> has-session exit 1, display-message exit 0; live pane
+ * `%8` -> both exit 0. The wrong probe is wrong in only one direction, which is
+ * why it survived: it never reports a live pane dead.
+ */
+export function paneExists(target) {
+    return spawnSync("tmux", ["has-session", "-t", target]).status === 0;
+}
+/**
+ * `has-session` with the failure text, for the one caller that reports it.
+ *
+ * `paneExists` is the boolean most sites want; attach quotes tmux's own stderr
+ * back to the user, and losing that text would make a refusal less useful while
+ * still typechecking — the exact class of silent regression this task guards.
+ */
+export function probePane(target) {
+    const probe = spawnSync("tmux", ["has-session", "-t", target]);
+    return { exists: probe.status === 0, stderr: (probe.stderr ?? "").toString().trim() };
+}
+/** `tmux -V` output, or undefined when tmux is absent. */
+export function tmuxVersion() {
+    const probe = spawnSync("tmux", ["-V"]);
+    if (probe.status !== 0)
+        return undefined;
+    return (probe.stdout ?? "").toString().trim() || undefined;
+}
+export class TmuxTransport {
+    kind;
+    #host;
+    constructor(host, kind = TMUX_PUSH) {
+        this.#host = host;
+        this.kind = kind;
+    }
+    available() {
+        return tmuxAvailable();
+    }
+    attach(args) {
+        return this.#host.attach(args);
+    }
+    detach(agentId) {
+        return this.#host.detach(agentId);
+    }
+    push(marker, text) {
+        return this.#host.push(marker, text);
+    }
+    sendControl(marker, cmd) {
+        return this.#host.sendControl(marker, cmd);
+    }
+    /**
+     * THREE ANSWERS, AND THE THIRD IS LOAD-BEARING.
+     *
+     * Each `unknown` below was previously a `continue` with a comment. The states
+     * are preserved exactly, because "we could not look" is not evidence of death
+     * and a reaper that cannot tell them apart kills live sessions:
+     *
+     * · not a tmux marker        -> unknown (this transport cannot speak for it)
+     * · remote (foreign host)    -> unknown (no local pane; heartbeat decides)
+     * · no target recorded       -> unknown (nothing to probe)
+     * · tmux missing on host     -> unknown (the instrument is absent, not the pane)
+     * · target absent            -> dead
+     * · pusher gone, pane alive  -> dead, and it says which half failed
+     */
+    async probe(marker) {
+        if (!isTmuxKind(marker.transport)) {
+            return { state: "unknown", reason: `transport "${marker.transport}" is not tmux` };
+        }
+        if (!isLocallyProbeable(marker.transport)) {
+            return {
+                state: "unknown",
+                reason: `${marker.transport} runs on another host${marker.host ? ` (${marker.host})` : ""} — no local pane to probe; liveness is heartbeat-based`,
+            };
+        }
+        const target = targetOf(marker);
+        if (!target)
+            return { state: "unknown", reason: "no target recorded on the marker" };
+        if (!tmuxAvailable())
+            return { state: "unknown", reason: "tmux is not available on this host" };
+        if (!paneExists(target))
+            return { state: "dead", reason: `pane ${target} does not exist` };
+        if (!this.#host.pusherAlive(marker)) {
+            return { state: "dead", reason: `pane ${target} is alive but its pusher (pid ${marker.pid}) is gone` };
+        }
+        return { state: "live" };
+    }
+    /**
+     * Reap pushers whose pane has gone, and say which ones could not be judged.
+     *
+     * `unprobeable` is NOT a residual list nobody reads — it is the distinction
+     * PRODUCTION_ROADMAP Phase 5.3 requires between "dead" and "cannot probe".
+     * An agent whose liveness is unknown is left alone and reported, never reaped.
+     */
+    async reapWedged(markers) {
+        const reaped = [];
+        const unprobeable = [];
+        for (const marker of markers) {
+            const live = await this.probe(marker);
+            if (live.state === "unknown") {
+                unprobeable.push(marker.agentId);
+                continue;
+            }
+            if (live.state === "live")
+                continue;
+            if (this.#host.killPusher(marker))
+                reaped.push(marker.agentId);
+            else
+                unprobeable.push(marker.agentId);
+        }
+        return { reaped, unprobeable };
+    }
+}
+//# sourceMappingURL=tmux.js.map

package/dist/transports/tmux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux.js","sourceRoot":"","sources":["../../src/transports/tmux.ts"],"names":[],"mappings":"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"}

package/dist/transports/types.js

@@ -0,0 +1,86 @@
+/**
+ * THE TRANSPORT SEAM (Phase 5.4 Task 2).
+ *
+ * This interface is DERIVED from the 12 `"tmux-push"` literals and the 7
+ * `spawnSync("tmux", …)` shell-outs that were spread across `tools/`, not
+ * designed top-down. Where the phase doc's sketch and the code disagreed, the
+ * code won — three times, each recorded below, because the gate for this task is
+ * that a running fleet cannot tell the difference.
+ *
+ * 1. `tmux-push-remote` IS A LIVE KIND. The doc's sketch had two kinds; the code
+ *    has three. `registry.ts` gives remote markers heartbeat-based liveness
+ *    because their pid is 0 on a foreign host, and `server.ts` documents the
+ *    value as the wire contract for `scripts/coord-pusher.mjs`. A union without
+ *    it silently reclassifies every remote agent as not-tmux.
+ * 2. THE MARKER HAS NINE FIELDS, NOT SIX. `scriptMtime`, `serverBuildMtime` and
+ *    `rooms` are absent from the sketch and each one closes a defect that
+ *    actually shipped. They are kept verbatim, including the rule they share:
+ *    ABSENT MEANS UNKNOWN, NEVER "ON" — the same principle as `Liveness.unknown`
+ *    below, one field deeper.
+ * 3. `target` IS ADDITIVE, NOT A RENAME. See `targetOf`.
+ */
+/**
+ * Every transport value that can appear in a marker on disk.
+ *
+ * Not `string`: the whole defect being fixed is code branching on a literal
+ * instead of reading the field, and a `string` discriminant cannot tell the
+ * compiler that a branch was missed. Not a two-member union either — see (1).
+ */
+export const TMUX_PUSH = "tmux-push";
+export const TMUX_PUSH_REMOTE = "tmux-push-remote";
+export const HERDR = "herdr";
+export const TRANSPORT_KINDS = [TMUX_PUSH, TMUX_PUSH_REMOTE, HERDR];
+/**
+ * The tmux family. Both members are delivered by a pusher process typing into a
+ * pane; they differ in WHERE that pane is, which is why liveness splits below.
+ *
+ * THIS IS THE ONE PLACE THE TMUX LITERALS LIVE. Twelve call sites used to spell
+ * them; they now ask.
+ */
+const TMUX_KINDS = new Set([TMUX_PUSH, TMUX_PUSH_REMOTE]);
+/** Is this marker carried by the tmux family (local OR remote)? */
+export function isTmuxKind(transport) {
+    return transport !== undefined && TMUX_KINDS.has(transport);
+}
+/**
+ * Is this marker's pane on THIS host, so that a local probe means anything?
+ *
+ * The distinction every `marker.transport !== "tmux-push"` site was making by
+ * hand, with a comment explaining "remote = can't verify". Naming it stops the
+ * next person re-deriving it — and re-deriving it wrongly is how a remote agent
+ * gets reported dead because a pane that was never local did not answer.
+ */
+export function isLocallyProbeable(transport) {
+    return transport === TMUX_PUSH;
+}
+/**
+ * Is liveness for this marker decided by the registry heartbeat rather than by a
+ * local pid? True only for the remote kind, whose pid is 0 on a foreign host.
+ */
+export function isRemoteTmuxKind(transport) {
+    return transport === TMUX_PUSH_REMOTE;
+}
+/**
+ * Read a marker's address, preferring the generic field and falling back to the
+ * tmux-specific one.
+ *
+ * This is the read half of the dual-write. Call it rather than touching either
+ * field: a consumer that reads only `tmuxTarget` goes blind the day a herdr
+ * marker appears, and one that reads only `target` is blind to every marker on
+ * disk today.
+ */
+export function targetOf(marker) {
+    return marker.target ?? marker.tmuxTarget;
+}
+/**
+ * Stamp an address into BOTH fields, so the marker is legible to the current
+ * code and to whatever a revert restores.
+ */
+export function withTarget(marker, target) {
+    if (target === undefined)
+        return marker;
+    return { ...marker, target, tmuxTarget: target };
+}
+/** Keystroke-shaped commands a transport must deliver to an interactive pane. */
+export const CONTROL_COMMANDS = ["clear", "compact", "reload-skills"];
+//# sourceMappingURL=types.js.map

package/dist/transports/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transports/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAoB,CAAC;AAC9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAA2B,CAAC;AAC5D,MAAM,CAAC,MAAM,KAAK,GAAG,OAAgB,CAAC;AAItC,MAAM,CAAC,MAAM,eAAe,GAA6B,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,CAAU,CAAC;AAEvG;;;;;;GAMG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAElE,mEAAmE;AACnE,MAAM,UAAU,UAAU,CAAC,SAA6B;IACtD,OAAO,SAAS,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAA6B;IAC9D,OAAO,SAAS,KAAK,SAAS,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAA6B;IAC5D,OAAO,SAAS,KAAK,gBAAgB,CAAC;AACxC,CAAC;AAoDD;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAsD;IAC7E,OAAO,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,UAAU,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAmB,MAAS,EAAE,MAA0B;IAChF,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACnD,CAAC;AAeD,iFAAiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,eAAe,CAAU,CAAC"}

package/hooks/tmux-pusher.mjs

@@ -288,7 +288,11 @@ function readJsonl(file) {
 // Allowlisted control commands the bus may type into this CLI. Mirrors
 // CONTROL_COMMANDS in src/tools/transport.ts and scripts/coord-pusher.mjs
 // (test/allowlist-parity.test.mjs locks the three); kept tiny + literal so a bugged/compromised
-// sender can't smuggle an arbitrary slash command past the guard below.
+// sender can't smuggle an arbitrary slash command onto the RAW submit path.
+// ⚠ THIS SET IS THE GATE. It used to be backed by a second check that dropped any
+// text starting with "/"; that check was removed in ⟨q-f14692ca⟩ because it silently
+// discarded legitimate messages and never saw the multi-line shape it was aimed at.
+// Membership here, plus bracketed paste on the peer path, is now the whole defence.
 const CONTROL_COMMANDS = new Set(["/clear", "/compact", "/reload-skills"]);
 
 // Shells we refuse to inject into: if the pane's foreground command is one of
@@ -321,9 +325,35 @@ function isControl(m) {
 function shouldInject(m) {
   if (!m || m.from === AGENT_ID) return false;
   if (ALLOWLIST.length > 0 && !ALLOWLIST.includes(m.from)) return false;
-  // Authorized control command — bypass the slash guard, injected raw later.
+  // Authorized control command — injected RAW later, so the allowlist in
+  // `isControl` is the gate that matters. Checked first and unchanged.
   if (isControl(m)) return true;
-  if (typeof m.text === "string" && m.text.trimStart().startsWith("/")) return false;
+
+  // ⛔ THE SLASH DROP USED TO LIVE HERE AND IT IS GONE ON PURPOSE (⟨q-f14692ca⟩).
+  //
+  // It returned false for any text starting with "/", which SILENTLY discarded
+  // the message: the sender was told nothing, and `collectSource` advances the
+  // offset past rejected lines, so it was never retried either. Measured in an
+  // isolated pane: a plain message and a trailing message both arrived, the
+  // slash-leading one between them did not, and the pusher log said nothing.
+  //
+  // AND IT WAS PROTECTING NOTHING THAT IS NOT ALREADY PROTECTED TWICE, measured
+  // rather than reasoned:
+  //   1. `formatBatch` prefixes every peer line with `  [DM hh:mm from] `, so a
+  //      single-line "/foo" reaches the pane with ZERO lines starting with "/" —
+  //      it is chat text, not a command.
+  //   2. Ordinary batches paste with `bracketed = true`, which makes the whole
+  //      payload inert: embedded newlines cannot submit a line or smuggle a
+  //      "/command". That is the defence that actually covers the multi-line
+  //      case, which this check never caught — `trimStart()` only ever examined
+  //      the FIRST line, so "opener\n/clear" passed straight through it.
+  //
+  // So the old guard was wrong in both directions at once: it dropped safe
+  // single-line messages, and it did not see the multi-line shape it was aimed
+  // at. Removing it restores delivery; the protection that matters is the
+  // allowlist above plus bracketed paste, and BOTH are pinned by tests in
+  // test/slash-message-delivery.test.mjs. ⚠ If anyone makes the peer path paste
+  // raw, those tests fail — which is the price of not having this check.
   return true;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.26.19",
+  "version": "0.26.21",
   "description": "File-backed MCP server for coordinating multiple AI coding agents (Claude Code, Cursor, Cline, etc.). Local stdio or networked over Streamable HTTP.",
   "type": "module",
   "bin": {
@@ -8,6 +8,18 @@
     "coord-chat": "scripts/coord-chat.mjs",
     "coord-pusher": "scripts/coord-pusher.mjs"
   },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm run clean && tsc",
+    "prepare": "node scripts/check-self-dependency.mjs && pnpm run clean && tsc",
+    "prepack": "node scripts/check-self-dependency.mjs && pnpm run build",
+    "prepublishOnly": "node scripts/check-publish-tool.mjs",
+    "start": "node dist/server.js",
+    "dev": "tsx src/server.ts",
+    "pretest": "node scripts/check-self-dependency.mjs && node scripts/check-optional-call.mjs && tsc",
+    "test": "node scripts/check-test-count.mjs",
+    "test:raw": "node --test \"test/*.test.mjs\""
+  },
   "files": [
     "dist",
     "src",
@@ -53,14 +65,5 @@
     "@types/proper-lockfile": "^4.1.4",
     "tsx": "^4.23.12",
     "typescript": "^7.0.2"
-  },
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "pnpm run clean && tsc",
-    "start": "node dist/server.js",
-    "dev": "tsx src/server.ts",
-    "pretest": "node scripts/check-self-dependency.mjs && node scripts/check-optional-call.mjs && tsc",
-    "test": "node scripts/check-test-count.mjs",
-    "test:raw": "node --test \"test/*.test.mjs\""
   }
-}
+}

package/src/capabilities.ts

@@ -39,6 +39,14 @@ import { suggestRecordType, typedRecordMode } from "./typed-records.js";
 import { LEAD_REFUSED, PARKED_CATEGORIES } from "./tools/away.js";
 import { recordAuthorityFor } from "./roles.js";
 import { subscriptionHealth } from "./tools/events.js";
+import {
+  configuredTransport,
+  runningTransport,
+  isTmuxKind,
+  targetOf,
+  type TransportKind,
+} from "./transports/index.js";
+import { readAllTransportMarkers } from "./tools/registry.js";
 
 export type ProbeResult = {
   id: string;
@@ -129,6 +137,44 @@ const PROBES: Probe[] = [
   },
 ];
 
+/**
+ * TWO CLAIMS, AND THE TYPE MAKES YOU CARRY BOTH (Phase 5.4 Task 3.3).
+ *
+ * *A config value is a label someone typed.* `configured` is that label;
+ * `running` is answered by CALLING the transport in this process. They are
+ * separate fields because they are separate facts, and `agrees` exists so a
+ * reader cannot skim one and believe the other.
+ *
+ * ⛔ THIS IS THE MACHINE-READABLE FORM OF A MISTAKE MADE IN PROSE. An hour
+ * before this shipped, a Task 2 contract asserted that "every seat in this fleet
+ * is running on the code you are refactoring." Measured afterwards: every server
+ * and every pusher loads the global install at 0.26.19 while `main` declared
+ * 0.26.20 — the fleet was running PRE-refactor code and always had been. The
+ * claim came from what the repo said, not from what any process answered. That
+ * is `configured` reported as `running`, in English instead of in a type.
+ *
+ * `running` is `undefined` when nothing is wired, which is NOT "tmux by
+ * default": a process with no transport delivers nothing, and substituting a
+ * default there would restage the same substitution one layer down.
+ */
+export type TransportCapability = {
+  configured: TransportKind;
+  /** Answered by calling the transport, never by reading config. */
+  running: TransportKind | undefined;
+  agrees: boolean;
+  /** What was called and what came back. */
+  evidence: string;
+  /** Where `configured` came from — config file, env, or the built-in default. */
+  configuredSource: "config" | "env" | "default";
+  /**
+   * MIXED FLEET, MADE LOUD (3.4). Agents whose marker names a transport other
+   * than the running one. Whole-fleet is the rule; this is the code noticing
+   * when reality disagrees with the rule rather than trusting it — at 2-of-5
+   * stall coverage a silent disagreement is a failure nobody can see.
+   */
+  disagreeingAgents: { agentId: string; marker: string }[];
+};
+
 export type CapabilityReport = {
   /**
    * WHICH PROCESS ANSWERED. Not evidence of anything — context, so a reader can
@@ -140,6 +186,8 @@ export type CapabilityReport = {
   probes: ProbeResult[];
   missing: string[];
   ok: boolean;
+  /** Absent only if the probe itself threw — see `probeTransport`. */
+  transport?: TransportCapability;
   note: string;
 };
 
@@ -182,7 +230,62 @@ import { resolveServerIdentity } from "./server-identity.js";
 
 export const capabilitiesSchema = {} as const;
 
+/**
+ * Build the transport capability by CALLING things, then compare.
+ *
+ * Deliberately async and deliberately separate from `probeCapabilities`, which
+ * is synchronous: the transport answer requires I/O (a `tmux -V`, a pane probe),
+ * and making the sync report do I/O to obtain it would have meant reading the
+ * config instead — which is the substitution this whole field exists to refuse.
+ */
+export async function probeTransport(): Promise<TransportCapability> {
+  const conf = configuredTransport();
+  const running = await runningTransport();
+
+  // 3.4 — a mixed fleet must be detectable and LOUD. Every marker on disk is
+  // read and any that names a different transport is listed by agent, because a
+  // count alone tells you something is wrong and not where to look.
+  const disagreeingAgents: { agentId: string; marker: string }[] = [];
+  try {
+    // READ-ONLY on purpose. The reaping loader would delete markers it judged
+    // not-live, so a diagnostic would mutate the fleet it is describing — and it
+    // would hide the remote kind, whose liveness needs a registry heartbeat.
+    for (const { marker, live } of await readAllTransportMarkers()) {
+      if (running.kind !== undefined && marker.transport !== running.kind) {
+        const where = isTmuxKind(marker.transport) ? targetOf(marker) : undefined;
+        disagreeingAgents.push({
+          agentId: marker.agentId,
+          marker: `${marker.transport}${where ? ` (${where})` : ""}${live ? "" : " [stale]"}`,
+        });
+      }
+    }
+  } catch {
+    // An unreadable transports dir is not evidence of a uniform fleet. Left
+    // empty, and the caller can see `running` was still answered.
+  }
+
+  return {
+    configured: conf.kind,
+    running: running.kind,
+    agrees: running.kind === conf.kind,
+    evidence: running.evidence,
+    configuredSource: conf.source,
+    disagreeingAgents,
+  };
+}
+
 export async function capabilitiesTool() {
   const id = resolveServerIdentity();
-  return probeCapabilities({ module: id.path, versionLabel: id.version });
+  const report = probeCapabilities({ module: id.path, versionLabel: id.version });
+  try {
+    return { ...report, transport: await probeTransport() };
+  } 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
+    // reaches for to find out why — so it must still answer, and say what threw.
+    return {
+      ...report,
+      transportError: `transport probe threw: ${(e as Error).message}`,
+    };
+  }
 }

package/src/gated-head.ts

@@ -0,0 +1,134 @@
+/*
+ * ⛔⛆ THE THING MERGED MUST BE THE THING GATED — AND NOTHING COMPARED THEM.
+ *
+ * `⟨q-6a4f0c38⟩`, from a real breach on kit#268. The sequence, which no single
+ * seat could see alone:
+ *
+ *   10:23:14Z  QA posts PASS bound to 6051193
+ *   10:23:22Z  the merge runs           <- 8 seconds later
+ *              but the branch head was 1d6deab by then: an author force-pushed
+ *   10:28:06Z  QA re-issues PASS bound to 1d6deab, AFTER the fact
+ *
+ * Three controls had to fail together: the force-push created the opportunity,
+ * the merge did not re-read the head, and the recording step did not compare.
+ * This module is the predicate for the two that are mechanisable.
+ *
+ * ⭐ WHY THE CHECK MUST BE TEMPORAL, and this is the trap that makes the naive
+ * version certify the very breach it was built for: by the time anyone looks,
+ * a PASS bound to `1d6deab` EXISTS. "Is there a PASS for the merged head?" is
+ * TRUE for #268 today. Only "was there one AT OR BEFORE the merge" is false.
+ * A re-issued verdict is an honest record that the CONTENT was verified; it is
+ * not evidence that the MERGE was gated, and conflating them erases the event.
+ *
+ * ⭐ WHY THE SHA COMPARISON IS PREFIX-TOLERANT RATHER THAN EQUALITY. Measured
+ * across all 45 verdict records on this fleet's room log:
+ *
+ *     headRefOid length:  7 chars -> 14 records,  40 chars -> 31 records
+ *
+ * Verdicts are written by hand and abbreviate. An exact compare against `gh`'s
+ * 40-char head would report "never gated" on ~31% of verdicts that DID gate —
+ * false positives on correct merges, which is the failure that gets a check
+ * switched off. MIN_SHA guards the other direction: a 4-character "sha" is not
+ * an identifier, it is a collision, so it is REFUSED rather than matched.
+ *
+ * ⛔ AND "COULD NOT CHECK" IS NEVER "CHECKED AND CLEAN" — the rule this repo
+ * already applies in `versionDrift`. No verdict found, an unreadable log and an
+ * unreachable `gh` are each a REFUSAL with a reason, never a pass.
+ */
+
+/** Below this, an abbreviation is a collision rather than an identifier. */
+export const MIN_SHA = 7;
+
+/**
+ * Do two object names refer to the same commit, allowing either to be
+ * abbreviated? Case-insensitive; hex only; both must reach MIN_SHA.
+ */
+export function shaAgrees(a: string | undefined, b: string | undefined): boolean {
+  const x = (a ?? "").trim().toLowerCase();
+  const y = (b ?? "").trim().toLowerCase();
+  if (!/^[0-9a-f]+$/.test(x) || !/^[0-9a-f]+$/.test(y)) return false;
+  if (x.length < MIN_SHA || y.length < MIN_SHA) return false;
+  return x.length <= y.length ? y.startsWith(x) : x.startsWith(y);
+}
+
+export type PassVerdict = { head: string; ts: number; from: string; result: string };
+
+/** The PR number a verdict record is about, from its `cites`. */
+function citedPr(cites: unknown): string | null {
+  if (!Array.isArray(cites)) return null;
+  for (const c of cites) {
+    const ref = String((c as { ref?: unknown })?.ref ?? "");
+    const m = ref.match(/#(\d+)/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/**
+ * Every verdict record in a room log that is about PR `pr`.
+ *
+ * Tolerant of unparseable lines by SKIPPING them and reporting how many, rather
+ * than throwing: a log this cannot fully read still answers the question for the
+ * lines it can, and the caller is told the denominator it actually saw.
+ */
+export function verdictsFor(logText: string, pr: string): { verdicts: PassVerdict[]; lines: number; unparsed: number } {
+  const lines = logText.split("\n").filter((l) => l.trim());
+  let unparsed = 0;
+  const verdicts: PassVerdict[] = [];
+  for (const l of lines) {
+    let o: Record<string, unknown>;
+    try {
+      o = JSON.parse(l) as Record<string, unknown>;
+    } catch {
+      unparsed++;
+      continue;
+    }
+    const r = o.record as { type?: string; payload?: Record<string, unknown>; cites?: unknown } | undefined;
+    if (!r || r.type !== "verdict") continue;
+    if (citedPr(r.cites) !== pr) continue;
+    verdicts.push({
+      head: String(r.payload?.headRefOid ?? ""),
+      ts: Number(o.ts ?? 0),
+      from: String(o.from ?? ""),
+      result: String(r.payload?.result ?? ""),
+    });
+  }
+  return { verdicts, lines: lines.length, unparsed };
+}
+
+export type GateAnswer =
+  | { gated: true; by: PassVerdict }
+  | { gated: false; reason: string; crossed?: { gatedSha: string; at: number }[] };
+
+/**
+ * Was `head` gated by a PASS that existed at or before `at`?
+ *
+ * `at` is the decisive argument. Pass the merge time to ask "was this merge
+ * gated"; pass `Date.now()` to ask "is this head gated right now", which is the
+ * pre-merge question. Same predicate, two positions.
+ */
+export function gatedAt(verdicts: PassVerdict[], head: string, at: number): GateAnswer {
+  const passes = verdicts.filter((v) => v.result === "pass");
+  if (passes.length === 0) {
+    return { gated: false, reason: `no PASS verdict was ever recorded for this PR — not checked, which is not the same as checked and passing` };
+  }
+  const inTime = passes.filter((v) => v.ts <= at);
+  if (inTime.length === 0) {
+    return {
+      gated: false,
+      reason:
+        `every PASS for this PR was recorded AFTER the moment being judged — a verdict posted later says the content ` +
+        `was verified, never that this merge was gated`,
+      crossed: passes.map((v) => ({ gatedSha: v.head, at: v.ts })),
+    };
+  }
+  const match = inTime.find((v) => shaAgrees(v.head, head));
+  if (match) return { gated: true, by: match };
+  return {
+    gated: false,
+    reason:
+      `the head being judged (${head.slice(0, 7)}) matches no PASS recorded at or before that moment — ` +
+      `the thing merged is not the thing gated`,
+    crossed: inTime.map((v) => ({ gatedSha: v.head, at: v.ts })),
+  };
+}