agent-coord-mcp 0.17.0 → 0.18.0

package/src/server.ts

@@ -4,7 +4,7 @@ import { createServer, IncomingMessage, ServerResponse } from "node:http";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { ensureDirs, readTokenMapSync } from "./store.js";
+import { ensureDirs, getTokenMap, reloadTokenMapSync } from "./store.js";
 import {
   attachAgentSchema,
   attachAgentTool,
@@ -38,12 +38,16 @@ import {
   pruneTool,
   readMessagesSchema,
   readMessagesTool,
+  retrieveMessageSchema,
+  retrieveMessageTool,
   retrieveRoomHistorySchema,
   retrieveRoomHistoryTool,
   registerSchema,
   registerTool,
   renameAgentSchema,
   renameAgentTool,
+  reportReceiptSchema,
+  reportReceiptTool,
   reportTransportSchema,
   reportTransportTool,
   sendCommandSchema,
@@ -62,6 +66,14 @@ import {
   quitTool,
   waitForMessageSchema,
   waitForMessageTool,
+  listScopesSchema,
+  listScopesTool,
+  importWorkSchema,
+  importWorkTool,
+  listWorkSchema,
+  listWorkTool,
+  exportWorkSchema,
+  exportWorkTool,
 } from "./tools/index.js";
 
 function jsonResult(data: unknown) {
@@ -88,16 +100,25 @@ function buildServer(initialBound?: string): McpServer {
 
   // Gate every tool that takes a caller identity. `field: null` (list_agents,
   // list_rooms, prune) bypasses the check entirely.
+  //
+  // `bindOnClaim: false` (status, ping) means the tool still enforces a
+  // mismatch against an *existing* binding, but a fresh (unbound) session
+  // never claims one just by naming an agentId — a diagnostic status/ping
+  // call must not be able to silently TOFU-bind a session to some other,
+  // already-live agent's identity.
   function gate(
     field: "agentId" | "from" | null,
     handler: (args: Record<string, unknown>) => Promise<unknown>,
+    { bindOnClaim = true }: { bindOnClaim?: boolean } = {},
   ) {
     return async (args: Record<string, unknown>) => {
       if (field) {
         const claimed = args[field];
         if (typeof claimed === "string") {
           if (bound === undefined) {
-            bound = claimed; // TOFU: first claim wins, then sticky.
+            if (bindOnClaim) {
+              bound = claimed; // TOFU: first claim wins, then sticky.
+            }
           } else if (bound !== claimed) {
             throw new Error(
               `identity bound to '${bound}'; rejected attempt to act as '${claimed}'`,
@@ -158,9 +179,9 @@ function buildServer(initialBound?: string): McpServer {
 
   server.tool(
     "status",
-    "Introspect this agent's coord state: registration, attached transport, inbox depth and unread count, and whether this MCP server is running inside tmux. Useful for debugging 'why isn't my DM landing'.",
+    "Introspect this agent's coord state: registration, attached transport, inbox depth and unread count, and whether this MCP server is running inside tmux. Useful for debugging 'why isn't my DM landing'. Read-only — naming an agentId here never binds this session's identity.",
     statusSchema,
-    gate("agentId", statusTool as (a: Record<string, unknown>) => Promise<unknown>),
+    gate("agentId", statusTool as (a: Record<string, unknown>) => Promise<unknown>, { bindOnClaim: false }),
   );
 
   server.tool(
@@ -172,9 +193,9 @@ function buildServer(initialBound?: string): McpServer {
 
   server.tool(
     "ping",
-    "Liveness probe for another agent, answered entirely from server-side state (registry entry, transport marker, pusher pid, tmux pane) — it never touches the target's session, so a fleet-wide sweep costs zero model tokens on the targets. Returns alive (fresh heartbeat or live transport), reachable (a DM pushed now would land), granular checks, and latencyMs. Distinct from heartbeat, which is an agent refreshing its OWN activity timestamp. Pass echo:true (default off) to additionally drop a PING DM into the target's inbox — that wakes the target's model, so use it sparingly and only when you need an agent-level acknowledgement. 'from' is enforced against the session's bound identity.",
+    "Liveness probe for another agent, answered entirely from server-side state (registry entry, transport marker, pusher pid, tmux pane) — it never touches the target's session, so a fleet-wide sweep costs zero model tokens on the targets. Returns alive (fresh heartbeat or live transport), reachable (a DM pushed now would land), granular checks, and latencyMs. Distinct from heartbeat, which is an agent refreshing its OWN activity timestamp. Pass echo:true (default off) to additionally drop a PING DM into the target's inbox — that wakes the target's model, so use it sparingly and only when you need an agent-level acknowledgement. 'from' is enforced against the session's bound identity, but read-only — naming 'from' here never binds this session's identity.",
     pingSchema,
-    gate("from", pingTool as (a: Record<string, unknown>) => Promise<unknown>),
+    gate("from", pingTool as (a: Record<string, unknown>) => Promise<unknown>, { bindOnClaim: false }),
   );
 
   server.tool(
@@ -212,6 +233,13 @@ function buildServer(initialBound?: string): McpServer {
     gate("agentId", retrieveRoomHistoryTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  server.tool(
+    "retrieve_message",
+    "Expand a `retrieve_message id=<uuid>` handle from a pane digest into the full message and its typed `record`. A record whose text rendering spans multiple lines (a DAVID_DECISION packet) is delivered to a pane as ONE attributed line plus this handle; call it to get the structured record back. Reads the message by id from the channels you can read (your inbox and rooms you belong to), falling through to the append-only archive if compaction moved it — so unlike retrieve_room_history there is no TTL and nothing to expire. A handle for a message never delivered to you is simply not found.",
+    retrieveMessageSchema,
+    gate("agentId", retrieveMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   server.tool(
     "post_status",
     "Append a status broadcast to the shared status stream.",
@@ -320,6 +348,13 @@ function buildServer(initialBound?: string): McpServer {
     gate("agentId", clearTransportTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  server.tool(
+    "report_receipt",
+    "Append a delivery receipt for a message this agent's pusher just typed into its pane — the wire-callable counterpart to the local pusher's receipts/<id>.jsonl stamp, for remote pushers (scripts/coord-pusher.mjs) that cannot write this host's filesystem. This is what lets send_command to a tmux-push-remote agent return delivery:'confirmed'. For control commands pass exactly what submit verification observed (submitted/verified/reason); omitting 'submitted' means 'typed but unverified' and is reported as delivery:'pending', never 'confirmed'. 'agentId' (the receiving agent) is enforced against the session's bound identity, so a pusher can only stamp its own agent's receipt file.",
+    reportReceiptSchema,
+    gate("agentId", reportReceiptTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   server.tool(
     "doctor",
     "Bus-wide health check: inspects the whole state dir and reports drift, leaks, and corruption (orphan transport markers / memberships / inboxes, cursor offsets past EOF, malformed JSONL, stale agents, oversized files, stale locks, channel/registry mismatches, environment). Read-only by default; pass fix=true to apply the safe, reversible repairs (malformed-line rewrites are backed up to .bak first). A clean report (healthy=true) means the bus is internally consistent.",
@@ -327,6 +362,34 @@ function buildServer(initialBound?: string): McpServer {
     gate(null, doctorTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  server.tool(
+    "list_scopes",
+    "Read the declared write scopes for managed documents (~/agent-coord/scopes.json). Call it with 'path' (and your 'agentId') to ask \"may I write this?\" BEFORE editing a shared doc like docs/QUEUE.md; call it bare to list every declared document and its owning role. ADVISORY ONLY: the bus does not mediate file writes, so this answers who owns a document, it does not stop anyone — enforcement arrives when work state moves into the store. Absent scopes.json means nothing is owned and nothing warns (opt-in).",
+    listScopesSchema,
+    gate(null, listScopesTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  server.tool(
+    "import_work",
+    "Read a project's work documents (docs/QUEUE.md + docs/DONE.md, or the legacy docs/BACKLOG.md, plus docs/WORKSTREAMS.md) into typed records: queue items {priority,text,done}, done entries {text,ref,date} and board rows. The markdown stays authoritative — this store is a derived index, and export_work renders it back byte-identically.",
+    importWorkSchema,
+    gate(null, importWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  server.tool(
+    "list_work",
+    "Query a project's work state as records instead of parsing markdown: open queue items (filter by priority), done entries with their ref and date as separate fields, and the board's lane rows. Falls back to reading the documents directly when nothing has been imported, so it works with no store at all.",
+    listWorkSchema,
+    gate(null, listWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  server.tool(
+    "export_work",
+    "Render a project's work documents back out of the store, reproducing the pinned glyph contract exactly (ref after the last ' \u2014 ', date after a trailing ' \u00b7 '). Reports by default; pass write:true to rewrite the files. Refuses to export from an empty store rather than blanking a document. Any declared Task 4 write scope is REPORTED alongside the write, never enforced.",
+    exportWorkSchema,
+    gate(null, exportWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   server.tool(
     "delete_room",
     "Permanently delete a channel: removes it from the registry, deletes its JSONL file, and clears all agent cursor offsets for that channel. Refuses if agents are still joined unless force=true. Cannot delete the default 'general' channel. Posts a system notice to #general on success.",
@@ -344,12 +407,13 @@ function buildServer(initialBound?: string): McpServer {
   return server;
 }
 
-// Lazy-loaded token map for HTTP identity binding. Hot-reloaded on SIGHUP so
-// operators can rotate / add agents without a server restart.
-let tokenMap: Map<string, string> | null = null;
+// Token map for HTTP identity binding, held in-process via store.ts's
+// shared cache. Hot-reloaded on SIGHUP so operators can rotate / add agents
+// without a server restart; also refreshed automatically by rename_agent
+// (see rotateAgentToken) so a live rename doesn't need one.
 function loadTokenMap(initial: boolean): void {
   try {
-    tokenMap = readTokenMapSync();
+    reloadTokenMapSync();
   } catch (e) {
     // On initial load a bad file is fatal — refuse to start in a known-bad
     // auth state. On SIGHUP, log and keep the previous (valid) map.
@@ -361,7 +425,7 @@ function loadTokenMap(initial: boolean): void {
     return;
   }
   if (!initial) {
-    console.error(`[agent-coord-mcp] SIGHUP: token map reloaded (${tokenMap?.size ?? 0} agents)`);
+    console.error(`[agent-coord-mcp] SIGHUP: token map reloaded (${getTokenMap()?.size ?? 0} agents)`);
   }
 }
 
@@ -396,7 +460,7 @@ async function main() {
 
 async function startHttp(port: number): Promise<void> {
   const sharedToken = process.env.AGENT_COORD_TOKEN;
-  const bound = tokenMap !== null;
+  const bound = getTokenMap() !== null;
   if (!bound && !sharedToken) {
     console.error(
       "[agent-coord-mcp] HTTP mode needs auth: either set AGENT_COORD_TOKEN (legacy " +
@@ -486,6 +550,7 @@ async function startHttp(port: number): Promise<void> {
   function resolveBoundAgent(authHeader: string | undefined): { ok: boolean; agent?: string } {
     if (!authHeader || !authHeader.startsWith("Bearer ")) return { ok: false };
     const bearer = authHeader.slice("Bearer ".length);
+    const tokenMap = getTokenMap();
     if (tokenMap) {
       const agent = tokenMap.get(bearer);
       return agent ? { ok: true, agent } : { ok: false };
@@ -528,7 +593,7 @@ async function startHttp(port: number): Promise<void> {
       // a leaked session id could drive that session's identity (session hijack).
       if (
         transport &&
-        tokenMap &&
+        getTokenMap() &&
         typeof sid === "string" &&
         sessionAgents.get(sid) !== resolved.agent
       ) {
@@ -555,7 +620,7 @@ async function startHttp(port: number): Promise<void> {
   });
 
   http.listen(port, bindAddr, () => {
-    const mode = bound ? `pre-bound (${tokenMap?.size ?? 0} agents)` : "TOFU";
+    const mode = bound ? `pre-bound (${getTokenMap()?.size ?? 0} agents)` : "TOFU";
     console.error(`[agent-coord-mcp] http listening on ${bindAddr}:${port} — identity ${mode}`);
     if (bindAddr !== "127.0.0.1" && bindAddr !== "localhost") {
       console.error(

package/src/store.ts

@@ -63,8 +63,26 @@ export const ARCHIVE_STATUS_FILE = path.join(ARCHIVE_DIR, "status.jsonl");
 // startup warning). Should be mode 600; operator-managed.
 export const TOKENS_FILE = path.join(ROOT, "tokens.json");
 
+// Declared write scopes for managed documents (v0.18.0, Phase 8 Task 4).
+// Opt-in and operator-managed: absent → nothing is owned and nothing warns.
+// ADVISORY. The bus does not mediate writes to docs/QUEUE.md & friends —
+// agents edit them with ordinary file tools, so there is no interception
+// point. This file lets an agent ASK who owns a document (list_scopes) and
+// lets `doctor` DETECT drift after the fact. Pre-emptive enforcement waits
+// for Phase 8 Task 5, when work state moves into the store.
+export const SCOPES_FILE = path.join(ROOT, "scopes.json");
+
+// Work state as data (v0.18.0, Phase 8 Task 5). One file per project holding
+// the parsed QUEUE/DONE/board documents. DERIVED, not authoritative: the
+// markdown in the repo remains the source of truth, and deleting this
+// directory costs an `import_work`, never data (see src/work.ts).
+export const WORK_DIR = path.join(ROOT, "work");
+export function workFile(project: string): string {
+  return path.join(WORK_DIR, `${sanitize(project)}.json`);
+}
+
 export function ensureDirs(): void {
-  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR, TRANSPORT_DIR, PID_DIR, LOG_DIR, ROOMS_DIR, RECEIPTS_DIR, HISTORY_DIR]) {
+  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR, TRANSPORT_DIR, PID_DIR, LOG_DIR, ROOMS_DIR, RECEIPTS_DIR, HISTORY_DIR, WORK_DIR]) {
     if (!existsSync(d)) mkdirSync(d, { recursive: true });
   }
   for (const f of [ROOM_FILE, STATUS_FILE]) {
@@ -105,18 +123,59 @@ export function readTokenMapSync(): Map<string, string> | null {
   return out;
 }
 
+// In-process cache of the token map, shared by the HTTP identity-binding
+// layer (server.ts) and rotateAgentToken below. A module-level cache (rather
+// than each caller re-reading the file) is what lets a rename refresh the
+// live server's view without an operator SIGHUP.
+let tokenMapCache: Map<string, string> | null = null;
+let tokenMapInitialized = false;
+
+// Current in-process token map (bearer -> agentId), or null if unbound (no
+// tokens.json). Lazily loads from disk on first call.
+export function getTokenMap(): Map<string, string> | null {
+  if (!tokenMapInitialized) {
+    tokenMapCache = readTokenMapSync();
+    tokenMapInitialized = true;
+  }
+  return tokenMapCache;
+}
+
+// Re-read tokens.json from disk and replace the in-process cache. Throws on
+// a malformed file — callers decide whether that's fatal (startup) or
+// recoverable (SIGHUP, post-rotate refresh).
+export function reloadTokenMapSync(): Map<string, string> | null {
+  tokenMapCache = readTokenMapSync();
+  tokenMapInitialized = true;
+  return tokenMapCache;
+}
+
 // Atomically rotate the token entry for an agent rename (used by
 // rename_agent so the same bearer continues to authenticate the renamed
 // identity). No-op if the file is absent or the old id isn't in the map.
 export async function rotateAgentToken(oldAgentId: string, newAgentId: string): Promise<void> {
   if (!existsSync(TOKENS_FILE)) return;
+  let rotated = false;
   await updateJson<Record<string, string>>(TOKENS_FILE, {}, (current) => {
     if (current[oldAgentId] !== undefined) {
       current[newAgentId] = current[oldAgentId];
       delete current[oldAgentId];
+      rotated = true;
     }
     return current;
   });
+  if (rotated) {
+    // Refresh the in-process cache immediately: without this, the renamed
+    // agent's bearer keeps resolving to the OLD id in this process until an
+    // operator sends SIGHUP, silently misattributing its calls.
+    try {
+      reloadTokenMapSync();
+    } catch (e) {
+      console.error(
+        `[agent-coord-mcp] rename_agent: token map reload after rotate failed: ${(e as Error).message} ` +
+          `(keeping previous in-process map; send SIGHUP to retry)`,
+      );
+    }
+  }
 }
 
 export type RoomEntry = {

package/src/tools/admin.ts

@@ -30,6 +30,7 @@ import {
   type Cursor,
   type Message,
   type StatusEntry,
+  isDecision,
 } from "./shared.js";
 
 // ---------- prune ----------
@@ -47,10 +48,15 @@ export const pruneSchema = {
   dryRun: z.boolean().optional(),
 };
 
-// Retention predicate: kind="decision" messages live by the (longer)
-// decision cutoff; everything else by the standard cutoff.
-function keepEntry(e: { ts: number; kind?: string }, cutoff: number, decisionCutoff: number): boolean {
-  return e.kind === "decision" ? e.ts > decisionCutoff : e.ts > cutoff;
+// Retention: decisions live by the (longer) decision cutoff; everything else
+// by the standard cutoff. What counts as a decision is `isDecision` — the
+// shared predicate, not a fourth copy of the comparison.
+function keepEntry(
+  e: { ts: number; kind?: string; record?: { type?: string } },
+  cutoff: number,
+  decisionCutoff: number,
+): boolean {
+  return isDecision(e) ? e.ts > decisionCutoff : e.ts > cutoff;
 }
 
 // Shift every agent's cursor offsets down by the number of entries removed

package/src/tools/index.ts

@@ -4,3 +4,5 @@ export * from "./rooms.js";
 export * from "./messaging.js";
 export * from "./transport.js";
 export * from "./admin.js";
+export * from "./scopes.js";
+export * from "./work.js";

package/src/tools/messaging.ts

@@ -1,11 +1,13 @@
 import { adjustCursors } from "./admin.js";
-import { ARCHIVE_STATUS_FILE, archiveJsonl, archiveRoomFile } from "../store.js";
+import { RECORD_AUTHORITY, resolveRole, roleMatches } from "../roles.js";
+import { ARCHIVE_STATUS_FILE, archiveJsonl, archiveInboxFile, archiveRoomFile } from "../store.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { renderRecord } from "./render.js";
 import path from "node:path";
 import {
   AGENTS_FILE,
@@ -53,6 +55,7 @@ import {
   type AgentEntry,
   type AgentRegistry,
   type Message,
+  type MessageRecord,
   type StatusEntry,
   type Cursor,
   type Source,
@@ -65,25 +68,149 @@ import {
   STALE_MS,
   EVICT_MS,
   MAX_WAIT_MS,
+  isDecision,
 } from "./shared.js";
 
 // ---------- send_message ----------
 
+// Typed protocol record (Phase 8). Additive: omitting it reproduces v1
+// behavior exactly.
+const citationSchema = z.object({
+  kind: z.enum(["pr", "file", "commit", "url"]),
+  ref: z.string().min(1),
+});
+
+// Payloads are LOOSE objects: a v3 sender's extra keys ride through to disk
+// untouched rather than being silently stripped. That is safe precisely
+// because payload is nested — it is caller data, and nothing in it is ever
+// read as a top-level Message field (which is what keeps a forged `tag` or
+// `urgent` out; see the source-level lock in test/tier.test.mjs).
+const summaryPayload = z.looseObject({ summary: z.string().min(1) });
+
+// All five fields, or none. A `decision` carrying three of them is
+// structurally wrong for the type it claims — and would render as a truncated
+// packet, which is worse than no packet.
+const decisionPayload = z.looseObject({
+  title: z.string().min(1),
+  context: z.string().min(1),
+  options: z.array(z.string().min(1)).min(1),
+  recommendation: z.string().min(1),
+  ifNoAction: z.string().min(1),
+});
+
+const verdictPayload = z.looseObject({
+  result: z.enum(["pass", "fail"]),
+  headRefOid: z.string().min(1),
+  notes: z.string().optional(),
+});
+
+// Discriminated on `type`, so an unknown type is rejected outright while a
+// known type is checked only against its own shape. `payload` is optional on
+// every arm: Phase 8 is additive and may not put a new required field on the
+// wire. `cites` is optional here too — `done` needs a PR citation, but that is
+// enforced in sendMessageTool as a plain {ok:false,error}, mirroring the
+// identity-binding rejection, rather than as a schema throw.
+export const messageRecordSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("decision"), payload: decisionPayload.optional(), cites: z.array(citationSchema).optional() }),
+  z.object({ type: z.literal("verdict"), payload: verdictPayload.optional(), cites: z.array(citationSchema).optional() }),
+  z.object({ type: z.literal("done"), payload: summaryPayload.optional(), cites: z.array(citationSchema).optional() }),
+  z.object({ type: z.literal("blocker"), payload: summaryPayload.optional(), cites: z.array(citationSchema).optional() }),
+  z.object({ type: z.literal("risk"), payload: summaryPayload.optional(), cites: z.array(citationSchema).optional() }),
+  z.object({ type: z.literal("fyi"), payload: summaryPayload.optional(), cites: z.array(citationSchema).optional() }),
+  z.object({ type: z.literal("action"), payload: summaryPayload.optional(), cites: z.array(citationSchema).optional() }),
+  z.object({ type: z.literal("go"), payload: summaryPayload.optional(), cites: z.array(citationSchema).optional() }),
+  z.object({ type: z.literal("scope"), payload: summaryPayload.optional(), cites: z.array(citationSchema).optional() }),
+]);
+
+// ---------- record authority (Phase 8 Task 4) ----------
+
+// The table (RECORD_AUTHORITY, ../roles.ts) is a floor on the three types
+// other agents ACT on; everything else is unrestricted.
+//
+// NOT A TRUST BOUNDARY. A role is self-declared at register/join (there is no
+// authority issuing them), so this is a CONSISTENCY check: it stops a worker
+// from accidentally emitting a `verdict` or countersigning its own `scope`,
+// the same way a linter stops a typo. Anything that must actually be
+// authenticated has to resolve identity-bound tokens (see tokens.json), never
+// this table.
+// Rejection shape mirrors the identity-binding rejection in server.ts: the
+// caller gets a plain `{ok: false, error}`, and nothing is written.
+export async function checkRecordAuthority(
+  from: string,
+  record: MessageRecord | undefined,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  if (!record) return { ok: true };
+  const rule = RECORD_AUTHORITY[record.type];
+  if (!rule) return { ok: true };
+
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+  const entry = reg[from];
+  if (roleMatches(entry, rule.roles)) return { ok: true };
+
+  const held = resolveRole(entry);
+  return {
+    ok: false,
+    error:
+      `record.type '${record.type}' is restricted to ${rule.label} roles ` +
+      `(${[...rule.roles].join(", ")}); sender '${from}' holds ` +
+      `${held ? `role '${held.roleId}'` : entry ? "no role" : "no registry entry"}. ` +
+      `Send it as text, or register with the role that owns this record type.`,
+  };
+}
+
 export const sendMessageSchema = {
   from: z.string().min(1),
   to: z.string().optional(),
   room: z.string().optional(),
-  text: z.string().min(1),
+  // Optional ONLY so a record can fill it (Task 3.3). This relaxes a
+  // constraint rather than adding one, so v1 senders are unaffected; a call
+  // with neither `text` nor a renderable `record` is rejected in the tool.
+  text: z.string().min(1).optional(),
   kind: z.enum(["decision", "status", "chatter"]).optional(),
+  record: messageRecordSchema.optional(),
 };
 
 export async function sendMessageTool(args: {
   from: string;
   to?: string;
   room?: string;
-  text: string;
+  text?: string;
   kind?: "decision" | "status" | "chatter";
+  record?: MessageRecord;
 }) {
+  // Record authority first — a sender who may not emit this type is refused
+  // before any other check runs, so a rejected record writes nothing anywhere.
+  const authority = await checkRecordAuthority(args.from, args.record);
+  if (!authority.ok) return { ok: false as const, error: authority.error };
+
+  // A `done` must cite the work it claims. Presence and shape only — resolving
+  // the ref against gh/git is a consumer's job, and the send path makes no
+  // network calls. Rejected as a value, not a throw, mirroring the
+  // identity-binding rejection in src/server.ts.
+  if (args.record?.type === "done") {
+    const hasPr = (args.record.cites ?? []).some((c) => c.kind === "pr" && c.ref.trim().length > 0);
+    if (!hasPr) {
+      return {
+        ok: false as const,
+        error:
+          "a 'done' record must carry at least one {kind:'pr'} citation — an uncited DONE is an unverifiable claim",
+      };
+    }
+  }
+
+  // `text` is what every consumer reads, so it must exist. The author's
+  // wording ALWAYS wins: a record renders only to fill an absent text, never
+  // to overwrite one.
+  const text = args.text ?? (args.record ? renderRecord(args.record) : null);
+  if (!text) {
+    return {
+      ok: false as const,
+      error: args.record
+        ? `record type '${args.record.type}' has no payload to render — supply 'text', or a payload the type's layout can render`
+        : "'text' is required when no record is supplied",
+    };
+  }
+
   // DM → inbox. Otherwise resolve the channel (default `general`), make sure it
   // exists in the registry, and tag the message with its channel.
   if (args.to) {
@@ -92,7 +219,8 @@ export async function sendMessageTool(args: {
       ts: Date.now(),
       from: args.from,
       to: args.to,
-      text: args.text,
+      text,
+      ...(args.record ? { record: args.record } : {}),
     };
     const target = inboxFile(args.to);
     await appendJsonl(target, msg);
@@ -113,8 +241,9 @@ export async function sendMessageTool(args: {
     ts: Date.now(),
     from: args.from,
     room: chan,
-    text: args.text,
+    text,
     ...(args.kind ? { kind: args.kind } : {}),
+    ...(args.record ? { record: args.record } : {}),
   };
   const target = roomFile(chan);
   await appendJsonl(target, msg);
@@ -154,7 +283,7 @@ async function maybeCompactRoom(chan: string): Promise<void> {
   const r = await archiveJsonl<Message>(
     file,
     archiveRoomFile(chan),
-    (e) => e.ts >= boundaryTs || (e.kind === "decision" && e.ts > decisionCutoff)
+    (e) => e.ts >= boundaryTs || (isDecision(e) && e.ts > decisionCutoff)
   );
   if (r.removed > 0) await adjustCursors({ roomRemovedByChan: { [chan]: r.removed } });
 }
@@ -287,7 +416,7 @@ function digestOverflow(over: (Message | StatusEntry)[], hash: string | undefine
     : `] — read without peek to get an expandable hash`;
   // Decisions are the one thing a digest must not bury — quote them verbatim
   // (capped) below the summary line.
-  const decisions = over.filter((m): m is Message => (m as Message).kind === "decision");
+  const decisions = over.filter((m): m is Message => isDecision(m as Message));
   const quoted = decisions
     .slice(-5)
     .map((d) => `  [decision] ${d.from}: ${d.text.length > 200 ? d.text.slice(0, 200) + "…" : d.text}`);
@@ -297,6 +426,76 @@ function digestOverflow(over: (Message | StatusEntry)[], hash: string | undefine
   return head + tail + decisionBlock;
 }
 
+// ---------- retrieve_message (Phase 8 Task 6) ----------
+
+export const retrieveMessageSchema = {
+  agentId: z.string().min(1),
+  id: z.string().min(1),
+};
+
+// Expand a digest handle back into the full typed record.
+//
+// NOT a cache. The handle is the message's own `id`, and this reads the source
+// of truth — rooms/<chan>.jsonl or inbox/<agent>.jsonl. That matters for two
+// reasons the CCR history cache could not offer: nothing is duplicated, and
+// nothing expires. A stashed copy would have carried HISTORY_TTL_MS and become
+// permanently unrecoverable after 30 minutes, which is exactly when a handle
+// that outlived a /clear would be expanded.
+//
+// It also sidesteps the cursor: the pusher SHARES the cursor file with
+// read_messages, so anything already delivered to a pane is behind the cursor
+// and re-reading the channel would not return it. A by-id lookup never
+// consults a cursor.
+//
+// AUTHORITY BY CONSTRUCTION: we only ever open files this agent is entitled to
+// read — its own inbox, and the rooms it is a member of. There is no separate
+// permission check that could disagree with the search, and a handle for a
+// message delivered somewhere else simply is not found. That is the same
+// property the history cache spent `forAgent` scoping to get.
+export async function retrieveMessageTool(args: { agentId: string; id: string }) {
+  const rooms = await memberRooms(args.agentId);
+  const scopes = [
+    {
+      source: "inbox" as const,
+      room: undefined as string | undefined,
+      live: inboxFile(args.agentId),
+      archived: archiveInboxFile(args.agentId),
+    },
+    ...rooms.map((r) => ({
+      source: "room" as const,
+      room: r as string | undefined,
+      live: roomFile(r),
+      archived: archiveRoomFile(r),
+    })),
+  ];
+
+  // Live files first. The archive is opened ONLY on a miss, so no normal
+  // retrieval touches it and compaction/prune semantics are unchanged — but a
+  // record that compaction moved is still recoverable, because archive/ is
+  // append-only and complete.
+  for (const pass of ["live", "archived"] as const) {
+    for (const s of scopes) {
+      const entries = await readJsonl<Message>(s[pass]);
+      const msg = entries.find((m) => m.id === args.id);
+      if (msg) {
+        return {
+          ok: true as const,
+          id: msg.id,
+          source: s.source,
+          room: s.room,
+          archived: pass === "archived",
+          message: msg,
+          record: msg.record,
+        };
+      }
+    }
+  }
+  return {
+    ok: false as const,
+    error: `no message '${args.id}' in any channel you can read — it may never have been delivered to you`,
+  };
+}
+
 // ---------- retrieve_room_history ----------
 
 export const retrieveRoomHistorySchema = {