agent-coord-mcp 0.26.5 → 0.26.7

package/dist/tools/stall.js

@@ -0,0 +1,294 @@
+/*
+ * `stall_check` — a predicate over the board and the bus, plus a HALT flag.
+ *
+ * Stall has been "notice the room" until now, which means it is noticed when
+ * somebody happens to look. The measured cost elsewhere: ~42 hours of dead merge
+ * path across four incidents in three days, with `main` advancing throughout so
+ * every commit-based liveness check read green.
+ *
+ * A MISS IS SILENT TO THE DUTY OFFICER AND NEVER SILENT TO THE RECORD.
+ *
+ * This is the whole design constraint (3.3b). "HIT DMs, MISS silent" answers the
+ * noise question and makes a DEAD CLOCK look exactly like a healthy fleet — the
+ * absence-read-as-evidence rule, inside the verb built to watch for absence. So
+ * every run leaves a mark, HIT or MISS, and "no alert" becomes distinguishable
+ * from "nothing ran". A check that only speaks when it fires cannot be told from
+ * a broken one.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { z } from "zod";
+import { parseWorkDoc, workstreamsV1RowsOf } from "@davidbalzan/groundwork-seam";
+import { ROOT, AGENTS_FILE, readJson } from "../store.js";
+import { loadLiveTransports } from "./registry.js";
+const BOARD_DOC = "docs/WORKSTREAMS.md";
+const STALL_MS = 30 * 60 * 1000;
+const runFile = () => path.join(ROOT, "stall-check.json");
+const haltFile = () => path.join(ROOT, "halt.json");
+// ---------- halt ----------
+export const setHaltSchema = {
+    reason: z.string().min(1),
+    by: z.string().min(1),
+    clear: z.boolean().optional(),
+};
+/**
+ * A NAMED state, never a mood.
+ *
+ * "Production feels down" is not a halt: a halt blocks every claim in the fleet,
+ * so the thing that sets it must be nameable and therefore arguable — a board
+ * cutover, a cited `BLOCKER:`, a documented red pipeline. The reason is required
+ * for that reason, not for the log.
+ */
+export async function setHaltTool(args) {
+    mkdirSync(ROOT, { recursive: true });
+    if (args.clear) {
+        writeFileSync(haltFile(), JSON.stringify({ halted: false, clearedBy: args.by, clearedAt: Date.now(), lastReason: args.reason }, null, 2));
+        return { ok: true, halted: false, clearedBy: args.by };
+    }
+    const state = { halted: true, reason: args.reason, by: args.by, at: Date.now() };
+    writeFileSync(haltFile(), JSON.stringify(state, null, 2));
+    return { ok: true, ...state };
+}
+export function haltState() {
+    try {
+        const raw = JSON.parse(readFileSync(haltFile(), "utf8"));
+        return raw?.halted ? raw : { halted: false };
+    }
+    catch {
+        return { halted: false };
+    }
+}
+// ---------- the run mark ----------
+/** Every run leaves this, HIT or MISS. It is what makes a dead clock visible. */
+/**
+ * Record a run that FAILED.
+ *
+ * Acceptance from the queue item, and the clause most easily skipped: "a
+ * scheduled check reports its FETCH FAILURES, or a broken check is
+ * indistinguishable from a quiet registry". Without this, a clock that fires
+ * every 30 minutes and throws every time leaves NO marks at all — identical on
+ * disk to a clock that was never installed.
+ */
+export function markRunFailure(reason) {
+    mkdirSync(ROOT, { recursive: true });
+    let history = [];
+    try {
+        history = JSON.parse(readFileSync(runFile(), "utf8")).history ?? [];
+    }
+    catch {
+        /* first run */
+    }
+    history.push({ at: Date.now(), hits: 0, checked: 0, failed: reason });
+    writeFileSync(runFile(), JSON.stringify({ history: history.slice(-200) }, null, 2));
+}
+function markRun(result) {
+    mkdirSync(ROOT, { recursive: true });
+    let history = [];
+    try {
+        history = JSON.parse(readFileSync(runFile(), "utf8")).history ?? [];
+    }
+    catch {
+        /* first run */
+    }
+    history.push({ at: Date.now(), hits: result.hits.length, checked: result.checked });
+    // A RUN OF MISSES MUST BE VISIBLE AS RUNS, not as absence — so the marks are a
+    // list, not a single timestamp. "Ten quiet checks" and "one check ten hours ago"
+    // are different states and only the first is a healthy fleet.
+    writeFileSync(runFile(), JSON.stringify({ history: history.slice(-200) }, null, 2));
+}
+export const lastRanSchema = { maxAgeMinutes: z.number().optional() };
+/**
+ * Is the clock alive? Readable by a human or another check, which is the point —
+ * MISS is silent to the duty officer, not to the record.
+ */
+export async function stallClockStatusTool(args) {
+    const maxAge = (args.maxAgeMinutes ?? 60) * 60 * 1000;
+    let history = [];
+    try {
+        history = JSON.parse(readFileSync(runFile(), "utf8")).history ?? [];
+    }
+    catch {
+        return {
+            ok: false,
+            error: "stall_check has NEVER run — no run mark exists. That is not a quiet fleet, it is an unwatched one: a check that only speaks when it fires cannot be told from a broken one.",
+        };
+    }
+    const last = history[history.length - 1];
+    // A RUN THAT FAILED IS NOT A RUN THAT PASSED. Without this the clock reads
+    // "fresh" off a mark it wrote while erroring — the age is honest and the
+    // health is not, which is the same shape as a fresh heartbeat from a stuck
+    // agent.
+    const failures = history.filter((h) => h.failed);
+    const lastFailed = last?.failed;
+    const age = Date.now() - (last?.at ?? 0);
+    // `>=`, NOT `>`, AND THE DIFFERENCE IS A REAL RACE RATHER THAN PEDANTRY.
+    //
+    // With `>`, a window of 0 and a mark written in the SAME MILLISECOND gives
+    // `0 > 0` = false: the clock reads FRESH at the instant it was asked to treat
+    // everything as stale. It passed locally and on one CI run and failed on
+    // another — green in two environments, red in one — because it depended on at
+    // least a millisecond elapsing.
+    //
+    // The window having ELAPSED is the condition, so equality is inside it: a
+    // 0-minute window means nothing is ever fresh, which is what a caller asking
+    // for one means.
+    const stale = age >= maxAge;
+    const misses = history.filter((h) => !h.failed && h.hits === 0).length;
+    const hits = history.filter((h) => !h.failed && h.hits > 0).length;
+    return {
+        // A FAILING CLOCK IS NOT A HEALTHY ONE. It writes marks on schedule, so the
+        // age looks fresh while nothing is being measured — a fresh heartbeat from
+        // a stuck agent, one level up.
+        ok: !stale && !lastFailed,
+        ...(stale
+            ? {
+                error: `stall_check last ran ${Math.round(age / 60000)}m ago, past the ${args.maxAgeMinutes ?? 60}m window — THE CLOCK IS STOPPED. No alerts is not the same as no stalls.`,
+            }
+            : lastFailed
+                ? {
+                    error: `the clock is RUNNING but its last run FAILED: ${lastFailed}. It is firing on schedule and measuring nothing, which reads as fresh and is not.`,
+                }
+                : {}),
+        lastRanMinutesAgo: Math.round(age / 60000),
+        runs: history.length,
+        misses,
+        hits,
+        failures: failures.length,
+    };
+}
+// ---------- the predicate ----------
+export const stallCheckSchema = { repo: z.string().optional(), stallMinutes: z.number().optional() };
+export async function stallCheckTool(args) {
+    const repo = args.repo ?? process.cwd();
+    const limit = (args.stallMinutes ?? 30) * 60 * 1000;
+    const board = path.join(repo, BOARD_DOC);
+    if (!existsSync(board))
+        return { ok: false, error: `no ${BOARD_DOC} under '${repo}'` };
+    const liveTransports = await loadLiveTransports();
+    const rows = workstreamsV1RowsOf(parseWorkDoc(readFileSync(board, "utf8")));
+    const inFlight = rows.filter((r) => /🚧/.test(r.status));
+    const reg = await readJson(AGENTS_FILE, {});
+    const now = Date.now();
+    const hits = [];
+    /** Rows whose VCS activity could not be measured. NOT stall claims. */
+    const unmeasurable = [];
+    for (const row of inFlight) {
+        const agentId = row.owner.replace(/[`*]/g, "").trim();
+        const entry = reg[agentId];
+        if (entry) {
+            const age = now - entry.lastHeartbeat;
+            // A HEARTBEAT IS ONLY EVIDENCE WHERE SOMETHING WRITES ONE.
+            //
+            // `heartbeat` is called by the PUSHER, never by the agent. Only
+            // `coord-pusher.mjs` (the REMOTE pusher) calls it, and it must: a remote
+            // marker cannot be pid-probed across machines, so its liveness IS the
+            // heartbeat. `hooks/tmux-pusher.mjs` — what this fleet actually runs —
+            // never calls it, because a LOCAL marker's liveness is `isPidAlive`.
+            //
+            // So for a local transport there is no heartbeat SOURCE at all. Before
+            // kit#137, `list_agents` stamped these agents and that fabrication was
+            // the only thing keeping the field moving; removing it left the field
+            // honest and empty. Measured: three attached, working agents at an
+            // IDENTICAL 44.7m — the uniform signature of one shared cause, not three
+            // stalls.
+            //
+            // WHY NOT JUST MAKE tmux-pusher HEARTBEAT: because the signal would mean
+            // "the pusher process is alive", which `isPidAlive` already answers for
+            // local markers. During the 17-hour stall every transport was live the
+            // whole time, so a pusher heartbeat would have read FRESH for all 17
+            // hours. It would restore a field without restoring a detector — and the
+            // case this verb exists for is exactly the one it would miss. The vcs
+            // half is what catches "alive and not progressing"; saying so is more
+            // honest than a green field.
+            //
+            // Unknown is not stalled (kit#138). This does NOT narrow Task 3.5: an
+            // 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") {
+                unmeasurable.push({
+                    agentId,
+                    value: marker.transport,
+                    why: `heartbeat is ${Math.round(age / 60000)}m old, but nothing writes heartbeats for a local 'tmux-push' transport — hooks/tmux-pusher.mjs does not call heartbeat, and this marker's liveness is its pid. There is no heartbeat SOURCE here, so the age measures nothing about this agent`,
+                });
+                continue;
+            }
+            if (age > limit) {
+                hits.push({ kind: "no-heartbeat", agentId, stream: row.stream.slice(0, 60), minutes: Math.round(age / 60000) });
+                continue;
+            }
+        }
+        // A FRESH HEARTBEAT IS NOT PROGRESS. An agent can be alive and stuck, which is
+        // the case "notice the room" never catches: the pane is responsive, so nobody
+        // looks. Ask the branch instead.
+        //
+        // RESOLVE A REF, AND SAY SO WHEN THE VALUE IS NOT ONE.
+        //
+        // `git log -1 <value>` accepts a PATHSPEC exactly as readily as a ref, and
+        // the old guard only required a `/` — which every path has. So the board's
+        // `Branch · Worktree` cells, which hold PATHS, were fed to git and silently
+        // measured as paths: the aide was reported at 2,271 minutes, the age of
+        // `docs/phases/phase5`'s last commit, not of any activity by that agent.
+        // Verified: `docs/phases/phase5` does not resolve as a ref, yet
+        // `git log -1 --format=%cI docs/phases/phase5` returns a date.
+        //
+        // Other rows read plausibly only by coincidence — a path that happens to be
+        // committed often looks like an active branch.
+        //
+        // UNKNOWN IS NOT STALLED, which this verb already gets right for
+        // heartbeats. An unresolvable value is REPORTED as unmeasurable rather than
+        // skipped in silence: a silent `continue` and a healthy agent produce the
+        // same output, which is the failure this whole verb exists to avoid.
+        const raw = (row.branchWorktree.match(/`([^`]+)`/)?.[1] ?? "").trim();
+        if (!raw) {
+            unmeasurable.push({ agentId, value: "", why: "no value in the Branch · Worktree cell" });
+            continue;
+        }
+        let sha = "";
+        try {
+            sha = execFileSync("git", ["rev-parse", "--verify", "--quiet", `${raw}^{commit}`], {
+                cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+            }).trim();
+        }
+        catch {
+            sha = "";
+        }
+        if (!sha) {
+            unmeasurable.push({
+                agentId,
+                value: raw,
+                why: `'${raw}' does not resolve as a git ref — it is a path or glob, and \`git log <path>\` would silently report that PATH's last commit as this agent's activity`,
+            });
+            continue;
+        }
+        try {
+            // The resolved SHA, and `--`: a ref can then never be re-read as a
+            // pathspec, which is the ambiguity that produced the wrong number.
+            const iso = execFileSync("git", ["log", "-1", "--format=%cI", sha, "--"], {
+                cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+            }).trim();
+            const age = now - Date.parse(iso);
+            if (age > limit) {
+                hits.push({ kind: "no-vcs-activity", agentId, branch: raw, minutes: Math.round(age / 60000) });
+            }
+        }
+        catch {
+            unmeasurable.push({ agentId, value: raw, why: "resolved as a ref but its log could not be read" });
+        }
+    }
+    const result = { hits, checked: inFlight.length, unmeasurable };
+    markRun(result);
+    return {
+        ok: true,
+        ...result,
+        halted: haltState().halted,
+        // MISS is silent to the DUTY OFFICER — the caller decides whether to DM — and
+        // never silent to the record, which markRun just wrote.
+        dm: hits.length > 0,
+        note: hits.length === 0
+            ? `MISS — ${inFlight.length} in-flight row(s), none stalled${unmeasurable.length ? `; ${unmeasurable.length} row(s) UNMEASURABLE for VCS activity (${unmeasurable.map((u) => u.agentId).join(", ")}) — reported, not counted as healthy` : ""}. No DM. The run IS recorded: read it with stall_clock_status, because no alert and nothing running look identical from here.`
+            : undefined,
+    };
+}
+//# sourceMappingURL=stall.js.map

