agent-coord-mcp 0.19.1 → 0.23.0

package/src/server.ts

@@ -5,6 +5,7 @@ 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 { unlinkSync, writeFileSync } from "node:fs";
+import { z, type ZodRawShape } from "zod";
 import {
   ensureDirs,
   getTokenMap,
@@ -240,10 +241,21 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   const server = new McpServer({
     name: "agent-coord",
-    version: "0.1.0",
+    version: "0.23.0",
   });
 
-  server.tool(
+  const addTool = (
+    name: string,
+    description: string,
+    inputSchema: ZodRawShape,
+    cb: (args: Record<string, unknown>) => Promise<ReturnType<typeof jsonResult>>,
+  ) => {
+    server.registerTool(name, { description, inputSchema: z.object(inputSchema) }, async (args) =>
+      cb((args ?? {}) as Record<string, unknown>),
+    );
+  };
+
+  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.",
     joinSchema,
@@ -266,147 +278,147 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     },
   );
 
-  server.tool(
+  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.",
     registerSchema,
     gate("agentId", registerTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "unregister",
     "Tear down this agent: detach any attached transport (kills the pusher) and remove the registry entry. Clean shutdown counterpart to `join`.",
     unregisterSchema,
     gate("agentId", unregisterTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "quit",
     "Clean shutdown: unregister this agent (detach transport, leave rooms, remove registry entry) then exit the MCP process. Only callable by the session's bound identity. Use this to cleanly hand off before a restart with a new name.",
     quitSchema,
     gate("agentId", quitTool as unknown as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "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'. Read-only — naming an agentId here never binds this session's identity.",
     statusSchema,
     gate("agentId", statusTool as (a: Record<string, unknown>) => Promise<unknown>, { bindOnClaim: false }),
   );
 
-  server.tool(
+  addTool(
     "heartbeat",
     "Refresh this agent's lastHeartbeat timestamp.",
     heartbeatSchema,
     gate("agentId", heartbeatTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "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, but read-only — naming 'from' here never binds this session's identity.",
     pingSchema,
     gate("from", pingTool as (a: Record<string, unknown>) => Promise<unknown>, { bindOnClaim: false }),
   );
 
-  server.tool(
+  addTool(
     "list_agents",
     "List all known agents and whether they appear online (heartbeat <5min).",
     listAgentsSchema,
     gate(null, listAgentsTool as () => Promise<unknown>),
   );
 
-  server.tool(
+  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. The 'from' field is enforced against the session's bound identity when binding is configured.",
     sendMessageSchema,
     gate("from", sendMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "send_command",
     "Inject a context-management slash command (/clear or /compact) directly into a sub-agent's live tmux session — delivered RAW with no banner or prefix, so the agent's CLI runs it as a real slash command. Target one agent with 'to' or broadcast to a channel's tmux-attached members with 'room' (never the sender). Hard-gated to tmux: returns ok:false if the target has no live tmux-push(-remote) transport. By default BLOCKS until the receiving pusher confirms it actually typed the command into the pane (out-of-band delivery receipt, no added agent context) and returns delivery:'confirmed' with deliveredAt, or delivery:'pending'+warning if no receipt arrived within deliveryTimeoutMs (default 8000) — a stale/wedged pusher. Pass waitForDelivery:false for fire-and-forget. Intended for a lead agent to clear/compact sub-agent context and save tokens. The command allowlist is locked to /clear and /compact; nothing else is accepted. 'from' is enforced against the session's bound identity.",
     sendCommandSchema,
     gate("from", sendCommandTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "read_messages",
     "Read new messages from inbox|room|status. For source='room', pass 'room' to read a specific channel (default 'general'). Room and status reads return the most recent 50 entries per call — pass limit to override (max 500). When the backlog exceeds the window, the older overflow is replaced by a compact `history` digest carrying a retrieval hash; call retrieve_room_history(hash) to expand it. Inbox drains fully by default. Advances the per-channel cursor unless peek=true.",
     readMessagesSchema,
     gate("agentId", readMessagesTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "retrieve_room_history",
     "Expand a compressed channel-history digest returned by read_messages. Pass the `hash` from the `history` field; optionally pass `query` to return only matching messages (case-insensitive substring). Entries are scoped to the agent that produced them and expire after 30 minutes — if expired, re-read the channel with a higher limit instead.",
     retrieveRoomHistorySchema,
     gate("agentId", retrieveRoomHistoryTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "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(
+  addTool(
     "post_status",
     "Append a status broadcast to the shared status stream.",
     postStatusSchema,
     gate("agentId", postStatusTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "prune",
     "Trim room/status/inbox JSONL to entries newer than `olderThanDays` (default 7); kind='decision' posts keep a longer `decisionDays` retention (default 30). Nothing is lost: aged-out entries are archived under archive/ (rooms/<chan>.jsonl, status.jsonl, inbox/<agent>.jsonl) — only receipts are truly deleted. `room` and `targets` compose: `room` scopes every sweep to that channel (and, alone, defaults the sweep to `rooms` only), while `targets` (rooms|status|inbox|receipts|members) selects which sweeps run and always wins over that default — so `{room, targets:['members']}` sweeps membership in that one channel. Sweeps room members that are unregistered or haven't heartbeated since the cutoff, and archives+removes non-default rooms left empty and inactive (disable via archiveEmptyRooms=false). Removes inbox files for agents no longer in the registry unless removeOrphanInboxes=false. Pass dryRun=true to preview.",
     pruneSchema,
     gate(null, pruneTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "wait_for_message",
     "Block (max 60s) until a new message appears on the given source, then return it. For source='room', pass 'room' to wait on a specific channel (default 'general').",
     waitForMessageSchema,
     gate("agentId", waitForMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "list_rooms",
     "List all channels with their topic, MOTD (room rules), members, message count, and last activity.",
     listRoomsSchema,
     gate(null, listRoomsTool as () => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "join_room",
     "Join a channel (creating it if new). Adds this agent to the channel's membership so the notification hooks push its messages. Posts a system join notice to the channel. Returns the channel's topic, MOTD, member list, and unread message count — but not the messages themselves. Call read_messages to fetch history if needed.",
     joinRoomSchema,
     gate("agentId", joinRoomTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "leave_room",
     "Leave a channel — removes this agent from its membership. Cannot leave the default 'general' channel.",
     leaveRoomSchema,
     gate("agentId", leaveRoomTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "set_room_topic",
     "Set a channel's topic (a short one-line description). Posts a system notice to the channel.",
     setRoomTopicSchema,
     gate("agentId", setRoomTopicTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "set_room_motd",
     "Set a channel's MOTD / room rules (shown to agents on join). Posts a system notice to the channel.",
     setRoomMotdSchema,
     gate("agentId", setRoomMotdTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "rename_agent",
     "Rename an agent (NICK): migrates its registry entry, inbox, cursor, and channel memberships to the new id, then broadcasts a rename notice to its channels. When tokens.json identity binding is on, the caller's bearer token is atomically rotated to the new id so the same session keeps authenticating after rename. If a live tmux-push transport is attached it is detached first (the pusher is bound to the old id) — re-attach as the new id (join/attach_agent) to restore real-time delivery; the response sets detachedTransport + a warning when this happens.",
     renameAgentSchema,
@@ -438,84 +450,84 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     },
   );
 
-  server.tool(
+  addTool(
     "attach_agent",
     "Start the tmux-push transport for an agent: spawns hooks/tmux-pusher.mjs as a background process so peer DMs (and optionally room messages) get typed into the agent's tmux pane in real time. tmuxTarget defaults to the MCP server's own $TMUX_PANE if this server is running inside tmux. allowlist restricts which peer agentIds can push. Updates list_agents to show transport=tmux-push.",
     attachAgentSchema,
     gate("agentId", attachAgentTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "detach_agent",
     "Stop the tmux-push transport for an agent: kills the pusher process and clears the transport marker.",
     detachAgentSchema,
     gate("agentId", detachAgentTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "report_transport",
     "Publish a transport marker for an agent (used by the remote tmux pusher, scripts/coord-pusher.mjs, to surface itself in list_agents). Set transport='tmux-push-remote' and optionally host/tmuxTarget. Liveness for remote markers is heartbeat-based — keep calling heartbeat or this marker gets GC'd after staleness.",
     reportTransportSchema,
     gate("agentId", reportTransportTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "clear_transport",
     "Idempotent delete of an agent's transport marker. The wire-callable counterpart to detach_agent for remote pushers: it only removes the marker — there's no local process to kill.",
     clearTransportSchema,
     gate("agentId", clearTransportTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "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(
+  addTool(
     "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.",
     doctorSchema,
     gate(null, doctorTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "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(
+  addTool(
     "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.",
+    "Read a project's work documents (docs/QUEUE.md + docs/DONE.md, or the legacy docs/BACKLOG.md, plus docs/WORKSTREAMS.md and optional docs/FACTS.md) into typed records: queue items {priority,text,done}, done entries {text,ref,date}, board rows, and facts {id,claim,verified,by,method}. The markdown stays authoritative — this store is a derived index, and export_work renders queue/done/board back byte-identically (FACTS is not an export write target).",
     importWorkSchema,
     gate(null, importWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "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.",
+    "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, the board's lane rows, and facts. 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(
+  addTool(
     "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.",
+    "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. Refuses write:true when that write would emit a new 5-col lanes-v0 table (parse-only; write grammar is workstreams.v1). 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(
+  addTool(
     "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.",
     deleteRoomSchema,
     gate("agentId", deleteRoomTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "force_unregister",
     "Admin eviction: unregisters any agent by targetAgentId regardless of the caller's identity. Detaches the agent's transport, removes it from all channel memberships, and drops its registry entry. Use after a reboot to clean up stale agents that can no longer unregister themselves.",
     forceUnregisterSchema,

package/src/tools/render.ts

@@ -1,80 +1 @@
-// Typed record → the text layout the fleet already reads (Phase 8 Task 3.3).
-//
-// Every consumer downstream of a message — hooks/tier.mjs's prefix table, the
-// UI's alert parser, a human reading a tmux pane — reads `text`. Phase 8 adds
-// `record` alongside it, so the rendering must reproduce the byte layout those
-// consumers already expect. Nothing downstream changes while agents migrate.
-//
-// This is a pure function of the record: no clock, no I/O, no registry. It
-// never sees `from`, `to`, or anything the sender could use it to forge.
-
-import type { DecisionPayload, MessageRecord, SummaryPayload, VerdictPayload } from "./shared.js";
-
-// The case-sensitive prefixes at byte 0 of `text`, exactly as classifyTier
-// matches them. `decision` is absent because it renders as a multi-line block,
-// not a one-liner.
-const PREFIX: Record<string, string> = {
-  blocker: "BLOCKER",
-  risk: "RISK",
-  done: "DONE",
-  fyi: "FYI",
-  action: "AGENT_ACTION",
-  go: "GO",
-  scope: "SCOPE CHANGE",
-  // `verdict` has no prefix in the v1 vocabulary — it is new in Phase 8. A gate
-  // PASS/FAIL was previously posted as prose, which is why verdicts could not
-  // be routed. Rendering it under its own prefix gives it one.
-  verdict: "VERDICT",
-};
-
-function isNonEmpty(v: unknown): v is string {
-  return typeof v === "string" && v.trim().length > 0;
-}
-
-// The playbook's decision packet (§Decision Packet Format), byte-for-byte —
-// the UI parses this into a clickable decision card, and a layout that drifts
-// still alerts loudly but loses the card. Returns null when any of the five
-// fields is missing, so the caller can reject rather than emit a half packet.
-function renderDecision(p: DecisionPayload): string | null {
-  if (!isNonEmpty(p.title) || !isNonEmpty(p.context)) return null;
-  if (!isNonEmpty(p.recommendation) || !isNonEmpty(p.ifNoAction)) return null;
-  if (!Array.isArray(p.options) || p.options.length === 0) return null;
-  if (!p.options.every(isNonEmpty)) return null;
-  return [
-    `DAVID_DECISION: ${p.title}`,
-    `Context: ${p.context}`,
-    "Options:",
-    ...p.options.map((o, i) => `${i + 1}. ${o}`),
-    `Recommendation: ${p.recommendation}`,
-    `If no action: ${p.ifNoAction}`,
-  ].join("\n");
-}
-
-// `VERDICT: PASS <sha> — <notes>`. The sha is not optional in the rendering:
-// a verdict that doesn't name the commit it was issued against is
-// unfalsifiable the moment the branch moves.
-function renderVerdict(p: VerdictPayload): string | null {
-  if (p.result !== "pass" && p.result !== "fail") return null;
-  if (!isNonEmpty(p.headRefOid)) return null;
-  const head = `${PREFIX.verdict}: ${p.result.toUpperCase()} ${p.headRefOid}`;
-  return isNonEmpty(p.notes) ? `${head} — ${p.notes}` : head;
-}
-
-// Render a record to its text form, or null when the payload can't support one
-// (absent, or missing a field the layout needs). Null is not an error here —
-// the caller decides whether a record without a rendering is fatal, and it only
-// is when there's no author-supplied `text` to fall back on.
-export function renderRecord(record: MessageRecord): string | null {
-  if (!record || typeof record.type !== "string") return null;
-  const payload = record.payload as unknown;
-  if (payload === undefined || payload === null) return null;
-  if (typeof payload !== "object" || Array.isArray(payload)) return null;
-
-  if (record.type === "decision") return renderDecision(payload as DecisionPayload);
-  if (record.type === "verdict") return renderVerdict(payload as VerdictPayload);
-
-  const prefix = PREFIX[record.type];
-  if (!prefix) return null;
-  const { summary } = payload as SummaryPayload;
-  return isNonEmpty(summary) ? `${prefix}: ${summary}` : null;
-}
+export { renderRecord, PREFIX } from "@davidbalzan/groundwork-seam/protocol";

package/src/tools/shared.ts

@@ -1,3 +1,12 @@
+import type {
+  Citation,
+  DecisionPayload,
+  MessageRecord,
+  MessageRecordType,
+  SummaryPayload,
+  SummaryRecordType,
+  VerdictPayload,
+} from "@davidbalzan/groundwork-seam/protocol";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
@@ -92,82 +101,16 @@ export type TransportMarker = {
 
 export type AgentRegistry = Record<string, AgentEntry>;
 
-// Where a claim can be independently verified. The point is that a consumer
-// resolves the ref (gh, git, fs) instead of trusting the message body — a
-// `done` record whose PR ref doesn't exist is a false claim, not a typo.
-export type Citation = {
-  kind: "pr" | "file" | "commit" | "url";
-  ref: string;
+export type {
+  Citation,
+  MessageRecordType,
+  DecisionPayload,
+  VerdictPayload,
+  SummaryPayload,
+  SummaryRecordType,
+  MessageRecord,
 };
 
-// The protocol vocabulary the fleet already speaks. Today these live as
-// case-sensitive prefixes at byte 0 of `text` (hooks/tier.mjs), parsed a
-// second time by the UI for alert priority — so a greeting before the prefix
-// silently downgrades a production blocker, and the two parsers can disagree
-// about the same message. As a field there is nothing to mis-parse.
-export type MessageRecordType =
-  | "blocker"   // BLOCKER:        work cannot continue
-  | "decision"  // DAVID_DECISION: the human must decide
-  | "risk"      // RISK:           quality/security/cost/product risk
-  | "done"      // DONE:           completed work, must cite
-  | "fyi"       // FYI:            no action needed
-  | "action"    // AGENT_ACTION:   another agent can handle it
-  | "go"        // GO:             a work order
-  | "scope"     // SCOPE CHANGE:   amends a contract in flight
-  | "verdict";  // (new) a gate PASS/FAIL — has no prefix today
-
-// The five fields of the playbook's decision packet (§Decision Packet Format).
-// Named to match that layout because `renderRecord` reproduces it byte-for-byte
-// — the UI parses the rendering into a clickable decision card.
-export type DecisionPayload = {
-  title: string;
-  context: string;
-  options: string[];
-  recommendation: string;
-  ifNoAction: string;
-};
-
-// A gate verdict. `headRefOid` pins WHICH commit was gated: a PASS that doesn't
-// name the sha it was issued against is unfalsifiable once the branch moves.
-export type VerdictPayload = {
-  result: "pass" | "fail";
-  headRefOid: string;
-  notes?: string;
-};
-
-// Everything else carries prose. One line, because these render as
-// `<PREFIX>: <summary>` and a paragraph in a tmux pane is a wall, not a status.
-export type SummaryPayload = { summary: string };
-
-// Message types whose payload is just a summary.
-export type SummaryRecordType = "blocker" | "risk" | "fyi" | "action" | "go" | "scope";
-
-// Structured counterpart to `text`, NOT a replacement: `text` is the rendering,
-// and a tmux pane can only receive text. A v1 agent that has never heard of
-// `record` omits it entirely and behaves byte-identically.
-//
-// `payload` stays OPTIONAL on every arm — Phase 8 is additive, so no new
-// required field may appear on the wire. What is pinned is the shape *if* a
-// payload is supplied: a `decision` carrying three of its five fields is
-// structurally wrong for the type it claims and is rejected, while a payload
-// with extra unknown keys passes through untouched (a v3 sender must not be
-// broken by a v2 server, and stripping would silently drop data on the way to
-// disk).
-//
-// `cites` is likewise optional here. `done` requires a PR citation, but that is
-// enforced in sendMessageTool as a plain {ok:false,error} rather than a schema
-// rejection — see the identity-binding precedent in src/server.ts.
-//
-// UNTRUSTED, exactly like `from`. A peer can claim any type here, so trust
-// decisions (the SCOPE countersignature, gate-runner routing) must still
-// resolve the sender against the registry — typed is not the same as
-// authenticated, and `record` must never become a path to setting `urgent`.
-export type MessageRecord =
-  | { type: "decision"; payload?: DecisionPayload; cites?: Citation[] }
-  | { type: "verdict"; payload?: VerdictPayload; cites?: Citation[] }
-  | { type: "done"; payload?: SummaryPayload; cites?: Citation[] }
-  | { type: SummaryRecordType; payload?: SummaryPayload; cites?: Citation[] };
-
 export type Message = {
   id: string;
   ts: number;
@@ -215,9 +158,7 @@ export type Message = {
 //
 // Deliberately structural about `record`: it takes anything with the two
 // fields, so status entries and archive rows can be passed without a cast.
-export function isDecision(e: { kind?: string; record?: { type?: string } } | null | undefined): boolean {
-  return e?.kind === "decision" || e?.record?.type === "decision";
-}
+export { isDecision } from "@davidbalzan/groundwork-seam/protocol";
 
 export type StatusEntry = {
   id: string;