agent-coord-mcp 0.26.18 → 0.26.20

package/README.md

@@ -157,6 +157,88 @@ The registry auto-evicts agents whose last heartbeat is older than 24h on every
 
 Set `AGENT_COORD_DIR=/some/other/path` in the MCP server's env to relocate state. (`CLAUDE_COORD_DIR` is also honored as a legacy alias.) Useful if you want different agent groups isolated, or to put the dir on a synced volume so agents on different machines can collaborate (caveat above).
 
+## Selecting the transport
+
+The transport is **fleet-wide and resolved once, at server startup**. There is no
+per-seat branching in `send_command` or `attach`: every seat in a fleet uses the
+same transport, so the answer is a property of the fleet rather than of a call.
+
+**Precedence: config file > env > built-in default.**
+
+| source | where | use it for |
+| --- | --- | --- |
+| `config` | `$AGENT_COORD_DIR/config.json` → `{ "transport": "tmux-push" }` | stating what the **fleet** does — on disk, reviewable, same bytes for every seat |
+| `env` | `AGENT_COORD_TRANSPORT=tmux-push` | one seat deviating **deliberately** (a test, a bisect) |
+| `default` | `tmux-push` | no config and no env |
+
+The file outranks the env var because it is the broader, visible statement: an env
+var is invisible from outside the process that has it, so it cannot describe a
+fleet. `capabilities` reports which source won, so a surprising answer can be
+traced rather than guessed at.
+
+**An unrecognised value refuses at startup — the server exits non-zero and says
+so.** It does not fall back to `tmux-push`. That is deliberate: a silent fallback
+and a correct default leave *identical evidence*, so `AGENT_COORD_TRANSPORT=heardr`
+would give you a working tmux fleet, nothing in any log, and an afternoon spent
+asking why the transport change did nothing. An unreadable `config.json` refuses
+for the same reason — a file that exists and cannot be parsed is not the same as
+no file.
+
+### Asking what is actually running
+
+```
+capabilities → transport: { configured, running, agrees, evidence, configuredSource, disagreeingAgents }
+```
+
+`configured` is the label. **`running` is answered by calling the transport in
+this process** — `available()`, then a `probe()` of a deliberately bogus target —
+and `evidence` carries what those calls returned. The two are separate fields
+because they are separate facts, and `agrees` exists so that reading one cannot be
+mistaken for knowing the other.
+
+`running` is `undefined` when no transport is wired. That is not "tmux by
+default": a process with no transport delivers nothing, and naming a default there
+would be the same substitution one layer down.
+
+`disagreeingAgents` lists, by agent, every marker on disk whose `transport`
+differs from the running one — a **mixed fleet**, which whole-fleet configuration
+says should not exist. Markers are read without being modified, and a stale marker
+is reported (tagged `[stale]`) rather than filtered out: a seat that may come back
+on the wrong transport is more alarming than a live mismatch, not less.
+
+## Migrating a fleet to a new transport
+
+⚠ **A broken transport is the one defect that cannot report itself.** Agents go
+quiet, and on a coordination bus quiet is indistinguishable from thinking. So the
+order below is not ceremony — it is the only way to learn that a transport change
+failed from something other than silence.
+
+A change to transport code reaches a fleet through five states —
+**merged · published · installed · restarted · observed** — and a merge is the
+first of them. Every seat keeps running the code it loaded at startup until its
+own process restarts, so:
+
+1. **Publish and install.** Until the new version is installed, `capabilities`
+   keeps answering honestly about the *old* code. Check `answeredBy.module` to see
+   which copy a seat actually loaded — a global install and a checkout can both be
+   present, and only one is running.
+2. **Restart ONE seat first, and verify it before the rest.** Call `capabilities`
+   on it: `transport.running` must be what you configured and `agrees` must be
+   true. Then exercise delivery — send that seat a message and confirm it arrives.
+   A staged restart turns a fleet-wide risk into a single-seat one.
+3. **Watch `disagreeingAgents` while the fleet is mixed.** During a staged restart
+   it is *expected* to be non-empty; it should reach `[]` when the last seat is
+   restarted. A value that never empties is the signal that a seat did not come
+   back on the new transport.
+4. **Restart the rest**, then confirm `agrees: true` and an empty
+   `disagreeingAgents` on every seat. A fleet where one seat still answers the old
+   way is the state this check exists to make visible.
+
+**Roll back by reverting the config value, not by reverting markers.** Marker
+writes carry both the generic `target` and the transport-specific `tmuxTarget`, so
+a marker written by a newer server stays readable by an older one — a revert does
+not orphan the fleet.
+
 ## Realtime vs. polling
 
 `wait_for_message` is the cheap path: one tool call, server-side `fs.watch` + 500ms poll, capped at 60s. The model only pays for one round-trip per wait.

