agent-coord-mcp 0.17.0 → 0.18.0

package/dist/tools/transport.js

@@ -1,5 +1,8 @@
 import { loadLiveTransports, isMarkerLive, isPidAlive } from "./registry.js";
+import { newestMtimeUnder, onDiskBuildMtime, onDiskSourceMtime, SERVER_BUILD_MTIME, SERVER_BUILD_SHA, BUILD_DIR } from "../build.js";
 import { registerTool } from "./registry.js";
+import { roleInputSchema } from "../roles.js";
+import { attributeWriter, isGitRepo, lastWriterOf, loadScopes, ownsDocument } from "./scopes.js";
 import { sendMessageTool, readMessagesTool } from "./messaging.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync } from "node:fs";
@@ -117,9 +120,14 @@ export const sendCommandSchema = {
     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 delivery timestamp, or null on timeout. The
-// receipt is written by the receiver's pusher AFTER send-keys, so a hit is
-// genuine proof the keystrokes reached the pane. File-only — no agent context.
+// 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;
@@ -128,12 +136,43 @@ async function waitForReceipt(agentId, msgId, timeoutMs) {
         const receipts = await readJsonl(file);
         const hit = receipts.find((r) => r.id === msgId);
         if (hit)
-            return hit.ts ?? Date.now();
+            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.
+export function deliveryOutcome(agentId, receipt, timeoutMs) {
+    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)
+        return { delivery: "confirmed", at: receipt.ts };
+    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 ` +
@@ -212,8 +251,9 @@ export async function sendCommandTool(args) {
         // confirmation rides back in THIS tool result, costing no extra agent context.
         const wait = args.waitForDelivery ?? true;
         const deliveryTimeoutMs = args.deliveryTimeoutMs ?? 8000;
-        const confirmedAt = wait ? await waitForReceipt(args.to, msg.id, deliveryTimeoutMs) : null;
-        const confirmed = confirmedAt !== null;
+        const receipt = wait ? await waitForReceipt(args.to, msg.id, deliveryTimeoutMs) : null;
+        const outcome = wait ? deliveryOutcome(args.to, receipt, deliveryTimeoutMs) : 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.
@@ -230,16 +270,12 @@ export async function sendCommandTool(args) {
             // 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
+            ...(wait && outcome
                 ? {
-                    delivery: confirmed ? "confirmed" : "pending",
+                    delivery: outcome.delivery,
                     confirmed,
-                    ...(confirmedAt !== null ? { deliveredAt: confirmedAt } : {}),
-                    ...(confirmed
-                        ? {}
-                        : {
-                            warning: `no delivery receipt from '${args.to}' within ${deliveryTimeoutMs}ms — the command was written but may not have reached the pane (stale/wedged pusher). Run doctor or re-attach the agent.`,
-                        }),
+                    ...(outcome.at !== undefined ? { deliveredAt: outcome.at } : {}),
+                    ...(confirmed ? {} : { warning: outcome.reason }),
                 }
                 : {}),
             ...(reminderMs > 0 ? { reminderScheduled: { delayMs: reminderMs, recipients: [args.to] } } : {}),
@@ -273,10 +309,17 @@ export async function sendCommandTool(args) {
     const deliveryTimeoutMs = args.deliveryTimeoutMs ?? 8000;
     let confirmed = [];
     let pending = [];
+    let pendingReasons = [];
     if (wait) {
-        const results = await Promise.all(delivered.map(async (m) => ({ m, at: await waitForReceipt(m, msg.id, deliveryTimeoutMs) })));
-        confirmed = results.filter((r) => r.at !== null).map((r) => r.m);
-        pending = results.filter((r) => r.at === null).map((r) => r.m);
+        const results = await Promise.all(delivered.map(async (m) => ({
+            m,
+            outcome: deliveryOutcome(m, await waitForReceipt(m, msg.id, deliveryTimeoutMs), deliveryTimeoutMs),
+        })));
+        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}`);
     }
     // 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.
