agent-coord-mcp 0.26.19 → 0.26.21

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

package/src/transports/config.ts

@@ -0,0 +1,110 @@
+/**
+ * WHICH TRANSPORT THIS FLEET IS CONFIGURED TO USE (Phase 5.4 Task 3.1–3.2).
+ *
+ * Whole-fleet, read ONCE at startup, per David 2026-09-11 — no per-seat
+ * branching in `send_command` or `attach`. Memoised for that reason and not for
+ * speed: a value that can be re-read mid-process is a value that can change
+ * mid-process, and then two calls in one session disagree about what the fleet
+ * is doing.
+ *
+ * ⛔ AN UNKNOWN VALUE REFUSES AT STARTUP. It does not fall back to `tmux-push`.
+ *
+ * The reason is not tidiness. A SILENT FALLBACK AND A CORRECT DEFAULT PRODUCE
+ * IDENTICAL EVIDENCE: both give you a fleet on tmux with nothing in any log, so
+ * a typo in the config reads exactly like a deliberate default, and the person
+ * who typed `heardr` spends the afternoon asking why their transport change did
+ * nothing. Refusing is louder than the bug it prevents.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { ROOT } from "../store.js";
+import { TMUX_PUSH, TRANSPORT_KINDS, type TransportKind } from "./types.js";
+
+/** `$AGENT_COORD_DIR/config.json`, the fleet-wide file. */
+export const TRANSPORT_CONFIG_FILE = path.join(ROOT, "config.json");
+export const TRANSPORT_ENV_VAR = "AGENT_COORD_TRANSPORT";
+
+/**
+ * PRECEDENCE, documented here because 3.2 asks for a decision and not a
+ * preference: **config file > env > default**.
+ *
+ * The file wins because it is the FLEET's statement and is reviewable — it sits
+ * on disk where every seat reads the same bytes, and a wrong value can be
+ * corrected in one place. An env var is per-process: it is the right tool for
+ * one seat to deviate deliberately (a test, a bisect), and the wrong tool for
+ * stating what the fleet does, because nothing can see it from outside that
+ * process. So the narrower, less visible source loses to the broader one, and
+ * `source` is reported so a surprising answer can be traced to its origin
+ * rather than guessed at.
+ */
+export type ConfiguredTransport = {
+  kind: TransportKind;
+  source: "config" | "env" | "default";
+  /** Where the value came from, for an error message a human can act on. */
+  origin: string;
+};
+
+function refuse(value: string, origin: string): never {
+  throw new Error(
+    `[agent-coord-mcp] unknown transport ${JSON.stringify(value)} from ${origin}. ` +
+      `Valid: ${TRANSPORT_KINDS.join(", ")}. ` +
+      `REFUSING AT STARTUP rather than falling back to "${TMUX_PUSH}" — a silent fallback and a correct ` +
+      `default leave identical evidence, so a typo here would look exactly like a working default and the ` +
+      `transport change would appear to do nothing. Fix the value or remove it to get the default.`,
+  );
+}
+
+function asKind(value: unknown, origin: string): TransportKind {
+  if (typeof value !== "string" || value.length === 0) refuse(String(value), origin);
+  const match = TRANSPORT_KINDS.find((k) => k === value);
+  if (!match) refuse(value, origin);
+  return match;
+}
+
+let cached: ConfiguredTransport | undefined;
+
+/**
+ * Resolve the fleet's transport. Throws on an unknown value — call it once at
+ * startup so the refusal lands before any agent attaches.
+ */
+export function configuredTransport(): ConfiguredTransport {
+  if (cached) return cached;
+
+  if (existsSync(TRANSPORT_CONFIG_FILE)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(TRANSPORT_CONFIG_FILE, "utf8"));
+    } catch (e) {
+      // A CONFIG FILE THAT CANNOT BE PARSED IS NOT AN ABSENT ONE. Treating it as
+      // absent would silently use the default while a file sits there stating
+      // otherwise — the same two-states-one-evidence defect as the fallback.
+      throw new Error(
+        `[agent-coord-mcp] ${TRANSPORT_CONFIG_FILE} is unreadable (${(e as Error).message}). ` +
+          `REFUSING rather than treating it as absent: a file that exists and cannot be read is not the ` +
+          `same as no file, and defaulting here would hide a stated intent behind a working fleet.`,
+      );
+    }
+    const raw = (parsed as { transport?: unknown } | null)?.transport;
+    if (raw !== undefined) {
+      cached = { kind: asKind(raw, `${TRANSPORT_CONFIG_FILE} ("transport")`), source: "config", origin: TRANSPORT_CONFIG_FILE };
+      return cached;
+    }
+  }
+
+  const env = process.env[TRANSPORT_ENV_VAR];
+  if (env !== undefined && env !== "") {
+    cached = { kind: asKind(env, `$${TRANSPORT_ENV_VAR}`), source: "env", origin: `$${TRANSPORT_ENV_VAR}` };
+    return cached;
+  }
+
+  cached = { kind: TMUX_PUSH, source: "default", origin: `built-in default (${TMUX_PUSH})` };
+  return cached;
+}
+
+/**
+ * Drop the memo. FOR TESTS ONLY — the whole point of reading once is that
+ * production code cannot do this.
+ */
+export function resetConfiguredTransportForTests(): void {
+  cached = undefined;
+}