package/dist/build.js

@@ -0,0 +1,113 @@
+// Build identity of the RUNNING server process.
+//
+// The principle is the #28 pusher-freshness fix carried one layer up: stamp
+// what you LOADED at init, compare against what's on disk NOW, and resolve the
+// measured artifact from the code that is actually executing
+// (import.meta.url), never from configuration — the thing that measures must
+// be the thing that ran. A server process outlives `npm run build`; without a
+// load-time sample there is nothing truthful to compare the on-disk build to,
+// and a server running pre-rebuild code stamps transport markers with logic
+// the rebuild replaced (observed live 2026-07-29: post-#28 attach spawned a
+// pusher with no `--agent` argv and a single-file freshness stamp, agreeing
+// with the new on-disk check only by coincidence).
+import { readdirSync, statSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// Newest mtime (epoch ms) across every file under `dir` (recursive) whose
+// name ends with one of `exts`. Returns undefined when the dir is missing or
+// unreadable — callers skip their check rather than guess. Pure over its
+// arguments so tests exercise it on temp trees instead of touching real
+// sources (a utimes on a shared checkout flips every live pusher's freshness
+// while the suite runs files in parallel).
+export function newestMtimeUnder(dir, exts) {
+    try {
+        let newest;
+        for (const rel of readdirSync(dir, { recursive: true })) {
+            const name = String(rel);
+            if (!exts.some((e) => name.endsWith(e)))
+                continue;
+            let m;
+            try {
+                m = statSync(path.join(dir, name)).mtimeMs;
+            }
+            catch {
+                continue; // deleted mid-scan
+            }
+            if (newest === undefined || m > newest)
+                newest = m;
+        }
+        return newest;
+    }
+    catch {
+        return undefined;
+    }
+}
+// The dir this module was loaded FROM: dist/ in production, src/ under tsx.
+// Either way it is the code actually running, which is the point.
+export const BUILD_DIR = path.dirname(fileURLToPath(import.meta.url));
+// .js for the compiled build, .ts for dev-mode (tsx src/server.ts) — both
+// sides of every comparison use the same list, so the two modes are each
+// self-consistent and can never be compared across.
+const BUILD_EXTS = [".js", ".ts"];
+// Sampled ONCE at module load: the newest mtime across the build this server
+// process actually imported. A later `npm run build` rewrites dist/ under a
+// still-running server; this value stays behind, which is exactly what
+// doctor's server-build-drift check compares against.
+export const SERVER_BUILD_MTIME = newestMtimeUnder(BUILD_DIR, BUILD_EXTS);
+// The on-disk side of the comparison, statted fresh per call.
+// AGENT_COORD_DIST_DIR is a test seam only: it redirects what doctor
+// MEASURES so tests can stage a newer/older build in a temp dir — it never
+// changes what the server loads.
+export function onDiskBuildMtime() {
+    const dir = process.env.AGENT_COORD_DIST_DIR ?? BUILD_DIR;
+    return newestMtimeUnder(dir, BUILD_EXTS);
+}
+// The uncompiled side of the dist-behind-source comparison: newest mtime
+// across src/**/*.ts, resolved as BUILD_DIR's sibling. undefined on a
+// packaged install with no src/ (callers report "nothing to compare", never
+// warn). Under tsx dev-mode BUILD_DIR *is* src/, so the comparison degrades
+// to src-vs-src and reads ok — dev-mode has no build to fall behind.
+// AGENT_COORD_SRC_DIR is the same test seam as AGENT_COORD_DIST_DIR:
+// it redirects measurement only.
+export function onDiskSourceMtime() {
+    const dir = process.env.AGENT_COORD_SRC_DIR ?? path.resolve(BUILD_DIR, "..", "src");
+    return newestMtimeUnder(dir, [".ts"]);
+}
+// Best-effort checkout identity, report-only: lets doctor NAME the build
+// (`branch@sha` would be nicer, but HEAD's sha alone already makes
+// mutable-checkout drift visible, which is all this claims). undefined when
+// not a git checkout (npm install) — never an error.
+export const SERVER_BUILD_SHA = (() => {
+    try {
+        let gitDir = path.resolve(BUILD_DIR, "..", ".git");
+        const st = statSync(gitDir);
+        if (st.isFile()) {
+            // A worktree's .git is a pointer file: "gitdir: <real dir>".
+            const ptr = readFileSync(gitDir, "utf8").trim();
+            if (!ptr.startsWith("gitdir:"))
+                return undefined;
+            gitDir = ptr.slice("gitdir:".length).trim();
+        }
+        const head = readFileSync(path.join(gitDir, "HEAD"), "utf8").trim();
+        if (!head.startsWith("ref:"))
+            return head.slice(0, 12); // detached
+        const ref = head.slice(4).trim();
+        try {
+            return readFileSync(path.join(gitDir, ref), "utf8").trim().slice(0, 12);
+        }
+        catch {
+            // Ref may be packed. commondir handling is deliberately out of scope —
+            // best-effort means undefined beats wrong.
+            const packed = readFileSync(path.join(gitDir, "packed-refs"), "utf8");
+            for (const line of packed.split("\n")) {
+                if (line.endsWith(` ${ref}`))
+                    return line.slice(0, 12);
+            }
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+})();
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

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

package/dist/capabilities.js

@@ -0,0 +1,214 @@
+/*
+ * Phase 5.1 Task 11 — CLOSE THE LOOP: answer a capability question by
+ * EXERCISING the capability, in the process that would serve it.
+ *
+ * 11.1: NO TIMESTAMP ON THIS BOX CAN ANSWER A CAPABILITY QUESTION. Every
+ * artefact people reach for is a proxy that fails differently:
+ *
+ *   an mtime          tracks WRITES. A reinstall of byte-identical code moves
+ *                     it, and an edit that never got built does not.
+ *   serverBuildMtime  is stamped at ATTACH, so it tells you when a transport
+ *                     started, not what the running process contains.
+ *   a version string  is a LABEL someone typed into package.json. Measured
+ *                     today: a tarball published as 0.5.23 contained a change
+ *                     the version numbering said it could not, and the number
+ *                     was believed over the artefact for an hour.
+ *   `npm view`        answers from a cache, and told this fleet the wrong
+ *                     published version twice in one morning.
+ *
+ * Each is honest about something and dishonest about capability, and the
+ * failure is always the same shape: an ANSWER ABOUT A LABEL read as an answer
+ * about behaviour.
+ *
+ * 11.2: A RELEASE IS NOT DELIVERED UNTIL A SERVER THAT RESTARTED ANSWERS.
+ * `merged · published · installed · restarted · observed` — five states, and
+ * the last two are the ones that keep being skipped. A probe run INSIDE the
+ * server process is the only artefact that speaks for the loaded code: it
+ * cannot be satisfied by a file that exists, a version that matches, or a
+ * package that installed, because it calls the code and reports what happened.
+ *
+ * WHY A PROBE MAY NEVER READ A VERSION: if a probe branched on a version
+ * string it would inherit that string's dishonesty, and a fleet would then
+ * have a capability check that passes on a restarted-but-not-upgraded server.
+ * Probes call behaviour. The version travels beside the answer as CONTEXT and
+ * is labelled as such.
+ */
+import { prRefsIn } from "./tools/record-events.js";
+import { EVENT_KIND_IDS } from "./tools/event-kinds.js";
+import { suggestRecordType, typedRecordMode } from "./typed-records.js";
+import { LEAD_REFUSED, PARKED_CATEGORIES } from "./tools/away.js";
+import { recordAuthorityFor } from "./roles.js";
+import { subscriptionHealth } from "./tools/events.js";
+import { configuredTransport, runningTransport, isTmuxKind, targetOf, } from "./transports/index.js";
+import { readAllTransportMarkers } from "./tools/registry.js";
+/**
+ * Each probe calls a behaviour that did not exist before its release and
+ * reports what it observed. A probe that could pass without the code being
+ * loaded is not a probe — it is a restatement of the version.
+ */
+const PROBES = [
+    {
+        id: "typed-records-obligatory",
+        since: "0.26.10",
+        run: () => {
+            const s = suggestRecordType("DONE: shipped it", []);
+            const mode = typedRecordMode();
+            return {
+                present: s.type === "done" && (mode === "warn" || mode === "refuse"),
+                evidence: `suggestRecordType("DONE: …") -> '${s.type}', policy mode '${mode}'`,
+            };
+        },
+    },
+    {
+        id: "record-events-all-kinds",
+        since: "0.26.12",
+        run: () => {
+            const kinds = [...EVENT_KIND_IDS].sort();
+            const present = ["item", "phase", "pr", "task"].every((k) => kinds.includes(k));
+            return { present, evidence: `subscribable kinds: ${kinds.join(", ")}` };
+        },
+    },
+    {
+        id: "multi-pr-citation",
+        since: "0.26.14",
+        run: () => {
+            const refs = prRefsIn("owner/repo#170, #173");
+            return {
+                present: refs.length === 2 && refs[1] === "owner/repo#173",
+                evidence: `prRefsIn("owner/repo#170, #173") -> [${refs.join(", ")}]`,
+            };
+        },
+    },
+    {
+        id: "away-means-david-away",
+        since: "0.26.13",
+        run: () => {
+            const present = "merge" in LEAD_REFUSED && PARKED_CATEGORIES.includes("licence");
+            return {
+                present,
+                evidence: `coord_away refuses [${Object.keys(LEAD_REFUSED).join(", ")}] for the lead; parks ${PARKED_CATEGORIES.length} categories`,
+            };
+        },
+    },
+    {
+        id: "subscription-scanned-vs-evaluated",
+        since: "0.26.15",
+        run: () => {
+            // The capability is that "the machinery ran" and "your kind fired" are
+            // separable. Probed by asking for the state that used to be reported as
+            // broken: scanned, never evaluated — a healthy idle watch.
+            const base = { id: "p", agentId: "p", kind: "item", target: "t", createdAt: 0, lastEvaluatedAt: null, lastEventAt: null, delivered: [] };
+            const quiet = subscriptionHealth({ ...base, lastScannedAt: Date.now() });
+            const unscanned = subscriptionHealth({ ...base, lastScannedAt: null });
+            return {
+                present: quiet.level === "ok" && unscanned.level === "error",
+                evidence: `scanned+quiet -> '${quiet.level}', never-scanned -> '${unscanned.level}'`,
+            };
+        },
+    },
+    {
+        id: "record-authority",
+        since: "0.24.0",
+        run: () => {
+            const worker = recordAuthorityFor({ roleId: "worker" });
+            return {
+                present: worker.mayNotEmit.includes("verdict"),
+                evidence: `a worker mayNotEmit: [${worker.mayNotEmit.join(", ")}]`,
+            };
+        },
+    },
+];
+export function probeCapabilities(context) {
+    const probes = PROBES.map((p) => {
+        try {
+            const r = p.run();
+            return { id: p.id, since: p.since, present: r.present, evidence: r.evidence };
+        }
+        catch (e) {
+            // A THROWN PROBE IS AN ABSENT CAPABILITY, NOT A BROKEN CHECK. Older code
+            // that lacks the symbol throws exactly here, and reporting that as an
+            // error rather than an absence would make the common case look like a
+            // malfunction.
+            return { id: p.id, since: p.since, present: false, evidence: `probe threw: ${e.message}` };
+        }
+    });
+    const missing = probes.filter((p) => !p.present).map((p) => p.id);
+    return {
+        answeredBy: {
+            pid: process.pid,
+            startedAtIso: new Date(Date.now() - Math.round(process.uptime() * 1000)).toISOString(),
+            module: context.module,
+            versionLabel: context.versionLabel,
+        },
+        probes,
+        missing,
+        ok: missing.length === 0,
+        note: "Every line above was produced by CALLING the code in this process. `versionLabel` is a label someone typed " +
+            "into package.json and is context, never evidence — a published tarball has already been observed carrying a " +
+            "change its version said it could not. THIS ANSWER IS ABOUT ONE PROCESS: a release is delivered when every " +
+            "live agent's OWN server answers, which is the fifth state (merged · published · installed · restarted · observed). " +
+            "A server that has not restarted answers honestly about the old code it is still running.",
+    };
+}
+/* ── the verb ──────────────────────────────────────────────────────────────── */
+import { resolveServerIdentity } from "./server-identity.js";
+export const capabilitiesSchema = {};
+/**
+ * Build the transport capability by CALLING things, then compare.
+ *
+ * Deliberately async and deliberately separate from `probeCapabilities`, which
+ * is synchronous: the transport answer requires I/O (a `tmux -V`, a pane probe),
+ * and making the sync report do I/O to obtain it would have meant reading the
+ * config instead — which is the substitution this whole field exists to refuse.
+ */
+export async function probeTransport() {
+    const conf = configuredTransport();
+    const running = await runningTransport();
+    // 3.4 — a mixed fleet must be detectable and LOUD. Every marker on disk is
+    // read and any that names a different transport is listed by agent, because a
+    // count alone tells you something is wrong and not where to look.
+    const disagreeingAgents = [];
+    try {
+        // READ-ONLY on purpose. The reaping loader would delete markers it judged
+        // not-live, so a diagnostic would mutate the fleet it is describing — and it
+        // would hide the remote kind, whose liveness needs a registry heartbeat.
+        for (const { marker, live } of await readAllTransportMarkers()) {
+            if (running.kind !== undefined && marker.transport !== running.kind) {
+                const where = isTmuxKind(marker.transport) ? targetOf(marker) : undefined;
+                disagreeingAgents.push({
+                    agentId: marker.agentId,
+                    marker: `${marker.transport}${where ? ` (${where})` : ""}${live ? "" : " [stale]"}`,
+                });
+            }
+        }
+    }
+    catch {
+        // An unreadable transports dir is not evidence of a uniform fleet. Left
+        // empty, and the caller can see `running` was still answered.
+    }
+    return {
+        configured: conf.kind,
+        running: running.kind,
+        agrees: running.kind === conf.kind,
+        evidence: running.evidence,
+        configuredSource: conf.source,
+        disagreeingAgents,
+    };
+}
+export async function capabilitiesTool() {
+    const id = resolveServerIdentity();
+    const report = probeCapabilities({ module: id.path, versionLabel: id.version });
+    try {
+        return { ...report, transport: await probeTransport() };
+    }
+    catch (e) {
+        // A THROWN TRANSPORT PROBE IS NOT A BROKEN VERB. An unknown configured value
+        // refuses at startup by design, and this verb is exactly what an operator
+        // reaches for to find out why — so it must still answer, and say what threw.
+        return {
+            ...report,
+            transportError: `transport probe threw: ${e.message}`,
+        };
+    }
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

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

package/dist/prefix.js

@@ -0,0 +1,64 @@
+/*
+ * WHERE WILL A NEW GLOBAL INSTALL LAND, AND IS IT WHERE THE FLEET LOADS FROM?
+ *
+ * These are two different questions and neither answers the other. The
+ * `server-build-drift` check names which copy is RUNNING; this names where the
+ * NEXT copy will be written. A run of `npm i -g agent-coord-mcp` that prints
+ * "added 1 package" is not evidence it landed anywhere that runs.
+ *
+ * MEASURED ON THIS BOX, 2026-08-28 — the divergence is not hypothetical:
+ *   npm prefix -g          -> .../node/v22.22.2
+ *   every live fleet server-> .../node/v22.21.1/lib/node_modules/agent-coord-mcp
+ * Three prefixes exist here (two nvm, one /opt/homebrew), `npm prefix -g` is
+ * PATH-dependent, and nvm switches it per shell. So the install target and the
+ * load target had silently diverged, and a successful install would have
+ * updated a copy nothing loads. That gap cost the fleet a day.
+ */
+import path from "node:path";
+/**
+ * The global root a module path sits under, or null if it is not in one.
+ * `/p/lib/node_modules/agent-coord-mcp/dist` -> `/p`
+ */
+export function prefixOf(modulePath) {
+    if (!modulePath)
+        return null;
+    // Split on the LAST occurrence: a global prefix can itself live under a path
+    // containing `node_modules`, and taking the first match would name an
+    // ancestor that installs nothing.
+    const marker = `${path.sep}lib${path.sep}node_modules${path.sep}`;
+    const i = modulePath.lastIndexOf(marker);
+    if (i === -1)
+        return null;
+    return modulePath.slice(0, i);
+}
+/**
+ * `loadPrefix` is where THIS server was loaded from; `installPrefix` is what
+ * `npm prefix -g` answered, and `npmPath` is which npm answered it — because a
+ * prefix without the binary that reported it cannot be reproduced by anyone.
+ */
+export function prefixVerdict(loadPrefix, installPrefix, npmPath) {
+    const via = npmPath ? ` (asked: ${npmPath})` : "";
+    // NOT DETERMINED IS NOT MATCHING. Both unknown branches are warnings that say
+    // what could not be established, never an "ok" over an unasked question.
+    // NOT APPLICABLE IS NOT THE SAME AS UNCHECKED, and conflating them is how a
+    // check earns its way into being ignored. A dev checkout has no load prefix
+    // BY CONSTRUCTION: this process is not the copy the fleet loads, so there is
+    // no divergence for it to have. Warning on every dev run would fire on every
+    // test run and every local session — noise, which is what a denylist does.
+    //
+    // The question is still ASKED where it can be answered: a session running
+    // from a global install has a load prefix, and that is where the fleet lives.
+    if (!loadPrefix)
+        return { level: "ok", detail: `not applicable: this server runs from a dev checkout, not a global install${via}, so it is not the copy the fleet loads and has no prefix to diverge from. Run \`doctor\` in an installed session to compare install target against load target.` };
+    if (!installPrefix)
+        return { level: "warn", detail: `could not determine the global install prefix${via} — \`npm prefix -g\` gave no answer, so where a new copy would land is UNKNOWN. Running from ${loadPrefix}.` };
+    if (path.resolve(loadPrefix) === path.resolve(installPrefix))
+        return { level: "ok", detail: `a global install would land where this server loads from (${loadPrefix})${via}` };
+    return {
+        level: "error",
+        detail: `INSTALL PREFIX AND LOAD PREFIX DIVERGE. A global install from this shell writes to ${installPrefix}${via}, but this server is running from ${loadPrefix}. ` +
+            `A successful "added 1 package" would update a copy nothing loads, and every check that reads a VERSION would keep reporting the old one truthfully. ` +
+            `Install with an explicit prefix (\`npm i -g --prefix ${loadPrefix} <pkg>\`) or switch node/nvm to the version owning ${loadPrefix} before installing.`,
+    };
+}
+//# sourceMappingURL=prefix.js.map

package/dist/prefix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefix.js","sourceRoot":"","sources":["../src/prefix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,UAA8B;IACrD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,6EAA6E;IAC7E,sEAAsE;IACtE,kCAAkC;IAClC,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,eAAe,IAAI,CAAC,GAAG,EAAE,CAAC;IAClE,MAAM,CAAC,GAAG,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAChC,CAAC;AAOD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,UAAyB,EAAE,aAA4B,EAAE,OAAgB;IACrG,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,YAAY,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAElD,8EAA8E;IAC9E,yEAAyE;IACzE,4EAA4E;IAC5E,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,2EAA2E;IAC3E,EAAE;IACF,0EAA0E;IAC1E,8EAA8E;IAC9E,IAAI,CAAC,UAAU;QACb,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,6EAA6E,GAAG,kKAAkK,EAAE,CAAC;IACrR,IAAI,CAAC,aAAa;QAChB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gDAAgD,GAAG,gGAAgG,UAAU,GAAG,EAAE,CAAC;IAErM,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC;QAC1D,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,6DAA6D,UAAU,IAAI,GAAG,EAAE,EAAE,CAAC;IAEnH,OAAO;QACL,KAAK,EAAE,OAAO;QACd,MAAM,EACJ,sFAAsF,aAAa,GAAG,GAAG,qCAAqC,UAAU,IAAI;YAC5J,sJAAsJ;YACtJ,wDAAwD,UAAU,sDAAsD,UAAU,qBAAqB;KAC1J,CAAC;AACJ,CAAC"}

package/dist/roles.js

@@ -0,0 +1,132 @@
+// Canonical role identity, server side (Phase 8 Task 4).
+//
+// MIRROR of hooks/roles.mjs — tsconfig's rootDir is `src`, so this cannot
+// import the hook copy, and the hook copy must stay build-free (the pusher
+// loads it from a bare checkout). test/roles.test.mjs asserts the two agree;
+// change one, change the other.
+//
+// See hooks/roles.mjs for the rationale behind `explicit` and the word-match
+// fallback.
+import { z } from "zod";
+export function slugifyRole(role) {
+    return String(role ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export const GATE_RUNNER_ROLE_IDS = new Set(["qa", "quality", "coordinator", "gate"]);
+export const COORDINATOR_ROLE_IDS = new Set(["coordinator"]);
+// CI receives express-lane DONE: wake. Not a gate-runner — must not grant verdict.
+export const CI_ROLE_IDS = new Set(["ci"]);
+// Console / watchers. May send prefixed messages. Not a gate-runner.
+export const AUTOMATION_ROLE_IDS = new Set(["automation"]);
+// A HUMAN READER. The one carve-out in the typed-record rule (Phase 5.1 Task
+// 12.3): canon already rules "David-facing messages may use normal prose", and
+// a blanket requirement would break the single channel whose reader is a
+// person. `david` is here as well as `human` because the registry entry that
+// exists on this bus today declares role "David" — the id derives to `david`,
+// and a rule that only recognised the canonical spelling would have refused
+// the exact traffic it is written to protect.
+export const HUMAN_ROLE_IDS = new Set(["human", "david"]);
+export function resolveRole(role) {
+    if (role === null || role === undefined)
+        return undefined;
+    if (typeof role === "string") {
+        const roleId = slugifyRole(role);
+        return roleId ? { roleId, displayName: role, explicit: false } : undefined;
+    }
+    if (typeof role === "object") {
+        const declared = typeof role.roleId === "string" ? slugifyRole(role.roleId) : "";
+        const name = typeof role.displayName === "string" && role.displayName
+            ? role.displayName
+            : typeof role.role === "string" && role.role
+                ? role.role
+                : undefined;
+        if (declared)
+            return { roleId: declared, displayName: name ?? declared, explicit: true };
+        if (name)
+            return resolveRole(name);
+    }
+    return undefined;
+}
+export function roleMatches(role, allowedIds) {
+    const resolved = resolveRole(role);
+    if (!resolved)
+        return false;
+    if (allowedIds.has(resolved.roleId))
+        return true;
+    // Word-split applies to DECLARED ids too. It used to be derived-only ("frozen
+    // ids match exactly"), which made precision cost authority: {roleId:"coord-qa"}
+    // was refused `verdict` while the vaguer bare string "coord-qa" passed via the
+    // split — a consumer fleet's QA verdicts were never machine-authorized (2026-08-21).
+    // Freezing still governs identity (the id cannot change); it must never grant
+    // LESS than the derived twin of the same spelling.
+    return resolved.roleId.split("-").some((word) => allowedIds.has(word));
+}
+// The canonical role vocabulary — every authority set plus the classes the
+// cards register. Not an allowlist: any roleId may register; a non-canonical
+// one gets a warning naming this set so the next card uses the exact spelling.
+export const CANONICAL_ROLE_IDS = new Set([
+    "coordinator",
+    "worker",
+    "aide",
+    "qa",
+    "quality",
+    "gate",
+    "ci",
+    "audit",
+    "automation",
+    "human",
+]);
+export function isGateRunner(role) {
+    return roleMatches(role, GATE_RUNNER_ROLE_IDS);
+}
+export function isCoordinator(role) {
+    return roleMatches(role, COORDINATOR_ROLE_IDS);
+}
+export function isCi(role) {
+    return roleMatches(role, CI_ROLE_IDS);
+}
+export function isAutomation(role) {
+    return roleMatches(role, AUTOMATION_ROLE_IDS);
+}
+export function isHuman(role) {
+    return roleMatches(role, HUMAN_ROLE_IDS);
+}
+// Which roles may emit which record.type at the send path. Enforcement lives
+// in messaging.ts (checkRecordAuthority); the table lives here so register/join
+// can ECHO the consequence back at onboarding — a role that cannot emit `go`
+// should learn it when it registers, not when it sends its first work order.
+//
+// NOT A TRUST BOUNDARY — roles are self-declared. See checkRecordAuthority.
+export const RECORD_AUTHORITY = {
+    verdict: { roles: GATE_RUNNER_ROLE_IDS, label: "gate-runner" },
+    go: { roles: COORDINATOR_ROLE_IDS, label: "coordinator" },
+    scope: { roles: COORDINATOR_ROLE_IDS, label: "coordinator" },
+};
+// Split the restricted record types into what this role may and may not emit.
+// Unrestricted types are omitted from both lists — they are nobody's business.
+export function recordAuthorityFor(role) {
+    const mayEmit = [];
+    const mayNotEmit = [];
+    for (const [type, rule] of Object.entries(RECORD_AUTHORITY)) {
+        (roleMatches(role, rule.roles) ? mayEmit : mayNotEmit).push(type);
+    }
+    return { mayEmit, mayNotEmit };
+}
+// Wire shape for `role` on register/join. Either free text (v1: `role: "qa
+// lead"`) or a declared identity (`{roleId: "qa", displayName: "QA gate"}`).
+// Both are supported forever — the string form is not deprecated, it just
+// leaves the id derived rather than frozen.
+//
+// Lives here rather than in tools/ because registry.ts and transport.ts import
+// each other; a schema in either would be a temporal-dead-zone hazard.
+export const roleInputSchema = z.union([
+    z.string(),
+    z.object({
+        roleId: z.string().min(1).optional(),
+        displayName: z.string().min(1).optional(),
+    }),
+]);
+//# sourceMappingURL=roles.js.map

package/dist/roles.js.map

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