agent-coord-mcp 0.26.9 → 0.26.11

package/src/server.ts

@@ -287,7 +287,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "join",
-    "Recommended session-start call. Does register + auto-attach (if running inside tmux) + read inbox in one round-trip. Pass attach=false to skip the transport, attach={...overrides} to customize, or omit it to let the server auto-detect $TMUX_PANE. Returns the registration, attach result, any unread inbox messages, and the default channel's topic + MOTD (room rules) so you see them on connect. Calling join binds this MCP process's identity to agentId for the lifetime of the session — no env var or config needed. Each Claude Code session runs its own stdio process so bindings are naturally isolated. Claiming an id that is currently LIVE on the bus (fresh heartbeat, live pusher, or another bound session) is refused unless the claim comes from that agent's own tmux pane or carries the agent's token or force:true — diagnosing someone else's agent is what status/ping are for.",
+    "Recommended session-start call. Does register + auto-attach (if running inside tmux) + read inbox in one round-trip. Pass attach=false to skip the transport, attach={...overrides} to customize, or omit it to let the server auto-detect $TMUX_PANE. Returns the registration, attach result, any unread inbox messages, and the default channel's topic + MOTD (room rules) so you see them on connect. Calling join binds this MCP process's identity to agentId for the lifetime of the session — no env var or config needed. Each Claude Code session runs its own stdio process so bindings are naturally isolated. Claiming an id that is currently LIVE on the bus (fresh heartbeat, live pusher, or another bound session) is refused unless the claim comes from that agent's own tmux pane or carries the agent's token or force:true — diagnosing someone else's agent is what status/ping are for. `proseOnly:true` claims the per-agent exemption from the typed-record rule — see `register`.",
     joinSchema,
     // join explicitly sets the session binding when unset, so each agent can
     // declare its identity via join rather than relying on env vars.
@@ -310,7 +310,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "register",
-    "Register this agent in the shared registry. Lower-level than `join` — does not attach a transport or drain the inbox. Prefer `join` unless you need explicit control.",
+    "Register this agent in the shared registry. Lower-level than `join` — does not attach a transport or drain the inbox. Prefer `join` unless you need explicit control. `proseOnly:true` claims the per-agent exemption from the typed-record rule, for a model that cannot reliably pick a record.type; it is visible and counted in list_agents, and it is granted to the SENDER but paid by every READER (an untyped message cannot be slimmed). Omit it to leave any existing exemption untouched; pass false to revoke.",
     registerSchema,
     gate("agentId", registerTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -352,14 +352,14 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "list_agents",
-    "List all known agents and whether they appear online (heartbeat <5min).",
+    "List all known agents and whether they appear online (heartbeat <5min). Also reports the prose-only exemptions from the typed-record rule — who holds one, since when, and the count over the total, so a rising exempt share is visible rather than inferred.",
     listAgentsSchema,
     gate(null, listAgentsTool as () => Promise<unknown>),
   );
 
   addTool(
     "send_message",
-    "Send a message. If 'to' is set, goes to that agent's inbox (DM); otherwise to a channel — pass 'room' (e.g. 'seo' or '#seo') to target a specific channel, or omit it for the default 'general' channel. For channel posts, tag 'kind': 'decision' for GOs/verdicts/agreements that must outlive routine cleanup (kept ~30 days, quoted verbatim in digests), 'status' for progress notes, omit for ordinary chatter. Optional 'inReplyTo' is a parent message uuid (a reply that resolves a DAVID_DECISION); malformed id is refused, unknown id is stored with a warning. The 'from' field is enforced against the session's bound identity when binding is configured.",
+    "Send a message. If 'to' is set, goes to that agent's inbox (DM); otherwise to a channel — pass 'room' (e.g. 'seo' or '#seo') to target a specific channel, or omit it for the default 'general' channel. For channel posts, tag 'kind': 'decision' for GOs/verdicts/agreements that must outlive routine cleanup (kept ~30 days, quoted verbatim in digests), 'status' for progress notes, omit for ordinary chatter. Optional 'inReplyTo' is a parent message uuid (a reply that resolves a DAVID_DECISION); malformed id is refused, unknown id is stored with a warning. The 'from' field is enforced against the session's bound identity when binding is configured. EVERY AGENT→AGENT MESSAGE MUST CARRY 'record' with a typed 'type' (decision · verdict · done · blocker · risk · fyi · action · go · scope): a typed multi-line message is delivered as ONE attributed line plus a retrieve_message handle, while an untyped one arrives in full in every reader's context. 'fyi' is the honest catch-all — use it rather than forcing a false 'decision'/'risk'. Untyped sends WARN today and are REFUSED from 2026-09-15. Messages TO a human are exempt (David-facing traffic stays prose), as is a sender that declared proseOnly:true at join.",
     sendMessageSchema,
     gate("from", sendMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
   );

package/src/tools/messaging.ts

@@ -1,5 +1,11 @@
 import { adjustCursors } from "./admin.js";
-import { RECORD_AUTHORITY, resolveRole, roleMatches } from "../roles.js";
+import { RECORD_AUTHORITY, isHuman, recordAuthorityFor, resolveRole, roleMatches } from "../roles.js";
+import {
+  TYPED_RECORD_CUTOVER_ISO,
+  suggestRecordType,
+  typedRecordGuidance,
+  typedRecordMode,
+} from "../typed-records.js";
 import { ARCHIVE_STATUS_FILE, ARCHIVE_INBOX_DIR, ARCHIVE_ROOMS_DIR, archiveJsonl, archiveInboxFile, archiveRoomFile } from "../store.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
@@ -159,6 +165,67 @@ export async function checkRecordAuthority(
   };
 }
 
