agent-coord-mcp 0.26.18 → 0.26.20

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/work.ts

@@ -139,8 +139,21 @@ function importedSummary(d: StoredDoc) {
     board: ["board"],
     legacy: ["queue", "done"],
   } as const;
+  // THE AXIS IS PASSED, NOT JUST ITERATED. It was already in scope here and was
+  // not handed to the predicate, so seam 0.1.16's queue-axis fix (#234) changed
+  // nothing any caller could observe: a pruned-but-healthy QUEUE.md kept
+  // reporting `unparsed: ["queue"]` because the predicate fell back to measuring
+  // authored CONTENT, and a queue keeps its headings and prose by design.
+  //
+  // Without the argument the queue axis asks "is there any prose here?" — which
+  // on a queue document is always yes. With it, it asks "did somebody write a
+  // ROW that failed to parse?", which is the question the zero actually needs.
+  // Every axis is passed its own name; only "queue" is treated differently
+  // inside the predicate. `done` and `board` keep the content measure
+  // deliberately — prose under an empty done log IS a fair reason to doubt that
+  // zero — so this is a narrowing of one axis, not a relaxation of all three.
   const unparsed = (AXES_BY_KIND[d.kind] as readonly (keyof typeof counts)[]).filter((axis) =>
-    zeroIsUnparsed(counts[axis], d.source),
+    zeroIsUnparsed(counts[axis], d.source, axis),
   );
   return {
     path: d.path,
@@ -188,6 +201,41 @@ async function loadState(project: string): Promise<WorkState | null> {
   return readJson<WorkState | null>(workFile(project), null);
 }
 
+/**
+ * WHICH STORED DOCS HAVE BEEN OVERTAKEN BY THE FILE ON DISK.
+ *
+ * THE FRESHNESS OF A RESPONSE IS THE FRESHNESS OF ITS STALEST FIELD, and before
+ * this the store was trusted because it existed. Measured on this fleet: a store
+ * imported at 17:29 already disagreed with 3 of its 4 documents by 17:42 —
+ * **thirteen minutes.** On a bus where several seats write coordination docs, the
+ * staleness window is minutes, not the weeks a dated store suggests.
+ *
+ * The instrument is mtime, and its limit is stated rather than hidden: an edit
+ * that PRESERVES mtime is not detected. mtime is used because the cheap question
+ * ("might the store be stale?") must not cost a full re-read of ~800KB of
+ * documents on every call; when the answer is yes, the re-read happens anyway.
+ * A missing file counts as stale — it cannot be compared, and "could not check"
+ * is not "checked and clean".
+ */
+async function staleDocs(state: WorkState): Promise<{ path: string; why: string }[]> {
+  const out: { path: string; why: string }[] = [];
+  for (const d of state.docs) {
+    const full = path.join(state.repo, d.path);
+    try {
+      const st = await fsp.stat(full);
+      if (st.mtimeMs > state.importedAt) {
+        out.push({
+          path: d.path,
+          why: `modified ${new Date(st.mtimeMs).toISOString()}, after the store was imported at ${new Date(state.importedAt).toISOString()}`,
+        });
+      }
+    } catch (e) {
+      out.push({ path: d.path, why: `cannot be read (${(e as Error).message}) — unverifiable, not assumed clean` });
+    }
+  }
+  return out;
+}
+
 async function saveState(state: WorkState): Promise<void> {
   await fsp.mkdir(WORK_DIR, { recursive: true });
   await fsp.writeFile(workFile(state.project), JSON.stringify(state, null, 2) + "\n", "utf8");
@@ -293,6 +341,13 @@ export async function listWorkTool(args: {
   // rather than in a comment.
   let state = await loadState(args.project);
   let source: "store" | "markdown" = "store";
+  // A STALE STORE IS NEVER SERVED SILENTLY. `staleStore` is present in the
+  // response whenever the store lost a race with the documents, so the caller
+  // learns it from the ANSWER rather than from a `source` field they would have
+  // to know to check. The confound this removes: `issues` carried live-looking
+  // diagnostics beside a stale queue, so the field that made a careful reader
+  // trust the payload was the one field that was current.
+  let staleStore: { reparsed: boolean; docs: { path: string; why: string }[]; note: string } | undefined;
   if (!state) {
     const imported = await importFromDisk(args.project, args.repo ?? process.cwd());
     if (!imported) {
@@ -300,6 +355,33 @@ export async function listWorkTool(args: {
     }
     state = imported;
     source = "markdown";
+  } else {
+    const stale = await staleDocs(state);
+    if (stale.length) {
+      const fresh = await importFromDisk(state.project, state.repo);
+      if (fresh) {
+        state = fresh;
+        source = "markdown";
+        staleStore = {
+          reparsed: true,
+          docs: stale,
+          note:
+            `the store was older than ${stale.length} of its document(s) and was NOT used — these rows were re-parsed from disk. ` +
+            `Every field below therefore shares one provenance.`,
+        };
+      } else {
+        // Cannot re-read, so the stale store is all there is. It is still
+        // reported, because an answer that cannot be refreshed is the one most
+        // in need of saying so.
+        staleStore = {
+          reparsed: false,
+          docs: stale,
+          note:
+            `the store is older than ${stale.length} of its document(s) and could NOT be re-parsed from disk — ` +
+            `the rows below are as stale as the store and must not be read as current.`,
+        };
+      }
+    }
   }
 
   const queue: QueueItem[] = [];
@@ -325,9 +407,9 @@ export async function listWorkTool(args: {
   // the caller does not have to know which kind its own id belongs to.
   if (args.id !== undefined) {
     const queueHit = queue.find((q) => q.id === args.id);
-    if (queueHit) return { ok: true as const, project: state.project, repo: state.repo, source, kind: "queue" as const, item: queueHit };
+    if (queueHit) return { ok: true as const, project: state.project, repo: state.repo, source, ...(staleStore ? { staleStore } : {}), kind: "queue" as const, item: queueHit };
     const doneHit = done.find((d) => d.id === args.id);
-    if (doneHit) return { ok: true as const, project: state.project, repo: state.repo, source, kind: "done" as const, item: doneHit };
+    if (doneHit) return { ok: true as const, project: state.project, repo: state.repo, source, ...(staleStore ? { staleStore } : {}), kind: "done" as const, item: doneHit };
     return { ok: false as const, error: `no queue item or DONE entry with id '${args.id}' in project '${state.project}'` };
   }
 
@@ -339,6 +421,16 @@ export async function listWorkTool(args: {
     project: state.project,
     repo: state.repo,
     source,
+    ...(staleStore ? { staleStore } : {}),
+    // PROVENANCE OF THE WHOLE PAYLOAD, including the instrument and its limit.
+    // Done-def 4: if any field can outpace another, the response says so rather
+    // than a comment saying it.
+    freshness: {
+      source,
+      importedAt: new Date(state.importedAt).toISOString(),
+      checkedAgainst: "file mtime vs store importedAt",
+      limit: "an edit that preserves mtime is not detected; a re-parse is triggered only when mtime is newer",
+    },
     // IDENTITY ONLY (Task 15.1) — id, priority, a bounded headline, and
     // blocked-by; never the full item text. Call again with `id` for one
     // row's body. This is the change that makes the tool cheap: the same