package/src/transports/index.ts

@@ -0,0 +1,126 @@
+/**
+ * THE REGISTRY — the one place a transport kind is turned into an implementation.
+ *
+ * `resolveTransport` is deliberately total over `TransportKind`: adding a kind to
+ * the union without registering it is a compile error here rather than a silent
+ * fall-through at a call site. Until Task 3, tmux is the only registered
+ * implementation and that is the rollback plan — the seam lands behind no config.
+ */
+import { HERDR, TMUX_PUSH, TMUX_PUSH_REMOTE, type Transport, type TransportKind } from "./types.js";
+import { TmuxTransport, type TmuxHost } from "./tmux.js";
+import { configuredTransport } from "./config.js";
+
+export * from "./types.js";
+export * from "./config.js";
+export { TmuxTransport, tmuxAvailable, paneExists, probePane, tmuxVersion, type TmuxHost } from "./tmux.js";
+
+let host: TmuxHost | undefined;
+
+/** Wire the process-layer implementation in once, at module init. */
+export function registerTmuxHost(h: TmuxHost): void {
+  host = h;
+}
+
+export function resolveTransport(kind: TransportKind): Transport {
+  if (!host) {
+    throw new Error(
+      "transport host not registered — call registerTmuxHost() before resolveTransport(); " +
+        "this is a wiring error, not a runtime condition",
+    );
+  }
+  switch (kind) {
+    case TMUX_PUSH:
+    case TMUX_PUSH_REMOTE:
+      return new TmuxTransport(host, kind);
+    case HERDR:
+      // Task 4. Named so the union stays total and the gap is a stated absence
+      // rather than a default that silently behaves like tmux.
+      throw new Error('transport "herdr" is not implemented yet (Phase 5.4 Task 4)');
+  }
+}
+
+/* ── the ACTIVE transport, and why `running` is not read from config ────────── */
+
+/**
+ * The instance this process would actually use to deliver.
+ *
+ * Kept as an OBJECT rather than re-derived from the config value on each call,
+ * and that is the whole design. If `running` were computed by reading the config
+ * and resolving it, then `configured` and `running` would be two names for one
+ * fact and `agrees` could never be false — a check that cannot fail. The active
+ * instance is what startup actually installed, so the two can genuinely differ:
+ * a startup that refused, a process that never wired one, a test that installed
+ * another, a future path that falls back.
+ */
+let active: Transport | undefined;
+
+export function setActiveTransport(t: Transport): void {
+  active = t;
+}
+
+/** FOR TESTS ONLY — production wires the active transport once, at startup. */
+export function clearActiveTransportForTests(): void {
+  active = undefined;
+}
+
+export function activeTransport(): Transport | undefined {
+  return active;
+}
+
+/**
+ * Wire the transport this fleet is configured for. Called once at startup, and
+ * it is where an unknown config value turns into a refusal.
+ */
+export function initTransportFromConfig(): { kind: TransportKind; source: string } {
+  const conf = configuredTransport();
+  setActiveTransport(resolveTransport(conf.kind));
+  return { kind: conf.kind, source: conf.source };
+}
+
+/**
+ * WHAT THIS PROCESS IS ACTUALLY RUNNING, answered by CALLING the transport.
+ *
+ * *A config value is a label someone typed.* This asks the live object instead:
+ * it calls `available()` and puts a synthetic marker through `probe()`, and
+ * reports what came back as the evidence beside the answer. The probe is chosen
+ * to be discriminating rather than decorative — a tmux transport answers a
+ * bogus pane id with a reason that names the pane, and an implementation that
+ * does not talk to panes cannot produce that.
+ *
+ * Returns `undefined` for `kind` when nothing is wired, which is NOT the same as
+ * "tmux by default": a process with no transport delivers nothing, and reporting
+ * a default here would be the exact substitution this function exists to refuse.
+ */
+export async function runningTransport(): Promise<{
+  kind: TransportKind | undefined;
+  evidence: string;
+}> {
+  const t = active;
+  if (!t) {
+    return {
+      kind: undefined,
+      evidence: "no transport is wired in this process — nothing was called, and no default is assumed",
+    };
+  }
+  const availability = (() => {
+    try {
+      return `available()=${t.available()}`;
+    } catch (e) {
+      return `available() threw: ${(e as Error).message}`;
+    }
+  })();
+  let probeEvidence: string;
+  try {
+    const live = await t.probe({
+      agentId: "__capability_probe__",
+      transport: t.kind,
+      pid: process.pid,
+      target: "__no_such_target__",
+      since: Date.now(),
+    });
+    probeEvidence = `probe(bogus target)=${live.state}${live.state === "live" ? "" : `: ${live.reason}`}`;
+  } catch (e) {
+    probeEvidence = `probe threw: ${(e as Error).message}`;
+  }
+  return { kind: t.kind, evidence: `${availability}, ${probeEvidence}` };
+}