+// ---------- typed records obligatory (Phase 5.1 Task 12) ----------
+
+// An untyped agent→agent message must not be able to EXIST. Enforced HERE, at
+// the send, and not at the render: a rule applied where the message is read
+// leaves the untyped message on disk, and the next reader re-derives the type
+// from prose. See src/typed-records.ts for the staging, the suggestion rules,
+// and why `fyi` stays an honest catch-all.
+//
+// Returns `undefined` when the send is fine, a WARNING string while the rule is
+// staged, or a REFUSAL after the cutover.
+//
+// TWO EXEMPTIONS, AND THEY ARE DIFFERENT IN KIND:
+//   - the RECIPIENT is a human. Canon: "David-facing messages may use normal
+//     prose". Scoped to agent→agent traffic, so the one channel whose reader is
+//     a person is untouched. Nothing is declared for this — it is a property of
+//     who is being written to.
+//   - the SENDER holds a prose-only exemption, declared per agent at join and
+//     visible in list_agents. That one is a statement about a model's ability
+//     to pick a type, and it is paid for by every reader.
+async function typedRecordCheck(args: {
+  from: string;
+  to?: string;
+  text: string;
+  record?: MessageRecord;
+}): Promise<{ ok: true; warning?: string } | { ok: false; error: string }> {
+  if (args.record?.type) return { ok: true };
+
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+
+  // David-facing prose stays prose. An UNREGISTERED recipient is treated as an
+  // agent, not as a human: the safe reading of "I cannot tell" is the rule, and
+  // a human on this bus has a registry entry (that is how the pane is found).
+  if (args.to && isHuman(reg[args.to])) return { ok: true };
+
+  const sender = reg[args.from];
+  if (sender?.proseOnly) return { ok: true };
+
+  const suggestion = suggestRecordType(args.text, recordAuthorityFor(sender).mayNotEmit);
+  const guidance = typedRecordGuidance(suggestion);
+
+  if (typedRecordMode() === "warn") {
+    return {
+      ok: true,
+      warning:
+        `UNTYPED — stored, but this send is REFUSED from ${TYPED_RECORD_CUTOVER_ISO}. ` +
+        `${guidance} Until then an untyped multi-line message arrives in full in every reader's context ` +
+        `instead of one line plus a retrieve_message handle. ` +
+        `A model that cannot pick a type declares proseOnly:true at join (per-agent, visible in list_agents).`,
+    };
+  }
+  return {
+    ok: false,
+    error:
+      `agent→agent messages must carry a typed record (since ${TYPED_RECORD_CUTOVER_ISO}) — nothing was written. ` +
+      `${guidance} ` +
+      `Types: decision · verdict · done · blocker · risk · fyi · action · go · scope; 'fyi' is the honest ` +
+      `catch-all — do not force a false 'decision'/'risk' to get past this. ` +
+      `Messages TO a human are exempt, and an agent that cannot pick a type declares proseOnly:true at join.`,
+  };
+}
+
 export const sendMessageSchema = {
   from: z.string().min(1),
   to: z.string().optional(),
@@ -245,6 +312,12 @@ export async function sendMessageTool(args: {
     };
   }
 
+  // After `text` is resolved (a record can fill it) and before anything is
+  // written, so a refusal leaves nothing on disk.
+  const typed = await typedRecordCheck({ from: args.from, to: args.to, text, record: args.record });
+  if (!typed.ok) return { ok: false as const, error: typed.error };
+  const typedWarning = typed.warning;
+
   let replyWarning: string | undefined;
   if (args.inReplyTo !== undefined) {
     if (!MESSAGE_ID_RE.test(args.inReplyTo)) {
@@ -312,7 +385,7 @@ export async function sendMessageTool(args: {
     const recipientWarning = reg[args.to]
       ? undefined
       : `recipient '${args.to}' is not a registered agent — message stored in their inbox but no one may be listening`;
-    const warning = [recipientWarning, replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
+    const warning = [typedWarning, recipientWarning, replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
     return { ok: true, id: msg.id, target, room: undefined, warning };
   }
 
@@ -331,7 +404,7 @@ export async function sendMessageTool(args: {
   const target = roomFile(chan);
   await appendJsonl(target, msg);
   await maybeCompactRoom(chan);
-  const roomWarning = [replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
+  const roomWarning = [typedWarning, replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
   return { ok: true, id: msg.id, target, room: chan, ...(roomWarning ? { warning: roomWarning } : {}) };
 }
 

package/src/tools/registry.ts

@@ -83,6 +83,11 @@ export const registerSchema = {
   // token (tokens.json / coord-token) or force:true. Ignored once bound.
   token: z.string().optional(),
   force: z.boolean().optional(),
+  // PROSE-ONLY EXEMPTION (Phase 5.1 Task 12.8). `true` grants it, `false`
+  // revokes it, omitted leaves it exactly as it was — so an agent re-joining
+  // after a /clear does not silently drop an exemption it was granted, and a
+  // card that never heard of the flag cannot revoke one either.
+  proseOnly: z.union([z.boolean(), z.object({ reason: z.string().min(1) })]).optional(),
 };
 
 // Work out what `role`/`roleId` should become, or why the update is refused.
@@ -120,7 +125,12 @@ export function resolveRoleUpdate(
   return { ok: true, role: nextRole, roleId: declared ? resolved.roleId : existing?.roleId };
 }
 
-export async function registerTool(args: { agentId: string; project?: string; role?: RoleArg }) {
+export async function registerTool(args: {
+  agentId: string;
+  project?: string;
+  role?: RoleArg;
+  proseOnly?: boolean | { reason: string };
+}) {
   const before = await readJson<AgentRegistry>(AGENTS_FILE, {});
   const roleUpdate = resolveRoleUpdate(args.agentId, before[args.agentId], args.role);
   if (!roleUpdate.ok) return { ok: false as const, error: roleUpdate.error };
@@ -145,6 +155,23 @@ export async function registerTool(args: { agentId: string; project?: string; ro
       registeredAt: existing?.registeredAt ?? now,
       lastHeartbeat: now,
       capabilities: existing?.capabilities,
+      // Omitted → carried forward untouched. Only an explicit `false` revokes.
+      ...(args.proseOnly === undefined
+        ? existing?.proseOnly
+          ? { proseOnly: existing.proseOnly }
+          : {}
+        : args.proseOnly === false
+          ? {}
+          : {
+              proseOnly: {
+                since: existing?.proseOnly?.since ?? now,
+                ...(typeof args.proseOnly === "object" && args.proseOnly.reason
+                  ? { reason: args.proseOnly.reason }
+                  : existing?.proseOnly?.reason
+                    ? { reason: existing.proseOnly.reason }
+                    : {}),
+              },
+            }),
     };
     return current;
   });
@@ -163,10 +190,28 @@ export async function registerTool(args: { agentId: string; project?: string; ro
         `It keeps any authority its words carry (e.g. 'coord-qa' → 'qa'), but prefer the canonical id — ` +
         `role:{roleId:"<canonical>", displayName:"${entry.role ?? entry.roleId}"}.`
       : undefined;
+  // The exemption's own docs state the asymmetry, at the one moment the agent
+  // granting itself one is reading the response. An exemption whose cost is
+  // invisible to the agent holding it is how the rule decays.
+  const proseOnlyEcho = entry.proseOnly
+    ? {
+        proseOnly: {
+          ...entry.proseOnly,
+          asymmetry:
+            "GRANTED TO THE SENDER, PAID BY EVERY READER. An untyped message cannot be slimmed by the " +
+            "transport (hooks/tier.mjs slims only when record.type is present), so every multi-line message " +
+            "you send arrives in full in every reader's context — which is precisely the cost the typed-record " +
+            "rule exists to remove. This is opt-in and reviewed, not self-service: it is visible in list_agents " +
+            "and counted there, so if the exempt share climbs the drift is measurable. Drop it with " +
+            "proseOnly:false as soon as the model behind this agent can pick a record.type.",
+        },
+      }
+    : {};
   return {
     ok: true as const,
     ...(canonWarning ? { warning: canonWarning } : {}),
     agent: entry,
+    ...proseOnlyEcho,
     resolvedRole: resolveRole(entry),
     recordAuthority: {
       ...authority,
@@ -344,7 +389,22 @@ export async function listAgentsTool() {
         : undefined,
     };
   });
-  return { agents, evicted };
+  // COUNTED, so drift is measurable (Task 12.8). "No exemptions" and "I did not
+  // look" are different claims, so the block is always present and always
+  // carries its denominator — a bare list of ids would read as zero on a bus
+  // where the field had simply never been written.
+  const exempt = agents.filter((a) => a.proseOnly);
+  const proseOnly = {
+    exempt: exempt.map((a) => ({ agentId: a.agentId, since: a.proseOnly!.since, reason: a.proseOnly!.reason })),
+    count: exempt.length,
+    total: agents.length,
+    share: agents.length ? Number((exempt.length / agents.length).toFixed(3)) : 0,
+    note:
+      "prose-only agents are exempt from the typed-record rule on agent→agent sends. The exemption is " +
+      "granted to the SENDER and paid by every READER: their multi-line messages cannot be slimmed. " +
+      "A rising share means the rule is decaying.",
+  };
+  return { agents, evicted, proseOnly };
 }
 
 export async function loadLiveTransports(): Promise<Map<string, TransportMarker>> {

package/src/tools/shared.ts

@@ -73,6 +73,19 @@ export type AgentEntry = {
   registeredAt: number;
   lastHeartbeat: number;
   capabilities?: string[];
+  // PROSE-ONLY EXEMPTION from the typed-record rule (Phase 5.1 Task 12.8).
+  //
+  // Declared PER AGENT at register/join, never as a global env var: a global
+  // switch turns the rule off fleet-wide in one line and nobody notices, while
+  // a per-agent declaration is a statement ABOUT THAT AGENT and shows up in
+  // `list_agents` next to it. It exists so a model that cannot reliably pick a
+  // `record.type` is not locked off the bus — opt-in, never the default.
+  //
+  // THE ASYMMETRY: granted to the SENDER, paid by every READER. An untyped
+  // message cannot be slimmed by hooks/tier.mjs, so a prose-only agent spends
+  // OTHER agents' context on every multi-line send. That is why it is stamped,
+  // counted, and reviewed rather than self-service.
+  proseOnly?: { since: number; reason?: string };
 };
 
 export type TransportMarker = {

package/src/tools/transport.ts

@@ -944,12 +944,16 @@ export const joinSchema = {
   // 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: {
   agentId: string;
   project?: string;
   role?: RoleArg;
+  proseOnly?: boolean | { reason: string };
   attach?: boolean | { tmuxTarget?: string; includeRoom?: boolean; allowlist?: string[]; debounceMs?: number };
   readInbox?: boolean;
 }) {
@@ -957,6 +961,7 @@ export async function joinTool(args: {
     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.

package/src/typed-records.ts

@@ -0,0 +1,216 @@
+// Typed records become obligatory on agent→agent traffic (Phase 5.1 Task 12).
+//
+// THE MECHANISM ALREADY SHIPPED AND ADOPTION WAS THE WHOLE GAP.
+// `hooks/tier.mjs:injectLine` slims a multi-line message to *first line +
+// `[+N lines · record:<type> · retrieve_message id=<uuid>]`* — but ONLY when
+// `record.type` is a string. Measured on the groundwork room 2026-08-30: 206
+// messages, 175 multi-line, 33 typed, 33 slimmed; the coordinator had sent 101
+// and typed 0. The renderer was never the problem.
+//
+// SO THE RULE IS ENFORCED AT THE SEND, NOT THE RENDER. An untyped agent→agent
+// message must not be able to EXIST, or the next reader re-derives the type
+// from prose and we are back to parsing English. Prose is a second source of
+// truth about what a message meant.
+//
+// Three things this module is careful about, each one a stated acceptance
+// property rather than an implementation taste:
+//
+//  1. STAGED, WITH A NAMED DATE. Five fleets share this bus and 7 of 13 server
+//     processes predate 0.26.7. A refusal shipped before a verified restart
+//     rejects messages from agents that CANNOT comply — the sender gets an
+//     error it has no code path to satisfy. So: WARN until the cutover, REFUSE
+//     after it, and the warning names the date in every single message so the
+//     deadline arrives having been announced ~every send rather than once.
+//
+//  2. THE REFUSAL NAMES A TYPE THE SENDER MAY ACTUALLY USE. `go` and `scope`
+//     are coordinator-restricted and `verdict` is gate-runner-restricted
+//     (RECORD_AUTHORITY): the aide hit exactly this, being told to use `scope`
+//     by one check and refused it by another. Naming a forbidden type is
+//     unusable guidance, so every suggestion is filtered through what this
+//     sender's role may emit before it is offered.
+//
+//  3. `fyi` IS AN HONEST CATCH-ALL. If the nine types do not cover a legitimate
+//     send, agents mistype into whatever passes and the type becomes noise —
+//     which costs more than the untyped message did. Anything unrecognised
+//     suggests `fyi` and says so plainly, never a forced `decision`/`risk`.
+
+// The named cutover. Until this instant an untyped agent→agent send WARNS and
+// is stored; from it, the same send is refused.
+//
+// A DATE, NOT A VERSION, because the constraint being waited on is a fleet-wide
+// RESTART, and no version string on the wire can answer "has every server
+// restarted" — 0.26.7 is published while servers predating it still run. Time
+// is the only clock every one of those processes shares.
+export const TYPED_RECORD_CUTOVER_ISO = "2026-09-15T00:00:00.000Z";
+export const TYPED_RECORD_CUTOVER_MS = Date.parse(TYPED_RECORD_CUTOVER_ISO);
+
+export type TypedRecordMode = "warn" | "refuse";
+
+// `AGENT_COORD_TYPED_RECORDS=warn|refuse` overrides the date. It exists for two
+// callers and no others: tests (which must exercise both sides of a date that
+// has not arrived) and an operator who needs to pull the refusal back for a
+// fleet mid-incident. It is NOT the exemption — an exemption is per-agent and
+// visible (see `proseOnly`); this switch is fleet-wide and invisible, which is
+// exactly why it is not how a less capable model gets on the bus.
+export function typedRecordMode(now: number = Date.now()): TypedRecordMode {
+  const env = process.env.AGENT_COORD_TYPED_RECORDS;
+  if (env === "warn" || env === "refuse") return env;
+  return now >= TYPED_RECORD_CUTOVER_MS ? "refuse" : "warn";
+}
+
+// ---------- suggesting the type the sender should have used ----------
+
+// A rejection that says only "record required" costs a round trip; one that
+// says "looks like a `done` — it cites a PR" costs none. A FAILURE PATH MUST BE
+// MORE INFORMATIVE THAN THE SUCCESS PATH HERE, because it fires during a
+// migration, at agents that are mid-slice and did nothing wrong yesterday.
+//
+// Read from the text the fleet already writes: the six canonical prefixes are
+// in every card and on ~every message, so the type is usually already declared
+// in English one token in.
+const PREFIX_TYPES: Array<[RegExp, string, string]> = [
+  [/^\s*DONE\b/i, "done", "the message opens with the DONE: prefix"],
+  [/^\s*BLOCKER\b/i, "blocker", "the message opens with the BLOCKER: prefix"],
+  [/^\s*RISK\b/i, "risk", "the message opens with the RISK: prefix"],
+  [/^\s*FYI\b/i, "fyi", "the message opens with the FYI: prefix"],
+  [/^\s*AGENT_ACTION\b/i, "action", "the message opens with the AGENT_ACTION: prefix"],
+  [/^\s*DAVID_DECISION\b/i, "decision", "the message opens with the DAVID_DECISION: prefix"],
+  [/^\s*GO\b/i, "go", "the message opens with the GO: prefix"],
+  [/^\s*SCOPE(?:\s+CHANGE)?\b/i, "scope", "the message opens with the SCOPE: prefix"],
+];
+
+// Weaker than a prefix and only consulted when there is no prefix at all.
+const SHAPE_TYPES: Array<[RegExp, string, string]> = [
+  [/\b(PASS|FAIL)\b.*\b[0-9a-f]{7,40}\b/, "verdict", "it reads as a gate verdict over a commit sha"],
+  [/^\s*(PASS|FAIL)\b/, "verdict", "it opens with a PASS/FAIL gate result"],
+  [/(^|\s)(#\d+|[\w.-]+\/[\w.-]+#\d+|https:\/\/github\.com\/\S+\/pull\/\d+)/, "done", "it cites a PR"],
+];
+
+export type RecordSuggestion = {
+  type: string;
+  /** Why this type — quoted back to the sender so the guess is auditable. */
+  why: string;
+  /** Set when the best-fitting type is one this sender's role may not emit. */
+  downgradedFrom?: string;
+};
+
+/**
+ * The record type this message most likely should have carried, CONSTRAINED to
+ * what this sender is allowed to emit.
+ *
+ * `mayNotEmit` is the restricted set this role is refused (recordAuthorityFor).
+ * A suggestion landing in it is downgraded to `fyi` and the downgrade is
+ * reported rather than hidden — being quietly steered off `go` reads as the
+ * heuristic being bad, when in fact the role simply does not own that type.
+ */
+export function suggestRecordType(text: string, mayNotEmit: readonly string[] = []): RecordSuggestion {
+  const forbidden = new Set(mayNotEmit);
+  const firstLine = (text ?? "").split("\n", 1)[0] ?? "";
+
+  const hit =
+    PREFIX_TYPES.find(([re]) => re.test(firstLine)) ??
+    SHAPE_TYPES.find(([re]) => re.test(firstLine) || re.test(text ?? ""));
+
+  if (!hit) {
+    return {
+      type: "fyi",
+      why: "nothing in the text names a kind — 'fyi' is the honest catch-all and is never wrong on purpose",
+    };
+  }
+
+  const [, type, why] = hit;
+  if (forbidden.has(type)) {
+    return {
+      type: "fyi",
+      downgradedFrom: type,
+      why: `${why}, but '${type}' is restricted to roles this sender does not hold — 'fyi' carries the same slimming`,
+    };
+  }
+  return { type, why };
+}
+
+/**
+ * The one line of guidance appended to both the warning and the refusal. Same
+ * words either side of the cutover ON PURPOSE: an agent that reads it during
+ * the warn window has already been told the exact call that will keep working.
+ */
+export function typedRecordGuidance(s: RecordSuggestion): string {
+  const cite =
+    s.type === "done"
+      ? `, cites: [{kind:'pr', ref:'<owner/repo#N>'}]` // a `done` is refused without one anyway
+      : "";
+  return (
+    `looks like a '${s.type}' — ${s.why}. ` +
+    `Add record: {type:'${s.type}', payload:{summary:'<one line>'}${cite}} to this same call; ` +
+    `'text' is untouched by the record and your wording always wins.`
+  );
+}
+
+// ---------- measuring adoption, and the inverse failure ----------
+
+// SUCCESS IS THE TRAFFIC TABLE RE-MEASURED, NOT THIS TASK MERGED. The baseline
+// captured the day the rule was made: 212 room messages, 37 typed (17%),
+// 425,903 bytes sitting below line 1 — bytes every reader pays for and no
+// reader asked for.
+//
+// AND THE INVERSE FAILURE LOOKS EXACTLY LIKE SUCCESS ON A COVERAGE NUMBER. If
+// `fyi` becomes nearly everything, coverage reads ~100% while agents are
+// mistyping to get past the gate and the type has stopped carrying
+// information — that is the catch-all rule (12.5) failing, not holding. So the
+// distribution is reported alongside the percentage and is what the verdict
+// keys on. A coverage-only check would certify the failure it exists to catch.
+//
+// The threshold is deliberately generous: `fyi` IS the honest answer for a
+// large share of real traffic, so this fires on domination, not on presence.
+export const FYI_DOMINANCE_THRESHOLD = 0.75;
+
+export type TypedRecordStats = {
+  total: number;
+  typed: number;
+  coverage: number;
+  /** Bytes below the first line of UNTYPED messages — the cost still being paid. */
+  unslimmedBytes: number;
+  /** count by record.type, plus `untyped`. */
+  distribution: Record<string, number>;
+  fyiShareOfTyped: number;
+  verdict: "healthy" | "adopting" | "degenerate";
+  note: string;
+};
+
+/** `messages` is any array of stored messages ({text, record?}). */
+export function typedRecordStats(messages: ReadonlyArray<{ text?: string; record?: { type?: string } }>): TypedRecordStats {
+  const distribution: Record<string, number> = {};
+  let typed = 0;
+  let unslimmedBytes = 0;
+
+  for (const m of messages) {
+    const type = typeof m.record?.type === "string" ? m.record.type : undefined;
+    distribution[type ?? "untyped"] = (distribution[type ?? "untyped"] ?? 0) + 1;
+    if (type) {
+      typed++;
+      continue;
+    }
+    const text = m.text ?? "";
+    const nl = text.indexOf("\n");
+    if (nl !== -1) unslimmedBytes += Buffer.byteLength(text.slice(nl + 1), "utf8");
+  }
+
+  const total = messages.length;
+  const coverage = total ? typed / total : 0;
+  const fyiShareOfTyped = typed ? (distribution.fyi ?? 0) / typed : 0;
+
+  // Order matters: degeneracy is checked BEFORE coverage, or a room that is
+  // 100% `fyi` reports "healthy" — the exact misreading this guards.
+  const degenerate = typed >= 10 && fyiShareOfTyped > FYI_DOMINANCE_THRESHOLD;
+  const verdict = degenerate ? "degenerate" : coverage >= 0.95 ? "healthy" : "adopting";
+
+  const note = degenerate
+    ? `'fyi' is ${(fyiShareOfTyped * 100).toFixed(0)}% of typed messages — coverage looks solved while the type has ` +
+      `stopped carrying information. Agents are typing to pass the gate, which is 12.5 FAILING, not holding.`
+    : verdict === "healthy"
+      ? `${(coverage * 100).toFixed(0)}% typed with a spread distribution — the reader-side cost is paid down and the type still discriminates.`
+      : `${(coverage * 100).toFixed(0)}% typed; ${unslimmedBytes.toLocaleString("en-US")} bytes still sit below line 1 in untyped messages, ` +
+        `carried by every reader.`;
+
+  return { total, typed, coverage: Number(coverage.toFixed(3)), unslimmedBytes, distribution, fyiShareOfTyped: Number(fyiShareOfTyped.toFixed(3)), verdict, note };
+}