@@ -298,7 +341,7 @@ export async function sendCommandTool(args) {
                 ...(pending.length
                     ? {
                         pending,
-                        warning: `no delivery receipt within ${deliveryTimeoutMs}ms from: ${pending.join(", ")} — written but may not have reached their panes (stale/wedged pusher). Run doctor.`,
+                        warning: `not confirmed as submitted within ${deliveryTimeoutMs}ms — ${pendingReasons.join(" | ")}`,
                     }
                     : {}),
             }
@@ -306,6 +349,25 @@ export async function sendCommandTool(args) {
         ...(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),
@@ -361,7 +423,12 @@ export async function attachAgentTool(args) {
     // 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").
-    const child = spawn(process.execPath, [pusher], {
+    // `--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: {
@@ -381,14 +448,10 @@ export async function attachAgentTool(args) {
         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 script's mtime so doctor() can flag a stale daemon if it
-    // outlives a later upgrade of the on-disk script (see v0.8.1 → v0.8.2 bug
+    // 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).
-    let scriptMtime;
-    try {
-        scriptMtime = (await fsp.stat(pusher)).mtimeMs;
-    }
-    catch { /* non-fatal */ }
+    const scriptMtime = newestPusherSourceMtime();
     const marker = {
         agentId: args.agentId,
         transport: "tmux-push",
@@ -396,6 +459,11 @@ export async function attachAgentTool(args) {
         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,
     };
     // Use updateJson so it lockfile-protects and creates the file atomically.
     await updateJson(transportFile(args.agentId), marker, () => marker);
@@ -468,6 +536,20 @@ function resolvePusherPath() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     return path.resolve(here, "..", "..", "hooks", "tmux-pusher.mjs");
 }
+// 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) {
@@ -501,7 +583,9 @@ const joinAttachOptionsSchema = z.object({
 export const joinSchema = {
     agentId: z.string().min(1),
     project: z.string().optional(),
-    role: 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(),
@@ -513,6 +597,10 @@ export async function joinTool(args) {
         project: args.project,
         role: args.role,
     });
+    // 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
@@ -585,6 +673,44 @@ 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(),
+};
+// 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 } : {}),
+    };
+    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.
@@ -683,15 +809,14 @@ export async function doctorTool(args) {
     //     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 on-disk script's current mtime catches it.
+    //     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.
     {
-        let localPusherMtime;
-        try {
-            localPusherMtime = (await fsp.stat(resolvePusherPath())).mtimeMs;
-        }
-        catch { /* not packaged? skip */ }
+        const localPusherMtime = newestPusherSourceMtime();
         const stale = [];
         for (const fname of await listTransportFiles()) {
             const file = path.join(TRANSPORT_DIR, fname);
@@ -720,6 +845,163 @@ export async function doctorTool(args) {
             items: stale.length ? stale : 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²ᵇ. 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 outdated = [];
+        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
+            // Absent field = pre-upgrade marker: SKIP, deliberately mirroring the
+            // scriptMtime semantics in 1b. Two checks holding different opinions
+            // about the same absence would be harder to see than either behaviour
+            // alone — the queued P2 ("missing scriptMtime is a skip, not a warn")
+            // flips BOTH together. Do not "fix" one half here.
+            if (marker.serverBuildMtime === undefined)
+                continue;
+            if (onDisk === undefined)
+                continue;
+            if (marker.serverBuildMtime < onDisk - 1) {
+                const stamped = new Date(marker.serverBuildMtime).toISOString();
+                const current = new Date(onDisk).toISOString();
+                outdated.push(`${marker.agentId} (stamped by server build ${stamped}, on-disk build ${current})`);
+            }
+        }
+        findings.push({
+            check: "marker-server-provenance",
+            level: outdated.length ? "warn" : "ok",
+            detail: outdated.length
+                ? `${outdated.length} transport marker(s) stamped by a server build older than dist/ — the stamping/spawn logic (freshness basis, pusher argv) predates the current code. Restart that agent's session, then detach_agent + attach_agent.`
+                : "all local transport markers were stamped by the current server build",
+            fixable: false,
+            items: outdated.length ? outdated : 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,
+        });
+    }
     // 2. Orphan room memberships (member not in the registry).
     {
         const orphans = new Set();
@@ -971,6 +1253,58 @@ export async function doctorTool(args) {
             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.
     {
         const tmuxProbe = spawnSync("tmux", ["-V"]);