package/dist/tools/stall.js.map

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

package/dist/tools/transport.js

@@ -1,5 +1,7 @@
 import { loadLiveTransports, isMarkerLive, isPidAlive } from "./registry.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";
 import { registerTool } from "./registry.js";
 import { roleInputSchema } from "../roles.js";
 import { attributeWriter, isGitRepo, lastWriterOf, loadScopes, ownsDocument } from "./scopes.js";
@@ -208,27 +210,72 @@ function defaultReminderText(agentId) {
         `list_rooms() for the channels you're in. Any DM or channel post you receive ` +
         `next is your new task context.`);
 }
+const pendingReminders = new Set();
+/** Reminders whose delivery FAILED, kept so a drop is observable, not stderr-only. */
+export const reminderFailures = [];
+/**
+ * Resolves once every scheduled reminder has been delivered or has failed.
+ *
+ * Re-`ref`s the pending timers for the duration of the wait. The reminder timer
+ * is deliberately `unref`d so it never holds the MCP server open on its own —
+ * but that also means the event loop will not wait for it, and awaiting an
+ * unref'd timer's promise hangs until the loop drains. A caller that has
+ * explicitly asked to wait is stating the opposite intent, so the ref is
+ * restored for exactly that window and dropped again afterwards.
+ *
+ * (The unref has a production consequence worth naming: if the server's
+ * transport closes before the timer fires, the reminder is dropped. That is a
+ * separate defect from the one this function fixes — reported, not silently
+ * papered over.)
+ */
+export function remindersSettled() {
+    const pending = [...pendingReminders];
+    for (const p of pending)
+        p.timer.ref();
+    return Promise.all(pending.map((p) => p.done)).then(() => {
+        for (const p of pending)
+            p.timer.unref();
+    });
+}
 function scheduleReminders(from, recipients, delayMs, override) {
+    // Registered BEFORE the timer fires, so awaiting settlement covers the delay
+    // as well as the write — otherwise a caller could observe "nothing pending"
+    // during the window between scheduling and firing.
+    let markDone = () => { };
+    const done = new Promise((resolve) => { markDone = resolve; });
+    let entry;
     const t = setTimeout(async () => {
-        for (const r of recipients) {
-            try {
-                const reminder = {
-                    id: randomUUID(),
-                    ts: Date.now(),
-                    from,
-                    to: r,
-                    text: override ?? defaultReminderText(r),
-                    // A just-cleared agent is contextless until this lands — it must
-                    // push immediately, never queue behind the routine tier.
-                    urgent: true,
-                };
-                await appendJsonl(inboxFile(r), reminder);
-            }
-            catch (e) {
-                process.stderr.write(`[send_command] post-/clear reminder to '${r}' failed: ${e?.message ?? e}\n`);
+        try {
+            for (const r of recipients) {
+                try {
+                    const reminder = {
+                        id: randomUUID(),
+                        ts: Date.now(),
+                        from,
+                        to: r,
+                        text: override ?? defaultReminderText(r),
+                        // A just-cleared agent is contextless until this lands — it must
+                        // push immediately, never queue behind the routine tier.
+                        urgent: true,
+                    };
+                    await appendJsonl(inboxFile(r), reminder);
+                }
+                catch (e) {
+                    const error = e?.message ?? String(e);
+                    // Recorded, not just printed: a dropped reminder leaves a just-cleared
+                    // agent contextless, and stderr is not somewhere anyone looks for that.
+                    reminderFailures.push({ to: r, error, at: Date.now() });
+                    process.stderr.write(`[send_command] post-/clear reminder to '${r}' failed: ${error}\n`);
+                }
             }
         }
+        finally {
+            pendingReminders.delete(entry);
+            markDone();
+        }
     }, delayMs);
+    entry = { done, timer: t };
+    pendingReminders.add(entry);
     // Don't keep the event loop alive solely for the reminder — the MCP server's
     // transport already holds it open as long as it's connected.
     if (typeof t.unref === "function")
@@ -510,6 +557,11 @@ export async function attachAgentTool(args) {
         // code, and after an in-place rebuild the two differ (that difference is
         // exactly what doctor's provenance check exists to surface).
         serverBuildMtime: SERVER_BUILD_MTIME,
+        // WHAT this transport carries, recorded by the code that decides it.
+        // `includeRoom` is what the pusher is actually spawned with a few lines
+        // above, so the marker cannot claim a capability the process was not
+        // given — the marker and the spawn come from one value, not two.
+        rooms: includeRoom,
     };
     // Use updateJson so it lockfile-protects and creates the file atomically.
     await updateJson(transportFile(args.agentId), marker, () => marker);
@@ -786,6 +838,10 @@ export const reportTransportSchema = {
     // counterpart has been upgraded since. The remote pusher passes
     // `(await fsp.stat(__filename)).mtimeMs`; absent → doctor skips the check.
     scriptMtime: z.number().optional(),
+    // Whether this pusher carries room traffic as well as DMs. Absent → the
+    // marker cannot say, and every reader reports UNKNOWN rather than assuming
+    // a full transport (the worker-2 shape).
+    rooms: z.boolean().optional(),
 };
 // Called by an external push daemon (typically scripts/coord-pusher.mjs on a
 // remote machine) to publish a transport marker so list_agents reflects the
@@ -800,6 +856,7 @@ export async function reportTransportTool(args) {
         host: args.host,
         since: args.since ?? Date.now(),
         scriptMtime: args.scriptMtime,
+        rooms: args.rooms,
     };
     await updateJson(transportFile(args.agentId), marker, () => marker);
     return { ok: true, marker };
@@ -1026,6 +1083,25 @@ export async function doctorTool(args) {
             fixable: false,
         });
     }
+    // 1b³. WHERE A NEW GLOBAL INSTALL WOULD LAND, which is a different question
+    //      from which copy is running (1b² above) and neither substitutes. On
+    //      this box `npm prefix -g` and the fleet's actual load path pointed at
+    //      two different nvm versions, so an install that printed success would
+    //      have updated a copy nothing loads.
+    {
+        const loadPrefix = prefixOf(BUILD_DIR);
+        let installPrefix = null;
+        let npmPath;
+        try {
+            installPrefix = execFileSync("npm", ["prefix", "-g"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+            npmPath = execFileSync("which", ["npm"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+        }
+        catch {
+            installPrefix = null;
+        }
+        const v = prefixVerdict(loadPrefix, installPrefix, npmPath);
+        findings.push({ check: "install-prefix", level: v.level, detail: v.detail, fixable: false });
+    }
     // 1b²ᵇ. The affirmative catch for merged-but-never-rebuilt: src/ newer than
     //       the compiled build means no restart can help — the artifact every
     //       future session will load is already behind the code. Distinct from