agent-coord-mcp 0.26.20 → 0.26.22

package/src/tools/transport.ts

@@ -33,6 +33,7 @@ import { promises as fsp } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { seatBuildOf, installedFrom, psReader } from "./seat-build.js";
 import path from "node:path";
 import {
   AGENTS_FILE,
@@ -157,12 +158,17 @@ export async function pingTool(args: { from: string; to: string; echo?: boolean
 
   let echoSent = false;
   if (args.echo && alive) {
-    await sendMessageTool({
+    // ⟨q-138f4b78⟩ — the echo is an agent→agent DM, so past the typed-record
+    // cutover it MUST carry a record or the send is refused; and `echoSent`
+    // reports what the send SAID, never that a call was made — measured on the
+    // cutover morning: this reported true while nothing was written.
+    const sent = await sendMessageTool({
       from: args.from,
       to: args.to,
       text: `PING: echo requested by ${args.from} — DM back if responsive.`,
+      record: { type: "fyi", payload: { summary: `PING echo requested by ${args.from}` } },
     });
-    echoSent = true;
+    echoSent = sent.ok === true;
   }
 
   return {
@@ -899,9 +905,22 @@ export async function statusTool(args: { agentId: string }) {
   // is the case every other instrument here reports as if the fleet were one
   // thing.
   const capabilities = await capabilitiesTool();
+  // ⟨q-8a3f1c05⟩ — THIS SEAT'S BUILD STATE, both halves: the pusher from its marker's
+  // pid via ps (keyed by --agent), the server from THIS process — status is called
+  // by the seat about itself, which is the one case the server half is knowable.
+  const id = resolveServerIdentity();
+  const installed = installedFrom(id.path);
+  const build = seatBuildOf({
+    agentId: args.agentId,
+    marker: transport,
+    installed,
+    ps: psReader,
+    server: { pid: process.pid, startedAt: Date.now() - Math.round(process.uptime() * 1000), buildMtime: installed.buildMtime },
+  });
 
   return {
     agentId: args.agentId,
+    build,
     registered: !!entry,
     entry,
     attached: !!transport,

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

package/src/tools/worktrees.ts

@@ -215,12 +215,25 @@ async function create(a: {
   } catch (e) {
     return { ok: false as const, error: `git worktree add failed: ${String((e as Error).message).split("\n")[0]}` };
   }
+  // ⟨q-7b2f6c04⟩ — THE EMPTY PUSH AT CLAIM. The branch goes to origin at the
+  // base's tip, so the lane has a ref on the remote from its first minute: the
+  // VCS axis sees it, and the stall clock scores it on the CLAIM axis (a ref
+  // sitting on the base has no commits of its own to date). Best-effort and
+  // REPORTED, never fatal — a tree cut offline is still a tree.
+  let pushed: { ok: true; ref: string } | { ok: false; why: string };
+  try {
+    execFileSync("git", ["push", "-q", "-u", "origin", `${branch}:refs/heads/${branch}`], { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 20_000 });
+    pushed = { ok: true, ref: `origin/${branch}` };
+  } catch (e) {
+    pushed = { ok: false, why: `the empty claim-time push did not land: ${String((e as Error).message).split("\n").find((l) => l.trim()) ?? "unknown"} — the lane is observable on the claim axis from the board's history only` };
+  }
   return {
     ok: true as const,
     path: target,
     sha,
     branch,
     created: true,
+    pushed,
     base: ref,
     // Cut from `sha`, which IS origin/<base> — true by construction here, and
     // stated so callers need not special-case "created" to know it.