agent-coord-mcp 0.26.16 → 0.26.18

package/dist/tools/transport.js

@@ -1,1810 +0,0 @@
-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";
-// Moved to a LEAF so `status` can report capabilities without a cycle — see
-// src/server-identity.ts. Re-exported so every existing importer is untouched.
-export { resolveServerIdentity } from "../server-identity.js";
-import { resolveServerIdentity } from "../server-identity.js";
-// ONE-WAY EDGE, and the direction is the point: `status` CALLS the capabilities
-// verb rather than re-deriving its probes. Two probes of the same thing is the
-// four-matchers defect committed deliberately, which is why 17.4 was deferred
-// behind 13.7 instead of built beside it.
-import { capabilitiesTool } from "../capabilities.js";
-import { sendMessageTool, readMessagesTool } from "./messaging.js";
-import { randomUUID } from "node:crypto";
-import { existsSync, openSync } from "node:fs";
-import { promises as fsp } from "node:fs";
-import { spawn, spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { z } from "zod";
-import path from "node:path";
-import { AGENTS_FILE, CURSOR_DIR, DEFAULT_ROOM, INBOX_DIR, ROOT, ROOM_FILE, ROOMS_DIR, ROOMS_FILE, STATUS_FILE, appendJsonl, cursorFile, deleteFile, ensureRoom, fileSize, getRooms, inboxFile, listCursorFiles, listInboxFiles, listSessionFiles, listTransportFiles, logFile, normalizeRoom, pidFile, readJson, readJsonl, receiptFile, rewriteJsonl, roomFile, transportFile, TRANSPORT_DIR, updateJson, } from "../store.js";
-import { STALE_MS, EVICT_MS, } from "./shared.js";
-// ---------- ping ----------
-export const pingSchema = {
-    from: z.string().min(1),
-    to: z.string().min(1),
-    echo: z.boolean().optional(),
-};
-// Liveness probe answered entirely from server-side state — registry entry,
-// transport marker, pusher pid, tmux pane. It never touches the target's
-// session, so a fleet-wide sweep costs zero model tokens on the targets.
-// Distinct from `heartbeat` (the target refreshing its own activity
-// timestamp): ping is a third party asking "would a DM land right now?".
-// echo=true is the one exception — it drops a PING DM into the target's inbox
-// (normal delivery, so the target's model DOES wake); opt-in, default off.
-export async function pingTool(args) {
-    const t0 = process.hrtime.bigint();
-    const now = Date.now();
-    const latencyMs = () => Math.round(Number(process.hrtime.bigint() - t0) / 1e3) / 1e3;
-    const reg = await readJson(AGENTS_FILE, {});
-    const entry = reg[args.to];
-    if (!entry) {
-        return { ok: true, to: args.to, alive: false, reachable: false, reason: "unregistered", latencyMs: latencyMs() };
-    }
-    const marker = await readJson(transportFile(args.to), null);
-    const heartbeatAgeSec = Math.floor((now - entry.lastHeartbeat) / 1000);
-    const heartbeatFresh = now - entry.lastHeartbeat < STALE_MS;
-    let transportLive = false;
-    let paneAlive;
-    if (marker) {
-        transportLive = isMarkerLive(marker, reg, now);
-        if (transportLive && marker.transport === "tmux-push" && marker.tmuxTarget) {
-            // 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;
-        }
-    }
-    const reachable = transportLive && paneAlive !== false;
-    // heartbeatFresh is only valid EVIDENCE where something writes a heartbeat.
-    // A local tmux-push transport's liveness is its pid (isPidAlive) —
-    // hooks/tmux-pusher.mjs never calls `heartbeat`, so the field measures time
-    // since JOIN, not activity (Task 13.3/13.4, stall.ts's own established
-    // rule for exactly this transport type). Crediting it here for a
-    // tmux-push agent produced the incident this fix exists for: `alive` and
-    // `reachable` read fully healthy, `heartbeatFresh` sat in `checks` reading
-    // false, and the top-line boolean never surfaced the disagreement — a
-    // status layer discarding what its own lower layer already reported, the
-    // 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 alive = reachable || (heartbeatIsValidSignal && heartbeatFresh);
-    let echoSent = false;
-    if (args.echo && alive) {
-        await sendMessageTool({
-            from: args.from,
-            to: args.to,
-            text: `PING: echo requested by ${args.from} — DM back if responsive.`,
-        });
-        echoSent = true;
-    }
-    return {
-        ok: true,
-        to: args.to,
-        alive,
-        reachable,
-        ...(alive ? {} : { reason: marker ? "transport-dead" : "heartbeat-stale" }),
-        checks: {
-            registered: true,
-            heartbeatFresh,
-            heartbeatAgeSec,
-            // Whether heartbeatFresh above is real evidence for this transport, or
-            // just time-since-join. A reader who sees `heartbeatFresh: false` next
-            // to `heartbeatValid: false` should not read that as a dissenting
-            // signal — there is no signal there to dissent.
-            heartbeatValid: heartbeatIsValidSignal,
-            transport: marker?.transport ?? null,
-            transportLive,
-            ...(paneAlive !== undefined ? { paneAlive, tmuxTarget: marker?.tmuxTarget } : {}),
-        },
-        ...(args.echo ? { echoSent } : {}),
-        latencyMs: latencyMs(),
-    };
-}
-// ---------- send_command (context-management control commands) ----------
-// The only slash commands a lead may inject into a sub-agent's CLI. Locked on
-// purpose: these wipe/compact context or reload the harness's own skill files
-// (cheap, reversible-by-the-agent, harness-local), nothing that mutates the repo
-// or the bus. `reload-skills` added 2026-08-19 on a DAVID_DECISION (option 1:
-// that one command only; re-decide per command). Stored WITHOUT the leading
-// slash; the wire text is `/${cmd}`.
-export const CONTROL_COMMANDS = ["clear", "compact", "reload-skills"];
-// 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) {
-    const c = raw.trim().replace(/^\/+/, "").toLowerCase();
-    return CONTROL_COMMANDS.includes(c) ? c : null;
-}
-// Live transports filtered to the tmux-push family (local + remote).
-async function liveTmuxTargets() {
-    const all = await loadLiveTransports();
-    const out = new Map();
-    for (const [id, m] of all)
-        if (TMUX_TRANSPORTS.has(m.transport))
-            out.set(id, m);
-    return out;
-}
-export const sendCommandSchema = {
-    from: z.string().min(1),
-    to: z.string().optional(),
-    room: z.string().optional(),
-    command: z.string().min(1),
-    // Default 3000ms. After /clear, schedules an identity-reminder DM to each
-    // recipient so a freshly-wiped worker re-anchors on its agentId and bus
-    // attach state. Set 0 to opt out. Ignored for non-/clear commands.
-    reminderMs: z.number().int().min(0).max(60_000).optional(),
-    // Override the auto-generated reminder body if you want something specific.
-    reminderText: z.string().optional(),
-    // Block until the receiving pusher confirms it actually typed the command
-    // into the pane (out-of-band receipt poll — zero added agent context).
-    // Default true: a control command you can't confirm is the bug this fixes.
-    // Set false for fire-and-forget. The wait is bounded by deliveryTimeoutMs.
-    waitForDelivery: z.boolean().optional(),
-    deliveryTimeoutMs: z.number().int().min(0).max(30_000).optional(),
-};
-// Poll an agent's receipt log until a receipt for `msgId` appears or the
-// deadline passes. Returns the receipt, or null on timeout. File-only — no
-// agent context.
-//
-// A receipt proves the pusher TYPED the payload into the pane. For a control
-// command that is NOT proof it ran: the command can sit in the input behind an
-// autocomplete menu, delivered and inert. `submitted` is the field that
-// distinguishes them, and `deliveryOutcome` below is the only place allowed to
-// turn a receipt into a "confirmed".
-async function waitForReceipt(agentId, msgId, timeoutMs) {
-    const file = receiptFile(agentId);
-    const deadline = Date.now() + timeoutMs;
-    // First check is immediate; then poll on a short interval.
-    for (;;) {
-        const receipts = await readJsonl(file);
-        const hit = receipts.find((r) => r.id === msgId);
-        if (hit)
-            return { ...hit, ts: hit.ts ?? Date.now() };
-        if (Date.now() >= deadline)
-            return null;
-        await new Promise((res) => setTimeout(res, 150));
-    }
-}
-// Turn a receipt (or its absence) into the delivery verdict for a CONTROL
-// command. Only `submitted === true` earns "confirmed" — anything else is
-// pending with a reason the caller can act on. Reporting an unverified
-// submission as confirmed is the defect this exists to remove: a check that
-// cannot fail loudly is worse than no check.
-//
-// `pusherSourceMtime` (the caller passes newestPusherSourceMtime()) lets a
-// CONFIRMED verdict carry a note when the reporting pusher's build identity
-// is behind the on-disk pusher source, or absent entirely. The note never
-// downgrades the verdict — the command demonstrably ran — it says whose
-// verification logic said so. Absence of the stamp reads as UNKNOWN, never
-// as fresh (same ruling as doctor's stale-pusher-script / provenance
-// checks: absence is not exemption), and the absence note is issued before
-// the on-disk comparison so an unstattable hooks dir cannot silence it.
-export function deliveryOutcome(agentId, receipt, timeoutMs, pusherSourceMtime) {
-    if (!receipt) {
-        return {
-            delivery: "pending",
-            reason: `no delivery receipt from '${agentId}' within ${timeoutMs}ms — the command was written but may not have reached the pane (stale/wedged pusher). Run doctor or re-attach the agent.`,
-        };
-    }
-    if (receipt.submitted === true) {
-        let note;
-        if (receipt.scriptMtime === undefined) {
-            note = `'${agentId}' confirmed the submission, but its pusher carries no build-identity stamp — the pusher predates receipt provenance and this confirmation cannot be tied to any known code; re-attach the agent (detach_agent + attach_agent) to upgrade it.`;
-        }
-        else if (pusherSourceMtime !== undefined && receipt.scriptMtime < pusherSourceMtime - 1) {
-            const loaded = new Date(receipt.scriptMtime).toISOString();
-            const ondisk = new Date(pusherSourceMtime).toISOString();
-            note = `'${agentId}' confirmed the submission, but its pusher loaded its code at ${loaded} and the on-disk pusher source is newer (${ondisk}) — the verification logic behind this confirmation predates the current code; re-attach the agent (detach_agent + attach_agent) to upgrade it.`;
-        }
-        return { delivery: "confirmed", at: receipt.ts, ...(note ? { note } : {}) };
-    }
-    if (receipt.submitted === false) {
-        return {
-            delivery: "pending",
-            at: receipt.ts,
-            reason: receipt.reason ??
-                `'${agentId}' pasted the command but could not confirm it was submitted — it may be sitting in the input.`,
-        };
-    }
-    // No `submitted` field: a pre-v0.19.0 pusher that stamps on paste. It may
-    // well have worked — but it cannot tell us, and guessing "confirmed" is the
-    // lie we are removing. Say what is actually known.
-    return {
-        delivery: "pending",
-        at: receipt.ts,
-        reason: `'${agentId}' typed the command into its pane, but its pusher predates submit verification and cannot confirm the command ran — re-attach the agent (detach_agent + attach_agent) to upgrade it.`,
-    };
-}
-function defaultReminderText(agentId) {
-    return (`[agent-coord] context reset by /clear. ` +
-        `Your bus identity is '${agentId}'. You remain registered and attached — call ` +
-        `status({agentId:"${agentId}"}) to re-orient (role, transport, unread) and ` +
-        `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 () => {
-        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")
-        t.unref();
-}
-// Inject a context-management slash command into a sub-agent's live tmux
-// session. Writes a control-flagged message the pushers deliver RAW (no banner,
-// no `[DM …]` prefix) so the receiving CLI runs it as a real slash command.
-// Hard-gated to tmux: refuses unless the target(s) have a live tmux-push(-remote)
-// transport, so a command never rots unexecuted in an offline inbox.
-export async function sendCommandTool(args) {
-    const cmd = normalizeControlCommand(args.command);
-    if (!cmd) {
-        return {
-            ok: false,
-            error: `unsupported command '${args.command}'. Allowed: ${CONTROL_COMMANDS.map((c) => "/" + c).join(", ")}`,
-        };
-    }
-    if (!args.to && !args.room) {
-        return { ok: false, error: "specify 'to' (a single agent) or 'room' (a channel's tmux-attached members)" };
-    }
-    if (args.to && args.room) {
-        return { ok: false, error: "specify only one of 'to' or 'room'" };
-    }
-    const text = `/${cmd}`;
-    const liveTmux = await liveTmuxTargets();
-    // DM: target must itself be tmux-attached.
-    if (args.to) {
-        const marker = liveTmux.get(args.to);
-        if (!marker) {
-            return {
-                ok: false,
-                error: `'${args.to}' has no live tmux-push transport — control commands can only be injected into a tmux session. Attach it (join/attach_agent) or target an attached agent.`,
-            };
-        }
-        const msg = {
-            id: randomUUID(),
-            ts: Date.now(),
-            from: args.from,
-            to: args.to,
-            text,
-            control: true,
-        };
-        const target = inboxFile(args.to);
-        await appendJsonl(target, msg);
-        // Confirm the pusher actually typed it into the pane before we report success
-        // (unless explicitly fire-and-forget). Out-of-band receipt poll — the
-        // confirmation rides back in THIS tool result, costing no extra agent context.
-        const wait = args.waitForDelivery ?? true;
-        const deliveryTimeoutMs = args.deliveryTimeoutMs ?? 8000;
-        const receipt = wait ? await waitForReceipt(args.to, msg.id, deliveryTimeoutMs) : null;
-        const outcome = wait ? deliveryOutcome(args.to, receipt, deliveryTimeoutMs, newestPusherSourceMtime()) : null;
-        const confirmed = outcome?.delivery === "confirmed";
-        // After /clear the receiver forgets its identity and that it's bus-attached
-        // (the system prompt isn't re-applied because /clear isn't a session
-        // start). Schedule a follow-up DM as a re-anchor; opt out with reminderMs:0.
-        const reminderMs = cmd === "clear" ? args.reminderMs ?? 3000 : 0;
-        if (reminderMs > 0)
-            scheduleReminders(args.from, [args.to], reminderMs, args.reminderText);
-        return {
-            ok: true,
-            id: msg.id,
-            command: text,
-            target,
-            delivered: [args.to],
-            transport: marker.transport,
-            // delivery: confirmed = pusher typed it into the pane; pending = written but
-            // unconfirmed within the timeout (stale/wedged pusher — run doctor). Absent
-            // when waitForDelivery:false.
-            ...(wait && outcome
-                ? {
-                    delivery: outcome.delivery,
-                    confirmed,
-                    ...(outcome.at !== undefined ? { deliveredAt: outcome.at } : {}),
-                    // A confirmed delivery can still warn: the note names a reporting
-                    // pusher whose build identity is stale or absent. `confirmed`
-                    // stays true — the command ran; the warning is about who said so.
-                    ...(confirmed ? (outcome.note ? { warning: outcome.note } : {}) : { warning: outcome.reason }),
-                }
-                : {}),
-            ...(reminderMs > 0 ? { reminderScheduled: { delayMs: reminderMs, recipients: [args.to] } } : {}),
-        };
-    }
-    // Room: broadcast to every tmux-attached member (never the sender itself).
-    const chan = normalizeRoom(args.room);
-    const rooms = await getRooms();
-    const members = rooms[chan]?.members ?? [];
-    const delivered = members.filter((m) => m !== args.from && liveTmux.has(m));
-    if (delivered.length === 0) {
-        return {
-            ok: false,
-            error: `no tmux-attached members in #${chan} to receive '${text}' (${members.length} member(s) total). Control commands only fire in a live tmux session.`,
-        };
-    }
-    const skipped = members.filter((m) => m !== args.from && !liveTmux.has(m));
-    const msg = {
-        id: randomUUID(),
-        ts: Date.now(),
-        from: args.from,
-        room: chan,
-        text,
-        control: true,
-    };
-    const target = roomFile(chan);
-    await appendJsonl(target, msg);
-    // Confirm each member's pusher typed it in (same msg.id lands in every
-    // member's own receipt file). Poll all in parallel within one timeout.
-    const wait = args.waitForDelivery ?? true;
-    const deliveryTimeoutMs = args.deliveryTimeoutMs ?? 8000;
-    let confirmed = [];
-    let pending = [];
-    let pendingReasons = [];
-    let confirmNotes = [];
-    if (wait) {
-        const sourceMtime = newestPusherSourceMtime();
-        const results = await Promise.all(delivered.map(async (m) => ({
-            m,
-            outcome: deliveryOutcome(m, await waitForReceipt(m, msg.id, deliveryTimeoutMs), deliveryTimeoutMs, sourceMtime),
-        })));
-        confirmed = results.filter((r) => r.outcome.delivery === "confirmed").map((r) => r.m);
-        pending = results.filter((r) => r.outcome.delivery !== "confirmed").map((r) => r.m);
-        pendingReasons = results
-            .filter((r) => r.outcome.delivery !== "confirmed")
-            .map((r) => `${r.m}: ${r.outcome.reason}`);
-        confirmNotes = results
-            .filter((r) => r.outcome.delivery === "confirmed" && r.outcome.note)
-            .map((r) => r.outcome.note);
-    }
-    // Same post-/clear re-anchor as the DM path — one reminder per delivered
-    // member, in their own inbox, with their own agentId in the body.
-    const reminderMs = cmd === "clear" ? args.reminderMs ?? 3000 : 0;
-    if (reminderMs > 0)
-        scheduleReminders(args.from, delivered, reminderMs, args.reminderText);
-    return {
-        ok: true,
-        id: msg.id,
-        command: text,
-        target,
-        room: chan,
-        delivered,
-        skipped: skipped.length ? skipped : undefined,
-        ...(wait
-            ? {
-                delivery: pending.length === 0 ? "confirmed" : "partial",
-                confirmed,
-                ...(pending.length
-                    ? {
-                        pending,
-                        warning: `not confirmed as submitted within ${deliveryTimeoutMs}ms — ${pendingReasons.join(" | ")}`,
-                    }
-                    : {}),
-                // Confirmed members whose reporting pusher is stale or unstamped —
-                // the confirmations stand, the notes say whose code issued them.
-                ...(confirmNotes.length ? { notes: confirmNotes } : {}),
-            }
-            : {}),
-        ...(reminderMs > 0 ? { reminderScheduled: { delayMs: reminderMs, recipients: delivered } } : {}),
-    };
-}
-// Does `pid` actually belong to one of our tmux pushers? A transport marker
-// records a pid, but a marker can outlive its process and pids get recycled —
-// so "pid is alive" is NOT evidence the pid is still the pusher. Anything that
-// SIGTERMs a marker's pid must confirm identity first or it will eventually
-// kill an unrelated process on the user's machine.
-//
-// Pushers are spawned as `<node> <.../hooks/tmux-pusher.mjs>` (see
-// attachAgentTool), so the script path in the process's argv is the signature.
-// Returns false when we cannot confirm — including when `ps` is unavailable.
-// Refusing to kill an unverifiable pid is the safe failure: a wedged pusher
-// that survives is a nuisance, a wrong SIGTERM is not.
-export function isPusherProcess(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    const ps = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8" });
-    if (ps.status !== 0)
-        return false; // pid gone, or no usable ps
-    return (ps.stdout ?? "").includes(path.basename(resolvePusherPath()));
-}
-// ---------- attach_agent / detach_agent (tmux push transport) ----------
-export const attachAgentSchema = {
-    agentId: z.string().min(1),
-    tmuxTarget: z.string().optional(),
-    includeRoom: z.boolean().optional(),
-    allowlist: z.array(z.string()).optional(),
-    debounceMs: z.number().int().positive().max(60_000).optional(),
-};
-export async function attachAgentTool(args) {
-    // Resolve target: explicit arg > MCP server's own TMUX_PANE env.
-    const target = args.tmuxTarget ?? process.env.TMUX_PANE;
-    if (!target) {
-        return {
-            ok: false,
-            error: "tmuxTarget not provided and the MCP server is not running inside tmux (no $TMUX_PANE). Pass tmuxTarget explicitly (e.g. '%42' or 'session:window.pane').",
-        };
-    }
-    // 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) {
-        return {
-            ok: false,
-            error: `tmux target '${target}' not found: ${(probe.stderr ?? "").toString().trim()}`,
-        };
-    }
-    // If something's already attached, refuse rather than spawn a second pusher.
-    const existing = await readJson(transportFile(args.agentId), null);
-    if (existing && isPidAlive(existing.pid)) {
-        return {
-            ok: false,
-            error: `agent '${args.agentId}' already has a live ${existing.transport} attached (pid ${existing.pid}). Call detach_agent first.`,
-            existing,
-        };
-    }
-    // Clean up dead marker, if any.
-    if (existing)
-        await deleteFile(transportFile(args.agentId));
-    const pusher = resolvePusherPath();
-    if (!existsSync(pusher)) {
-        return { ok: false, error: `tmux-pusher not found at ${pusher}` };
-    }
-    // Detached spawn so the pusher outlives this MCP request/process.
-    const log = logFile(args.agentId, "pusher");
-    await fsp.mkdir(path.dirname(log), { recursive: true });
-    await fsp.mkdir(path.dirname(pidFile(args.agentId, "pusher")), { recursive: true });
-    await fsp.mkdir(path.dirname(transportFile(args.agentId)), { recursive: true });
-    const logFd = openSync(log, "a");
-    // Default: deliver room broadcasts too. The bus is chat-first — silence on
-    // a room post is a worse failure mode than a slightly noisier pane. Callers
-    // who want DM-only can pass includeRoom:false explicitly.
-    const includeRoom = args.includeRoom !== false;
-    // Use the exact node binary running this server, not bare "node" — the MCP
-    // server is often launched via an absolute path (nvm/Homebrew/bundled
-    // runtime) that isn't on the spawned child's PATH, which would silently fail
-    // the pusher launch ("attached but nothing arrives").
-    // `--agent <id>` is inert to the pusher (env stays authoritative) but puts
-    // the agentId in argv, so a pattern kill can be scoped to ONE pusher
-    // (`pkill -f "tmux-pusher.mjs --agent <id>"`). Without it the only matchable
-    // pattern was the script path, and a `pkill -f tmux-pusher.mjs` during one
-    // agent's cleanup silently detached every live agent on the bus (2026-07-28).
-    const child = spawn(process.execPath, [pusher, "--agent", args.agentId], {
-        detached: true,
-        stdio: ["ignore", logFd, logFd],
-        env: {
-            ...process.env,
-            AGENT_COORD_ID: args.agentId,
-            AGENT_COORD_TMUX_TARGET: target,
-            ...(includeRoom ? { AGENT_COORD_INCLUDE_ROOM: "1" } : {}),
-            ...(args.allowlist && args.allowlist.length > 0
-                ? { AGENT_COORD_ALLOWLIST: args.allowlist.join(",") }
-                : {}),
-            ...(args.debounceMs ? { AGENT_COORD_DEBOUNCE_MS: String(args.debounceMs) } : {}),
-        },
-    });
-    child.unref();
-    const pid = child.pid;
-    if (!pid)
-        return { ok: false, error: "spawn returned no pid" };
-    // Write pid file (for scripts) and transport marker (for list_agents).
-    await fsp.writeFile(pidFile(args.agentId, "pusher"), String(pid), "utf8");
-    // Stamp the pusher source's freshness so doctor() can flag a stale daemon if
-    // it outlives a later upgrade of the on-disk code (see v0.8.1 → v0.8.2 bug
-    // report: control commands silently dropped by pre-v0.8 in-memory code).
-    const scriptMtime = newestPusherSourceMtime();
-    const marker = {
-        agentId: args.agentId,
-        transport: "tmux-push",
-        pid,
-        tmuxTarget: target,
-        since: Date.now(),
-        scriptMtime,
-        // Provenance: the build identity THIS server loaded at startup — not a
-        // fresh stat of dist/, because the code doing the stamping is the loaded
-        // 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);
-    // Best-effort scan for a peek-coord.mjs hook wired to the same agentId —
-    // both consumers share the cursor file and would race / double-deliver.
-    const conflictingHook = await detectPeekCoordHook(args.agentId);
-    return {
-        ok: true,
-        agentId: args.agentId,
-        transport: "tmux-push",
-        tmuxTarget: target,
-        pid,
-        log,
-        ...(conflictingHook
-            ? {
-                warnings: [
-                    `peek-coord.mjs hook for agentId='${args.agentId}' detected in ${conflictingHook}. ` +
-                        `Running both transports causes double-delivery — disable one. ` +
-                        `Recommend removing the peek-coord hook entry since tmux-push supersedes it.`,
-                ],
-            }
-            : {}),
-    };
-}
-async function detectPeekCoordHook(agentId) {
-    const home = process.env.HOME ?? "";
-    const cwd = process.cwd();
-    const candidates = [
-        path.join(home, ".claude", "settings.json"),
-        path.join(home, ".claude", "settings.local.json"),
-        path.join(cwd, ".claude", "settings.json"),
-        path.join(cwd, ".claude", "settings.local.json"),
-    ];
-    for (const file of candidates) {
-        if (!existsSync(file))
-            continue;
-        try {
-            const raw = await fsp.readFile(file, "utf8");
-            if (raw.includes("peek-coord.mjs") && raw.includes(`AGENT_COORD_ID=${agentId}`)) {
-                return file;
-            }
-        }
-        catch {
-            // unreadable, skip
-        }
-    }
-    return undefined;
-}
-export const detachAgentSchema = {
-    agentId: z.string().min(1),
-};
-export async function detachAgentTool(args) {
-    const marker = await readJson(transportFile(args.agentId), null);
-    let killed = false;
-    let unverified = false;
-    if (marker && isPidAlive(marker.pid)) {
-        // ALIVE IS NOT ENOUGH — VERIFY IT IS A PUSHER BEFORE SIGNALLING IT.
-        //
-        // A pid is only meaningful while the process that owned it is running: pids
-        // are recycled, and a stale marker pointing at a recycled pid makes this a
-        // SIGTERM at an unrelated process. Doctor's reaper already gates its kill on
-        // `isPusherProcess` for exactly this reason (see the wedged-pusher fix); this
-        // path never took the correction, and `unregister`/`quit` inherit it.
-        //
-        // UNVERIFIABLE MEANS CLEAR THE MARKER, NEVER SIGNAL. The marker is ours to
-        // delete and the process is not ours to kill — those are different
-        // authorities, and conflating them is how a detach becomes someone else's
-        // outage. Reported rather than silent, so a pusher that genuinely needs
-        // killing is not left running unnoticed.
-        if (isPusherProcess(marker.pid)) {
-            try {
-                process.kill(marker.pid, "SIGTERM");
-                killed = true;
-            }
-            catch {
-                // already gone
-            }
-        }
-        else {
-            unverified = true;
-        }
-    }
-    await deleteFile(transportFile(args.agentId));
-    await deleteFile(pidFile(args.agentId, "pusher"));
-    return {
-        ok: true,
-        agentId: args.agentId,
-        killed,
-        hadMarker: marker !== null,
-        ...(unverified
-            ? {
-                warning: `pid ${marker.pid} is alive but is NOT a pusher process — the marker was cleared and NOTHING was signalled. ` +
-                    `A stale marker pointing at a recycled pid would otherwise make this a SIGTERM at an unrelated process. ` +
-                    `If a pusher is still running for '${args.agentId}', find it with \`doctor\` and let its reaper handle it.`,
-            }
-            : {}),
-    };
-}
-function resolvePusherPath() {
-    // transport.js (compiled) lives in dist/tools/; pusher lives in hooks/ at repo root.
-    const here = path.dirname(fileURLToPath(import.meta.url));
-    return path.resolve(here, "..", "..", "hooks", "tmux-pusher.mjs");
-}
-/** An epoch-ms stamp as ISO-8601 UTC, or an explicit absence — never a blank. */
-function stamp(ms) {
-    return ms === undefined ? "(no stamp)" : new Date(ms).toISOString();
-}
-// Freshness basis for the stale-pusher-script mechanism: the newest mtime
-// across the pusher's source dir (hooks/*.mjs), NOT just the entry file. The
-// pusher imports submit.mjs / tier.mjs / roles.mjs, so a fix touching only an
-// import (the #21/#25 control-submit fixes did) leaves tmux-pusher.mjs's own
-// mtime unchanged — a single-file stamp/compare reports ok on a pusher running
-// exactly the code the fix replaced. Used by both the attach-time stamp and
-// doctor's on-disk comparison so the two sides can never drift apart.
-// AGENT_COORD_HOOKS_DIR is a test seam only: it redirects what freshness
-// MEASURES (against a temp copy of hooks/) so tests never touch the mtimes of
-// real sources shared with live pushers — it never changes what attach SPAWNS.
-function newestPusherSourceMtime() {
-    const dir = process.env.AGENT_COORD_HOOKS_DIR ?? path.dirname(resolvePusherPath());
-    return newestMtimeUnder(dir, [".mjs"]);
-}
-// ---------- status / whoami ----------
-export const statusSchema = { agentId: z.string().min(1) };
-export async function statusTool(args) {
-    const reg = await readJson(AGENTS_FILE, {});
-    const entry = reg[args.agentId];
-    const transports = await loadLiveTransports();
-    const transport = transports.get(args.agentId);
-    const inbox = await readJsonl(inboxFile(args.agentId));
-    const cursor = await readJson(cursorFile(args.agentId), {});
-    const inboxOffset = cursor.inboxOffset ?? 0;
-    const unread = Math.max(0, inbox.length - inboxOffset);
-    // WHAT THIS PROCESS CAN ACTUALLY DO, embedded WHOLE.
-    //
-    // A new tool otherwise lands silently: an agent reading an old listing
-    // asserts the tool does not exist, and it is right about its own listing and
-    // wrong about the world. Three wrong conclusions in two days came from
-    // exactly that, each about which build a pane was running.
-    //
-    // The full report travels, not a summary. Flattening it to a boolean would
-    // hand the caller a tidier answer and a worse one: `versionLabel` stays
-    // CONTEXT rather than evidence, a THROWN probe stays an absent capability
-    // rather than a broken check, and `answeredBy` keeps naming which pid
-    // answered — two servers disagreeing mid-rollout is the normal case, and it
-    // is the case every other instrument here reports as if the fleet were one
-    // thing.
-    const capabilities = await capabilitiesTool();
-    return {
-        agentId: args.agentId,
-        registered: !!entry,
-        entry,
-        attached: !!transport,
-        transport,
-        inboxDepth: inbox.length,
-        inboxUnread: unread,
-        inTmux: !!process.env.TMUX_PANE,
-        tmuxPane: process.env.TMUX_PANE,
-        capabilities,
-    };
-}
-// ---------- join (combo: register + auto-attach + read inbox) ----------
-const joinAttachOptionsSchema = z.object({
-    tmuxTarget: z.string().optional(),
-    includeRoom: z.boolean().optional(),
-    allowlist: z.array(z.string()).optional(),
-    debounceMs: z.number().int().positive().max(60_000).optional(),
-});
-export const joinSchema = {
-    agentId: z.string().min(1),
-    project: z.string().optional(),
-    // Free text, or a declared identity ({roleId, displayName}) — see
-    // roleInputSchema. A frozen roleId cannot be changed by re-joining.
-    role: roleInputSchema.optional(),
-    // attach: undefined → auto-attach if $TMUX_PANE is set; true → always try;
-    // false → never; object → attach with overrides.
-    attach: z.union([z.boolean(), joinAttachOptionsSchema]).optional(),
-    readInbox: z.boolean().optional(),
-    // First-claim guard overrides (server.ts guardFirstClaim): claiming an id
-    // that is LIVE on the bus refuses unless the call presents that agent's
-    // token (tokens.json / coord-token) or force:true. Ignored once bound.
-    token: z.string().optional(),
-    force: z.boolean().optional(),
-    // Prose-only exemption from the typed-record rule — see registerSchema.
-    // Declared here too because `join` is the call every card actually makes.
-    proseOnly: z.union([z.boolean(), z.object({ reason: z.string().min(1) })]).optional(),
-};
-export async function joinTool(args) {
-    const reg = await registerTool({
-        agentId: args.agentId,
-        project: args.project,
-        role: args.role,
-        proseOnly: args.proseOnly,
-    });
-    // A refused role update (frozen roleId) fails the whole join rather than
-    // silently attaching a transport under the wrong identity.
-    if (!reg.ok)
-        return reg;
-    // Decide attach behavior.
-    const wantAttach = args.attach === false
-        ? false
-        : args.attach === true || typeof args.attach === "object"
-            ? true
-            : !!process.env.TMUX_PANE; // undefined → auto-detect
-    // Always present as object | null so callers can branch on a single key
-    // instead of "did I pass attach?" — per agent-pa's API review.
-    let attach = null;
-    if (wantAttach) {
-        const opts = typeof args.attach === "object" ? args.attach : {};
-        attach = await attachAgentTool({ agentId: args.agentId, ...opts });
-    }
-    const readInbox = args.readInbox ?? true;
-    let inbox = null;
-    if (readInbox) {
-        inbox = await readMessagesTool({ agentId: args.agentId, source: "inbox" });
-    }
-    // Surface the default channel's topic + MOTD (room rules) in the same
-    // round-trip, so a connecting agent sees them without a separate call.
-    const rooms = await getRooms();
-    const def = rooms[DEFAULT_ROOM];
-    return {
-        ok: true,
-        registered: reg.agent,
-        attached: !!attach && attach.ok !== false,
-        attach,
-        inbox,
-        defaultRoom: { room: DEFAULT_ROOM, topic: def?.topic, motd: def?.motd },
-        inTmux: !!process.env.TMUX_PANE,
-    };
-}
-// ---------- transport markers (for remote pushers) ----------
-export const reportTransportSchema = {
-    agentId: z.string().min(1),
-    transport: z.string().min(1),
-    tmuxTarget: z.string().optional(),
-    host: z.string().optional(),
-    since: z.number().optional(),
-    // mtime of the script the remote daemon loaded into memory at spawn time
-    // (epoch ms). Lets doctor() flag the remote pusher as stale if its on-disk
-    // 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
-// attachment. The local tmux-push path writes the marker directly inside
-// attach_agent; this is the wire-callable equivalent for remote pushers.
-export async function reportTransportTool(args) {
-    const marker = {
-        agentId: args.agentId,
-        transport: args.transport,
-        pid: 0, // not meaningful for remote; liveness comes from heartbeat
-        tmuxTarget: args.tmuxTarget,
-        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 };
-}
-export const clearTransportSchema = {
-    agentId: z.string().min(1),
-};
-// Idempotent remote-counterpart to detach_agent: just deletes the marker. Used
-// by the remote pusher on graceful shutdown so list_agents stops showing it
-// attached. (Does NOT try to kill any process — there's nothing local to kill.)
-export async function clearTransportTool(args) {
-    const removed = await deleteFile(transportFile(args.agentId));
-    return { ok: true, removed };
-}
-export const reportReceiptSchema = {
-    agentId: z.string().min(1),
-    id: z.string().min(1),
-    from: z.string().optional(),
-    control: z.boolean().optional(),
-    submitted: z.boolean().optional(),
-    verified: z.boolean().optional(),
-    reason: z.string().optional(),
-    // Build identity of the reporting pusher: newest mtime across its loaded
-    // module graph (entry file + hooks/ imports), sampled once at its startup —
-    // the same basis report_transport's scriptMtime uses. Absent → the receipt's
-    // provenance is UNKNOWN and deliveryOutcome says so; the server never
-    // defaults it (a default here would be assume-fresh, the twin of the
-    // assume-success `submitted` refuses to invent).
-    scriptMtime: z.number().optional(),
-};
-// Wire-callable counterpart to the local pusher's receipt stamp (writeReceipts
-// in hooks/tmux-pusher.mjs). A remote pusher types into a pane on ANOTHER
-// machine and cannot append to this host's receipts/<id>.jsonl, so before this
-// existed a control command to a tmux-push-remote agent was never confirmable:
-// send_command waited out deliveryTimeoutMs and reported delivery:"pending"
-// even when the command demonstrably ran.
-//
-// The receipt is appended in the exact shape the local pusher writes, so
-// waitForReceipt/deliveryOutcome need no remote-specific branch. `submitted`
-// is recorded only when the caller reports it — absence means "typed but
-// unverified", which deliveryOutcome refuses to call confirmed. The server
-// cannot see the remote pane, so it stores what the pusher observed and
-// nothing more; defaulting the field here would recreate assume-success one
-// layer up. Trust matches report_transport: the identity gate binds agentId
-// to the session, so a pusher can only stamp its own agent's receipt file.
-export async function reportReceiptTool(args) {
-    const receipt = {
-        id: args.id,
-        agentId: args.agentId,
-        ts: Date.now(),
-        ...(args.from !== undefined ? { from: args.from } : {}),
-        control: args.control === true,
-        ...(args.submitted !== undefined ? { submitted: args.submitted } : {}),
-        ...(args.verified !== undefined ? { verified: args.verified } : {}),
-        ...(args.reason !== undefined ? { reason: args.reason } : {}),
-        ...(args.scriptMtime !== undefined ? { scriptMtime: args.scriptMtime } : {}),
-    };
-    await appendJsonl(receiptFile(args.agentId), receipt);
-    return { ok: true, receipt };
-}
-// Count non-empty lines vs successfully-parsed entries in a JSONL file.
-// Offsets index the PARSED entries (see readJsonl), so `parsed` is the figure
-// cursor math is compared against; `malformed` is the desync risk.
-async function scanJsonl(file) {
-    if (!existsSync(file))
-        return { lines: 0, parsed: 0, malformed: 0 };
-    const raw = await fsp.readFile(file, "utf8");
-    let lines = 0;
-    let parsed = 0;
-    for (const line of raw.split("\n")) {
-        if (!line.trim())
-            continue;
-        lines++;
-        try {
-            JSON.parse(line);
-            parsed++;
-        }
-        catch {
-            // malformed
-        }
-    }
-    return { lines, parsed, malformed: lines - parsed };
-}
-// Find leftover proper-lockfile lock dirs (`<file>.lock`) across the state
-// dirs. Anything older than the threshold is almost certainly orphaned by a
-// crashed writer (withLock's stale window is 5s).
-async function scanStaleLocks(olderThanMs, now) {
-    const out = [];
-    const dirs = [ROOT, INBOX_DIR, CURSOR_DIR, ROOMS_DIR, TRANSPORT_DIR];
-    for (const dir of dirs) {
-        if (!existsSync(dir))
-            continue;
-        let names;
-        try {
-            names = await fsp.readdir(dir);
-        }
-        catch {
-            continue;
-        }
-        for (const name of names) {
-            if (!name.endsWith(".lock"))
-                continue;
-            const p = path.join(dir, name);
-            try {
-                const st = await fsp.stat(p);
-                const ageMs = now - st.mtimeMs;
-                if (ageMs > olderThanMs)
-                    out.push({ path: p, ageMs });
-            }
-            catch {
-                // vanished mid-scan
-            }
-        }
-    }
-    return out;
-}
-export const doctorSchema = {
-    fix: z.boolean().optional(),
-    maxFileBytes: z.number().int().positive().optional(),
-};
-export async function doctorTool(args) {
-    const fix = args.fix ?? false;
-    const maxBytes = args.maxFileBytes ?? 5 * 1024 * 1024;
-    const now = Date.now();
-    const findings = [];
-    const fixed = [];
-    const reg = await readJson(AGENTS_FILE, {});
-    const known = new Set(Object.keys(reg));
-    const rooms = await getRooms();
-    const channels = Object.keys(rooms);
-    // 1. Orphan transport markers (dead local pid, or stale remote heartbeat).
-    {
-        const dead = [];
-        for (const fname of await listTransportFiles()) {
-            const file = path.join(TRANSPORT_DIR, fname);
-            const marker = await readJson(file, null);
-            if (!marker || !isMarkerLive(marker, reg, now)) {
-                dead.push(file);
-                if (fix) {
-                    await deleteFile(file);
-                    fixed.push(`deleted stale transport marker ${fname}`);
-                }
-            }
-        }
-        findings.push({
-            check: "orphan-transport-markers",
-            level: dead.length ? "warn" : "ok",
-            detail: dead.length ? `${dead.length} stale transport marker(s) (dead pid or expired remote heartbeat)` : "no stale transport markers",
-            fixable: true,
-            items: dead.length ? dead.map((f) => path.basename(f)) : undefined,
-        });
-    }
-    // 1b. Stale pusher daemons — a long-running pusher loaded its script into
-    //     memory at spawn time, so when the on-disk script is later upgraded
-    //     (npm i -g a new version), the still-running pid is on the OLD code.
-    //     Pre-v0.8.2 pushers had no `control:true` awareness and silently
-    //     dropped /clear /compact at the slash-guard — ack:true with no
-    //     keystrokes ever reaching the pane. Comparing the marker's stamped
-    //     scriptMtime against the newest on-disk mtime across hooks/*.mjs
-    //     catches it — the whole module graph, not just the entry file, because
-    //     the control-submit logic lives in submit.mjs and a fix landing there
-    //     alone leaves tmux-pusher.mjs's mtime (and a single-file stamp) intact.
-    //     Local tmux-push only — for tmux-push-remote the script lives on a
-    //     different host so we can't stat it from here.
-    {
-        const localPusherMtime = newestPusherSourceMtime();
-        const stale = [];
-        const unverifiable = [];
-        for (const fname of await listTransportFiles()) {
-            const file = path.join(TRANSPORT_DIR, fname);
-            const marker = await readJson(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 (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
-                // thing it monitors — a live pusher we cannot verify is a warn, not
-                // an ok (credit agent-coordination-david-dev). Same flip, same
-                // commit, as serverBuildMtime below: the two checks must never
-                // disagree about what absence means.
-                unverifiable.push(`${marker.agentId} (pid ${marker.pid}, no scriptMtime stamp — cannot verify; detach_agent + attach_agent to re-stamp)`);
-                continue;
-            }
-            if (localPusherMtime === undefined)
-                continue;
-            if (marker.scriptMtime < localPusherMtime - 1) { // -1ms slack for fs mtime rounding
-                const loaded = new Date(marker.scriptMtime).toISOString();
-                const ondisk = new Date(localPusherMtime).toISOString();
-                stale.push(`${marker.agentId} (pid ${marker.pid}, loaded ${loaded}, on-disk now ${ondisk})`);
-            }
-        }
-        const bad = [...stale, ...unverifiable];
-        findings.push({
-            check: "stale-pusher-script",
-            level: bad.length ? "warn" : "ok",
-            detail: bad.length
-                ? `${stale.length} attached pusher(s) running pre-upgrade code and ${unverifiable.length} whose freshness cannot be verified (no stamp) — control commands (/clear, /compact) may be silently dropped. Run detach_agent + attach_agent for each, or have the agent relaunch.`
-                : "all attached pushers are running the current on-disk script",
-            fixable: false,
-            items: bad.length ? bad : undefined,
-        });
-    }
-    // 1b². The same staleness class one layer up: doctor itself runs inside an
-    //      MCP server process that imported dist/ at startup. `npm run build`
-    //      rewrites dist/ under the still-running server, which then keeps
-    //      spawning pushers and stamping markers with logic the rebuild
-    //      replaced — merging is not deploying, and until the session restarts
-    //      no on-disk artifact reflects what this process will actually do.
-    //      Self-scoped by construction: each session's doctor reports on the
-    //      server it is running in, which is the only process whose loaded
-    //      build it can truthfully know.
-    {
-        const onDisk = onDiskBuildMtime();
-        const drifted = SERVER_BUILD_MTIME !== undefined && onDisk !== undefined && SERVER_BUILD_MTIME < onDisk - 1;
-        const identity = `${SERVER_BUILD_SHA ?? "unknown-sha"} @ ${BUILD_DIR}`;
-        findings.push({
-            check: "server-build-drift",
-            level: drifted ? "warn" : "ok",
-            detail: drifted
-                ? `this MCP server loaded its build at ${new Date(SERVER_BUILD_MTIME).toISOString()} but the on-disk build is newer (${new Date(onDisk).toISOString()}) — the session is running pre-rebuild code and everything it stamps or spawns uses replaced logic. Restart this agent's session. (${identity})`
-                : `server is running the current on-disk build (${identity})`,
-            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
-    //       1b² (a process behind its dist); this is the DISK being behind
-    //       itself, which is why it can fire on a bus with zero live sessions.
-    //       Not inferred from marker state: both sides are statted directly.
-    {
-        const srcMtime = onDiskSourceMtime();
-        const distMtime = onDiskBuildMtime();
-        const behind = srcMtime !== undefined && distMtime !== undefined && distMtime < srcMtime - 1;
-        findings.push({
-            check: "dist-behind-source",
-            level: behind ? "warn" : "ok",
-            detail: behind
-                ? `src/ is newer than the compiled build (src ${new Date(srcMtime).toISOString()}, dist ${new Date(distMtime).toISOString()}) — the checkout was updated but never rebuilt, so every session (current and future) runs pre-update code. \`npm run build\`, then restart sessions.`
-                : srcMtime === undefined
-                    ? "no src/ to compare (packaged install) — dist is the only artifact"
-                    : "compiled build is at least as new as src/",
-            fixable: false,
-        });
-    }
-    // 1b³. Marker provenance — which server BUILD stamped each marker. A live
-    //      pusher can be perfectly fresh while the marker's stamps were
-    //      computed by an outdated server (observed live 2026-07-29: a stale
-    //      server's attach stamped single-file freshness that agreed with the
-    //      new on-disk check only because tmux-pusher.mjs happened to be the
-    //      newest hooks file). Local tmux-push only, same as 1b.
-    {
-        const onDisk = onDiskBuildMtime();
-        const unverifiable = [];
-        for (const fname of await listTransportFiles()) {
-            const file = path.join(TRANSPORT_DIR, fname);
-            const marker = await readJson(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 (marker.serverBuildMtime === undefined) {
-                // ABSENCE IS NOT EXEMPTION — flipped in the same commit as the
-                // scriptMtime absence above, so the two checks can never disagree
-                // about what a missing stamp means. An unstamped marker was written
-                // by a pre-provenance server (or by hand): precisely the population
-                // this check exists to police, and the one it must not exempt.
-                // Transition is deliberately correct-and-loud: after the upgrade,
-                // every pre-existing marker warns at once, each cleared by a session
-                // restart + re-attach — the burst is also the only external view of
-                // which sessions still run pre-provenance servers, since a stale
-                // server cannot self-report (see 1b²).
-                unverifiable.push(`${marker.agentId} (no serverBuildMtime stamp — stamped by a pre-provenance server; restart that session, then detach_agent + attach_agent)`);
-                continue;
-            }
-            if (onDisk === undefined)
-                continue;
-            if (marker.serverBuildMtime < onDisk - 1) {
-                // A COMPONENT CAN REPORT ITS OWN FRESHNESS; A SIBLING'S RECORD OF IT
-                // GOES STALE SILENTLY. That asymmetry is the whole correction here.
-                //
-                // `serverBuildMtime` is stamped inside `attach_agent` — by the PUSHER's
-                // attach, once — so it records what the server was AT THE LAST ATTACH.
-                // A server-only restart (David's `/mcp`) reloads the server and touches
-                // no marker, so this stamp cannot be refreshed by the thing it
-                // describes and CANNOT DISTINGUISH a restarted server from an
-                // un-restarted one.
-                //
-                // Measured on three agents: each answered `list_subscriptions` — a tool
-                // that does not exist before 0.26.7 — while its marker still stamped a
-                // pre-0.26.7 build. The stamp was 2.2 hours behind the installed dist
-                // on a server demonstrably running the new code.
-                //
-                // So this is reported as what it IS: the marker predates the build, and
-                // the server's actual state is UNKNOWN from here. Calling it an
-                // outdated server is a claim this record cannot support, and it priced
-                // a restart decision on a count where at least three entries had
-                // already restarted.
-                //
-                // The pusher half is untouched and remains valid: `scriptMtime` is
-                // self-reported by the process it describes.
-                const stamped = new Date(marker.serverBuildMtime).toISOString();
-                const current = new Date(onDisk).toISOString();
-                unverifiable.push(`${marker.agentId} (marker stamped at the last ATTACH from server build ${stamped}, on-disk build ${current} — this says the MARKER is behind, NOT that the server is: a server-only restart refreshes no marker. Exercise the server to settle it, or detach_agent + attach_agent to refresh the stamp)`);
-            }
-        }
-        // `outdated` is gone, not emptied: nothing can populate it any more, and a
-        // bucket that always reports 0 is a claim the reader still has to discount.
-        const bad = unverifiable;
-        findings.push({
-            check: "marker-server-provenance",
-            level: bad.length ? "warn" : "ok",
-            detail: bad.length
-                ? `${bad.length} transport marker(s) cannot report their server's build: the stamp is written by attach_agent, so it records the server AT THE LAST ATTACH and a server-only restart refreshes nothing. This says the MARKER is behind or absent — NOT that the server is stale. Exercise the server to settle it (a tool that exists only in the newer build), or detach_agent + attach_agent to refresh the stamp. Restart the session too if the server itself is old.`
-                : "every local transport marker was stamped at an attach against the current build — which says the markers are current, not that every server is",
-            fixable: false,
-            items: bad.length ? bad : undefined,
-        });
-    }
-    // 1b³. THE SPLIT: one pane, two components, ONE version number.
-    //
-    // The two stamps above are each checked, and each in its own finding — which
-    // means the state that actually bit us has no name. `detach_agent` +
-    // `attach_agent` respawns the PUSHER and reloads its script; **it does not
-    // restart the MCP SERVER.** So a pane can run a current pusher against a
-    // two-day-old server, and both existing checks are individually correct while
-    // nothing says "this agent is split". Measured across this machine: all three
-    // panes ran a 2026-08-27 pusher hook against a 2026-08-25 server build.
-    //
-    // WHY IT IS A DISPLAY TASK AND NOT A DESIGN ONE: both facts were already
-    // written into every marker. Nothing needed adding; the pair needed reading
-    // together, and reading them apart is what let "we restarted the transports"
-    // be heard as "we restarted the fleet".
-    //
-    // The classification is the deliverable, because the REMEDIES differ: SPLIT
-    // needs a session restart (re-attach will not touch the server), fully-stale
-    // needs both, fresh needs nothing. Reporting two independent warnings leaves
-    // the reader to infer which — and the inference that was actually made was the
-    // optimistic one.
-    //
-    // Every timestamp is ISO-8601 UTC (`Z`), so no reading depends on the reader's
-    // timezone.
-    {
-        const onDiskScript = newestPusherSourceMtime();
-        const onDiskServer = onDiskBuildMtime();
-        const split = [];
-        const bothStale = [];
-        const unknown = [];
-        let fresh = 0;
-        for (const fname of await listTransportFiles()) {
-            const file = path.join(TRANSPORT_DIR, fname);
-            const marker = await readJson(file, null);
-            if (!marker || !isMarkerLive(marker, reg, now))
-                continue;
-            if (marker.transport !== "tmux-push")
-                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
-                // point: "unclassifiable" and "fresh" are different answers, and the
-                // whole finding is about not collapsing them.
-                unknown.push(`${agentId} (pusher ${stamp(scriptMtime)} · server ${stamp(serverBuildMtime)} — one stamp missing, cannot classify)`);
-                continue;
-            }
-            const scriptStale = scriptMtime < onDiskScript - 1;
-            const serverStale = serverBuildMtime < onDiskServer - 1;
-            const pair = `${agentId} (pusher ${stamp(scriptMtime)} · server ${stamp(serverBuildMtime)})`;
-            if (scriptStale && serverStale)
-                bothStale.push(pair);
-            else if (scriptStale !== serverStale) {
-                split.push(`${pair} — ${scriptStale ? "pusher stale, server current" : "pusher CURRENT, server STALE"}`);
-            }
-            else
-                fresh++;
-        }
-        const bad = [...split, ...bothStale, ...unknown];
-        findings.push({
-            check: "transport-build-split",
-            level: split.length || bothStale.length ? "warn" : unknown.length ? "warn" : "ok",
-            detail: bad.length
-                ? `${split.length} pane(s) SPLIT (the two components are at different builds under one version number — a re-attach reloads the pusher and NOT the server, so this needs a SESSION restart), ` +
-                    `${bothStale.length} fully stale, ${unknown.length} unclassifiable, ${fresh} fully current. On-disk now: pusher ${stamp(onDiskScript)} · server ${stamp(onDiskServer)}. Times are ISO-8601 UTC.`
-                : `${fresh} local pane(s) fully current — pusher and server both at the on-disk build (ISO-8601 UTC)`,
-            fixable: false,
-            items: bad.length ? bad : undefined,
-        });
-    }
-    // 1c. Wedged local pushers (pid-alive, pane-dead). v0.8.0 made pushers
-    //     self-exit when their own tmux-target probe finds the pane gone, but
-    //     that only fires from inside the pusher's own poll loop — if the pane
-    //     is killed in a way that loop never observes (or the loop itself is
-    //     wedged), the pid stays alive, isMarkerLive's pid-alive check keeps
-    //     treating it as live, and list_agents reports it "live" while nothing
-    //     can actually be delivered. Local tmux-push only — a tmux-push-remote
-    //     marker's pane lives on a different host, unprobeable from here.
-    {
-        // 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 wedged = [];
-        if (tmuxAvailable) {
-            for (const fname of await listTransportFiles()) {
-                const file = path.join(TRANSPORT_DIR, fname);
-                const marker = await readJson(file, null);
-                if (!marker || !isMarkerLive(marker, reg, now))
-                    continue;
-                if (marker.transport !== "tmux-push")
-                    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]);
-                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
-                // a confirmed pusher.
-                wedged.push({
-                    agentId: marker.agentId,
-                    pid: marker.pid,
-                    file,
-                    target: marker.tmuxTarget,
-                    isPusher: isPusherProcess(marker.pid),
-                });
-            }
-        }
-        if (fix) {
-            for (const w of wedged) {
-                // Clearing the marker is always safe — the pane is gone either way, so
-                // nothing can be delivered through it. Signalling is not: an
-                // unverifiable pid is some other process that inherited this number.
-                if (w.isPusher) {
-                    try {
-                        process.kill(w.pid, "SIGTERM");
-                    }
-                    catch { /* already gone */ }
-                }
-                await deleteFile(w.file);
-                fixed.push(w.isPusher
-                    ? `reaped wedged pusher for ${w.agentId} (pid ${w.pid}, tmux target '${w.target}' gone)`
-                    : `cleared stale transport marker for ${w.agentId} (tmux target '${w.target}' gone; pid ${w.pid} is not a tmux-pusher — not signalled)`);
-            }
-        }
-        findings.push({
-            check: "wedged-local-pushers",
-            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
-                    ? "no wedged local pushers (pid-alive, pane-dead)"
-                    : "tmux not available — skipped wedged-pusher pane probe",
-            fixable: true,
-            items: wedged.length
-                ? wedged.map((w) => `${w.agentId} (pid ${w.pid}, tmux target '${w.target}')${w.isPusher ? "" : " — pid is not a tmux-pusher, marker will be cleared without signalling"}`)
-                : undefined,
-        });
-    }
-    // 1d. Duplicate session bindings — two live MCP sessions bound to one agent
-    //     id means two processes are ACTING as the same agent (the
-    //     `<project>-liaison` shape: a dev session bound onto a live worker's id;
-    //     force/token make that possible on purpose, this makes it visible).
-    //     Bindings are per-process closure state, so this reads the on-disk
-    //     session markers stdio servers write at bind time. A marker whose pid
-    //     is dead is litter from a killed session (default signal death skips
-    //     exit handlers) — cleaned under fix. Live duplicates are NOT auto-
-    //     fixable: doctor cannot know which of two running sessions is the
-    //     impostor; the wrong session should `quit` (its marker clears on exit).
-    {
-        const byAgent = new Map();
-        const stale = [];
-        for (const file of await listSessionFiles()) {
-            const s = await readJson(file, null);
-            if (!s || typeof s.pid !== "number" || !s.agentId || !isPidAlive(s.pid)) {
-                stale.push(path.basename(file));
-                if (fix) {
-                    await deleteFile(file);
-                    fixed.push(`deleted stale session binding ${path.basename(file)}`);
-                }
-                continue;
-            }
-            const list = byAgent.get(s.agentId) ?? [];
-            list.push({ pid: s.pid, via: s.via ?? "unknown", boundAt: s.boundAt ?? 0 });
-            byAgent.set(s.agentId, list);
-        }
-        const dupes = [];
-        for (const [id, list] of byAgent) {
-            if (list.length < 2)
-                continue;
-            dupes.push(`${id} — ${list
-                .map((b) => `pid ${b.pid} (via ${b.via}, bound ${b.boundAt ? new Date(b.boundAt).toISOString() : "unknown"})`)
-                .join(" AND ")}`);
-        }
-        findings.push({
-            check: "duplicate-session-binding",
-            level: dupes.length ? "warn" : "ok",
-            detail: dupes.length
-                ? `${dupes.length} agent id(s) bound by more than one live session — two processes are acting as the same agent. Decide which is legitimate; the other should quit (its binding clears on exit).`
-                : stale.length
-                    ? `no duplicate session bindings (${stale.length} stale binding file(s) from dead sessions${fix ? " — cleaned" : "; run doctor with fix:true to clean"})`
-                    : "no duplicate session bindings",
-            fixable: true,
-            items: dupes.length ? dupes : undefined,
-        });
-    }
-    // 2. Orphan room memberships (member not in the registry).
-    {
-        const orphans = new Set();
-        for (const e of Object.values(rooms)) {
-            for (const m of e.members ?? [])
-                if (!known.has(m))
-                    orphans.add(m);
-        }
-        if (fix && orphans.size) {
-            await updateJson(ROOMS_FILE, {}, (cur) => {
-                for (const e of Object.values(cur)) {
-                    if (e.members?.length)
-                        e.members = e.members.filter((m) => known.has(m));
-                }
-                return cur;
-            });
-            fixed.push(`dropped ${orphans.size} orphan membership(s): ${[...orphans].join(", ")}`);
-        }
-        findings.push({
-            check: "orphan-room-memberships",
-            level: orphans.size ? "warn" : "ok",
-            detail: orphans.size ? `${orphans.size} channel member(s) not in the registry` : "all channel members are registered",
-            fixable: true,
-            items: orphans.size ? [...orphans] : undefined,
-        });
-    }
-    // 3. Orphan inbox / cursor files (owner not registered).
-    {
-        const orphanInbox = [];
-        for (const fname of await listInboxFiles()) {
-            const id = fname.replace(/\.jsonl$/, "");
-            if (!known.has(id)) {
-                orphanInbox.push(id);
-                if (fix) {
-                    await deleteFile(path.join(INBOX_DIR, fname));
-                    fixed.push(`deleted orphan inbox ${fname}`);
-                }
-            }
-        }
-        const orphanCursor = [];
-        for (const fname of await listCursorFiles()) {
-            const id = fname.replace(/\.json$/, "");
-            if (!known.has(id)) {
-                orphanCursor.push(id);
-                if (fix) {
-                    await deleteFile(path.join(CURSOR_DIR, fname));
-                    fixed.push(`deleted orphan cursor ${fname}`);
-                }
-            }
-        }
-        const total = orphanInbox.length + orphanCursor.length;
-        findings.push({
-            check: "orphan-inboxes-cursors",
-            level: total ? "warn" : "ok",
-            detail: total
-                ? `${orphanInbox.length} inbox + ${orphanCursor.length} cursor file(s) for unregistered ids`
-                : "no orphan inbox/cursor files",
-            fixable: true,
-            items: total ? [...new Set([...orphanInbox, ...orphanCursor])] : undefined,
-        });
-    }
-    // Precompute parsed line counts for cursor + malformed checks.
-    const counts = new Map();
-    const countFor = async (file) => {
-        if (!counts.has(file))
-            counts.set(file, await scanJsonl(file));
-        return counts.get(file);
-    };
-    // 4. Cursor offsets past end-of-file (would return [] forever).
-    {
-        const broken = [];
-        for (const fname of await listCursorFiles()) {
-            const id = fname.replace(/\.json$/, "");
-            const cursorPath = path.join(CURSOR_DIR, fname);
-            const cursor = await readJson(cursorPath, {});
-            const overflow = [];
-            const inboxMax = (await countFor(inboxFile(id))).parsed;
-            if ((cursor.inboxOffset ?? 0) > inboxMax)
-                overflow.push(`inboxOffset ${cursor.inboxOffset}>${inboxMax}`);
-            const roomMax = (await countFor(ROOM_FILE)).parsed;
-            if ((cursor.roomOffset ?? 0) > roomMax)
-                overflow.push(`roomOffset ${cursor.roomOffset}>${roomMax}`);
-            const statusMax = (await countFor(STATUS_FILE)).parsed;
-            if ((cursor.statusOffset ?? 0) > statusMax)
-                overflow.push(`statusOffset ${cursor.statusOffset}>${statusMax}`);
-            for (const [chan, off] of Object.entries(cursor.roomOffsets ?? {})) {
-                const max = (await countFor(roomFile(chan))).parsed;
-                if (off > max)
-                    overflow.push(`roomOffsets[${chan}] ${off}>${max}`);
-            }
-            if (overflow.length) {
-                broken.push(`${id}: ${overflow.join(", ")}`);
-                if (fix) {
-                    await updateJson(cursorPath, {}, (c) => {
-                        if ((c.inboxOffset ?? 0) > inboxMax)
-                            c.inboxOffset = inboxMax;
-                        if ((c.roomOffset ?? 0) > roomMax)
-                            c.roomOffset = roomMax;
-                        if ((c.statusOffset ?? 0) > statusMax)
-                            c.statusOffset = statusMax;
-                        if (c.roomOffsets) {
-                            for (const chan of Object.keys(c.roomOffsets)) {
-                                const max = counts.get(roomFile(chan))?.parsed ?? 0;
-                                if (c.roomOffsets[chan] > max)
-                                    c.roomOffsets[chan] = max;
-                            }
-                        }
-                        return c;
-                    });
-                    fixed.push(`clamped cursor offsets for ${id}`);
-                }
-            }
-        }
-        findings.push({
-            check: "cursor-past-eof",
-            level: broken.length ? "error" : "ok",
-            detail: broken.length ? `${broken.length} cursor(s) with an offset past EOF — delivery stalled` : "all cursor offsets are within bounds",
-            fixable: true,
-            items: broken.length ? broken : undefined,
-        });
-    }
-    // 5. Malformed JSONL lines (silently desync offset math between server + hooks).
-    {
-        const jsonlFiles = [
-            ROOM_FILE,
-            STATUS_FILE,
-            ...channels.filter((c) => c !== DEFAULT_ROOM).map((c) => roomFile(c)),
-            ...(await listInboxFiles()).map((f) => path.join(INBOX_DIR, f)),
-        ];
-        const bad = [];
-        for (const file of jsonlFiles) {
-            const c = await countFor(file);
-            if (c.malformed > 0) {
-                bad.push(`${path.basename(file)} (${c.malformed})`);
-                if (fix) {
-                    await fsp.copyFile(file, file + ".bak");
-                    await rewriteJsonl(file, () => true); // drops unparseable lines
-                    fixed.push(`rewrote ${path.basename(file)} dropping ${c.malformed} malformed line(s) (backup: ${path.basename(file)}.bak)`);
-                }
-            }
-        }
-        findings.push({
-            check: "malformed-jsonl",
-            level: bad.length ? "warn" : "ok",
-            detail: bad.length ? `${bad.length} file(s) contain unparseable lines` : "no malformed JSONL lines",
-            fixable: true,
-            items: bad.length ? bad : undefined,
-        });
-    }
-    // 6. Stale agents (registered, no live transport, heartbeat past EVICT_MS). Report only.
-    {
-        // Compute liveness WITHOUT deleting dead markers — loadLiveTransports
-        // prunes as a side effect, which would make this read-only check mutate
-        // state (and pre-empt the orphan-marker fix in check 1).
-        const live = new Set();
-        for (const fname of await listTransportFiles()) {
-            const marker = await readJson(path.join(TRANSPORT_DIR, fname), null);
-            if (marker && isMarkerLive(marker, reg, now))
-                live.add(marker.agentId);
-        }
-        const stale = [];
-        for (const [id, a] of Object.entries(reg)) {
-            if (live.has(id))
-                continue;
-            if (now - a.lastHeartbeat > EVICT_MS)
-                stale.push(`${id} (${Math.floor((now - a.lastHeartbeat) / 3600000)}h)`);
-        }
-        findings.push({
-            check: "stale-agents",
-            level: stale.length ? "warn" : "ok",
-            detail: stale.length ? `${stale.length} agent(s) past the eviction window — next list_agents will drop them` : "no stale agents",
-            fixable: false,
-            items: stale.length ? stale : undefined,
-        });
-    }
-    // 6b. STALENESS HAS TWO CAUSES AND THEY LOOK IDENTICAL IN A FLAT LIST.
-    //
-    // Check 6 reports "these N agents are stale", which is the detection half and
-    // leaves the reader to infer the cause. The inference is the expensive part: a
-    // coordinator misdiagnosed a billing outage as a coordination failure for want
-    // of exactly this distinction, and spent the incident chasing agents.
-    //
-    //   UNIFORM   every agent stale by roughly the same interval. Agents do not
-    //             fail in lockstep — something they SHARE did: the machine slept,
-    //             the API key expired, billing lapsed, the host lost network. The
-    //             remedy is the environment, and touching the agents does nothing.
-    //   DIVERGENT some stale, some fresh, on the same bus at the same moment. The
-    //             shared substrate is demonstrably working, so the fault is the
-    //             stale agent's. The remedy is that agent.
-    //
-    // CLASSIFICATION IS THE DELIVERABLE, NOT DETECTION — the same finding as
-    // `transport-build-split`: two states with different remedies reported as one
-    // warning leave the reader to guess, and the guess is made under incident
-    // pressure.
-    //
-    // WITH FEWER THAN TWO AGENTS THE QUESTION IS UNANSWERABLE and it says so. One
-    // stale agent on a bus of one is uniform and divergent simultaneously; there is
-    // no second observation to compare against. Naming a cause there would be the
-    // confident-wrong-answer shape this whole class is about.
-    {
-        const live = new Set();
-        for (const fname of await listTransportFiles()) {
-            const marker = await readJson(path.join(TRANSPORT_DIR, fname), null);
-            if (marker && isMarkerLive(marker, reg, now))
-                live.add(marker.agentId);
-        }
-        const entries = Object.entries(reg).map(([id, a]) => ({
-            id,
-            live: live.has(id),
-            ageMs: now - a.lastHeartbeat,
-            stale: !live.has(id) && now - a.lastHeartbeat > STALE_MS,
-        }));
-        const stale = entries.filter((e) => e.stale);
-        const fresh = entries.filter((e) => !e.stale);
-        const mins = (ms) => Math.round(ms / 60000);
-        let level = "ok";
-        let detail;
-        let items;
-        if (entries.length === 0) {
-            detail = "no registered agents — nothing to classify";
-        }
-        else if (stale.length === 0) {
-            detail = `${entries.length} agent(s), none stale (threshold ${mins(STALE_MS)}m)`;
-        }
-        else if (entries.length < 2) {
-            level = "warn";
-            detail =
-                `1 agent and it is stale (${mins(stale[0].ageMs)}m) — UNCLASSIFIABLE. Uniform and divergent are the same ` +
-                    `picture with one observation, so the cause is not named here rather than guessed.`;
-            items = [`${stale[0].id} (${mins(stale[0].ageMs)}m)`];
-        }
-        else if (fresh.length === 0) {
-            // Spread across the stale set decides it: a shared cause stops everything at
-            // once, so the ages cluster. Independent failures do not.
-            const ages = stale.map((e) => e.ageMs).sort((a, b) => a - b);
-            const spread = ages[ages.length - 1] - ages[0];
-            const tight = spread <= Math.max(2 * 60 * 1000, ages[ages.length - 1] * 0.1);
-            level = "warn";
-            detail = tight
-                ? `UNIFORM: all ${stale.length} agent(s) stale within ${mins(spread)}m of each other (${mins(ages[0])}–${mins(ages[ages.length - 1])}m). ` +
-                    `Agents do not fail in lockstep — suspect something they SHARE (machine asleep, credentials, billing, network). ` +
-                    `Restarting agents will not help.`
-                : `ALL ${stale.length} agent(s) are stale but their ages span ${mins(spread)}m — NOT uniform, so a single shared cause does not explain it. ` +
-                    `Treat as ${stale.length} independent failures until something ties them together.`;
-            items = stale.map((e) => `${e.id} (${mins(e.ageMs)}m)`);
-        }
-        else {
-            level = "warn";
-            detail =
-                `DIVERGENT: ${stale.length} stale, ${fresh.length} fresh on the same bus at the same moment. ` +
-                    `The shared substrate is demonstrably working — the fault is the stale agent's, not the environment's.`;
-            items = stale.map((e) => `${e.id} (${mins(e.ageMs)}m stale)`);
-        }
-        findings.push({ check: "staleness-class", level, detail, fixable: false, ...(items ? { items } : {}) });
-    }
-    // 7. Oversized JSONL files. Report only (suggest prune).
-    {
-        const big = [];
-        const candidates = [
-            ROOM_FILE,
-            STATUS_FILE,
-            ...channels.filter((c) => c !== DEFAULT_ROOM).map((c) => roomFile(c)),
-            ...(await listInboxFiles()).map((f) => path.join(INBOX_DIR, f)),
-        ];
-        for (const file of candidates) {
-            const sz = await fileSize(file);
-            if (sz > maxBytes)
-                big.push(`${path.basename(file)} (${(sz / 1024 / 1024).toFixed(1)}MB)`);
-        }
-        findings.push({
-            check: "oversized-files",
-            level: big.length ? "warn" : "ok",
-            detail: big.length ? `${big.length} file(s) over ${(maxBytes / 1024 / 1024).toFixed(0)}MB — consider prune` : "no oversized files",
-            fixable: false,
-            items: big.length ? big : undefined,
-        });
-    }
-    // 8. Stale lock dirs from crashed writers.
-    {
-        const locks = await scanStaleLocks(60_000, now);
-        for (const l of locks) {
-            if (fix) {
-                try {
-                    await fsp.rm(l.path, { recursive: true, force: true });
-                    fixed.push(`removed stale lock ${path.basename(l.path)}`);
-                }
-                catch {
-                    // ignore
-                }
-            }
-        }
-        findings.push({
-            check: "stale-locks",
-            level: locks.length ? "warn" : "ok",
-            detail: locks.length ? `${locks.length} lock dir(s) older than 60s — likely from a crashed writer` : "no stale locks",
-            fixable: true,
-            items: locks.length ? locks.map((l) => `${path.basename(l.path)} (${Math.floor(l.ageMs / 1000)}s)`) : undefined,
-        });
-    }
-    // 9. Channel/registry consistency: rooms/<chan>.jsonl files without a registry entry.
-    {
-        const orphanFiles = [];
-        if (existsSync(ROOMS_DIR)) {
-            let names = [];
-            try {
-                names = await fsp.readdir(ROOMS_DIR);
-            }
-            catch {
-                // ignore
-            }
-            for (const name of names) {
-                if (!name.endsWith(".jsonl"))
-                    continue;
-                const chan = name.replace(/\.jsonl$/, "");
-                if (!rooms[chan]) {
-                    orphanFiles.push(name);
-                    if (fix) {
-                        await ensureRoom(chan, "doctor");
-                        fixed.push(`registered channel '${chan}' (had a JSONL file but no registry entry)`);
-                    }
-                }
-            }
-        }
-        findings.push({
-            check: "channel-registry-consistency",
-            level: orphanFiles.length ? "warn" : "ok",
-            detail: orphanFiles.length ? `${orphanFiles.length} channel file(s) with no registry entry` : "channel files and registry agree",
-            fixable: true,
-            items: orphanFiles.length ? orphanFiles : undefined,
-        });
-    }
-    // 9b. Document scope drift (Phase 8 Task 4). For each document declared in
-    //     scopes.json, compare git's last writer against the declared owner.
-    //
-    //     DETECTION ONLY, never fixable — rewriting or reverting someone else's
-    //     file is not a safe automatic repair, and the bus cannot prevent the
-    //     write in the first place (agents edit these with ordinary file tools;
-    //     enforcement waits for Task 5). Skips silently when no scopes.json
-    //     exists (opt-in) or when the declared repo isn't a git checkout, the
-    //     same way the wedged-pusher check skips without tmux — a check that
-    //     can't observe anything must not guess.
-    {
-        const scopes = await loadScopes();
-        const drift = [];
-        const unattributed = [];
-        let detail;
-        if (!scopes.documents.length) {
-            detail = scopes.configured
-                ? `${path.basename(scopes.file)} declares no documents`
-                : `no ${path.basename(scopes.file)} — document scopes are opt-in and none are declared`;
-        }
-        else if (!isGitRepo(scopes.repo)) {
-            detail = `${scopes.documents.length} document(s) declared but '${scopes.repo}' is not a git checkout — last writer is unknowable, check skipped`;
-        }
-        else {
-            for (const doc of scopes.documents) {
-                const writer = lastWriterOf(scopes.repo, doc.path);
-                if (!writer)
-                    continue; // never committed — nothing has written it yet
-                const who = attributeWriter(writer, reg);
-                if (!who) {
-                    // Commits are authored by humans/machine accounts, not agent ids, so
-                    // an unmappable author is the normal case — reported, never flagged.
-                    unattributed.push(`${doc.path}: last written by '${writer.author}' (${writer.commit}), not attributable to a registered agent`);
-                    continue;
-                }
-                if (ownsDocument(who.agentId, reg[who.agentId], doc.owner))
-                    continue;
-                drift.push(`${doc.path}: declared owner '${doc.owner}' (${doc.mode}) but last written by '${who.agentId}'` +
-                    `${who.roleId ? ` [role ${who.roleId}]` : ""} in ${writer.commit} (${writer.when})`);
-            }
-            detail = drift.length
-                ? `${drift.length} document(s) last written by someone other than their declared owner — advisory: coordinate ownership, doctor will not rewrite anyone's file`
-                : `${scopes.documents.length} declared document(s) agree with their scope`;
-        }
-        findings.push({
-            check: "document-scope-drift",
-            level: drift.length ? "warn" : "ok",
-            detail,
-            fixable: false,
-            items: drift.length ? drift : unattributed.length ? unattributed : undefined,
-        });
-    }
-    // 10. Environment sanity. Report only. Path + version come from the running
-    // module's package.json so a stale/decoy bin is named (LESSONS #35). Git
-    // 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 ident = resolveServerIdentity();
-        const loc = ident.branch && ident.sha
-            ? `path=${ident.path} version=${ident.version} ${ident.branch}@${ident.sha.slice(0, 12)}`
-            : `path=${ident.path} version=${ident.version}`;
-        const items = [
-            `root=${ROOT}`,
-            `execPath=${process.execPath}`,
-            `inTmux=${!!process.env.TMUX_PANE}`,
-            `path=${ident.path}`,
-            `version=${ident.version}`,
-        ];
-        if (ident.branch)
-            items.push(`branch=${ident.branch}`);
-        if (ident.sha)
-            items.push(`sha=${ident.sha}`);
-        findings.push({
-            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 NOT on PATH — the tmux-push transport will not work`,
-            fixable: false,
-            items,
-        });
-    }
-    const summary = {
-        ok: findings.filter((f) => f.level === "ok").length,
-        warn: findings.filter((f) => f.level === "warn").length,
-        error: findings.filter((f) => f.level === "error").length,
-    };
-    return {
-        ok: true,
-        healthy: summary.warn === 0 && summary.error === 0,
-        fixApplied: fix,
-        root: ROOT,
-        findings,
-        fixed: fix ? fixed : undefined,
-        summary,
-    };
-}
-//# sourceMappingURL=transport.js.map