package/src/transports/tmux.ts

@@ -0,0 +1,177 @@
+/**
+ * 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 type { ControlCommand, Liveness, Transport, TransportMarker, TransportKind } from "./types.js";
+import { TMUX_PUSH, isLocallyProbeable, isTmuxKind, targetOf } from "./types.js";
+
+/**
+ * The parts of delivery that belong to the PROCESS layer, not to tmux.
+ *
+ * Injected rather than imported to keep the dependency pointing one way:
+ * `tools/transport.ts` owns pusher spawn, receipts and marker files, and hands
+ * them here. Importing them back would make this module and that one mutually
+ * dependent, and a cycle is how "one place for the literal" quietly becomes two.
+ */
+export type TmuxHost = {
+  attach(args: {
+    agentId: string;
+    target?: string;
+    includeRoom?: boolean;
+    allowlist?: string[];
+    debounceMs?: number;
+  }): Promise<TransportMarker>;
+  detach(agentId: string): Promise<void>;
+  push(marker: TransportMarker, text: string): Promise<{ delivered: boolean; error?: string }>;
+  sendControl(marker: TransportMarker, cmd: ControlCommand): Promise<{ ok: boolean; error?: string }>;
+  /** Is the pusher process behind this marker still running on this host? */
+  pusherAlive(marker: TransportMarker): boolean;
+  /** Stop a wedged pusher. Returns false if it could not be signalled. */
+  killPusher(marker: TransportMarker): boolean;
+};
+
+/** `tmux -V` — is tmux on this host at all? */
+export function tmuxAvailable(): boolean {
+  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: string): boolean {
+  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: string): { exists: boolean; stderr: string } {
+  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(): string | undefined {
+  const probe = spawnSync("tmux", ["-V"]);
+  if (probe.status !== 0) return undefined;
+  return (probe.stdout ?? "").toString().trim() || undefined;
+}
+
+export class TmuxTransport implements Transport {
+  readonly kind: TransportKind;
+  #host: TmuxHost;
+
+  constructor(host: TmuxHost, kind: TransportKind = TMUX_PUSH) {
+    this.#host = host;
+    this.kind = kind;
+  }
+
+  available(): boolean {
+    return tmuxAvailable();
+  }
+
+  attach(args: {
+    agentId: string;
+    target?: string;
+    includeRoom?: boolean;
+    allowlist?: string[];
+    debounceMs?: number;
+  }): Promise<TransportMarker> {
+    return this.#host.attach(args);
+  }
+
+  detach(agentId: string): Promise<void> {
+    return this.#host.detach(agentId);
+  }
+
+  push(marker: TransportMarker, text: string): Promise<{ delivered: boolean; error?: string }> {
+    return this.#host.push(marker, text);
+  }
+
+  sendControl(marker: TransportMarker, cmd: ControlCommand): Promise<{ ok: boolean; error?: string }> {
+    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: TransportMarker): Promise<Liveness> {
+    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: TransportMarker[]): Promise<{ reaped: string[]; unprobeable: string[] }> {
+    const reaped: string[] = [];
+    const unprobeable: string[] = [];
+    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 };
+  }
+}