agent-coord-mcp 0.26.24 → 0.26.26

package/hooks/submit.mjs

@@ -281,6 +281,168 @@ export function readPaneState(paneText) {
   return { busy, draft, ghost, styledInputLine };
 }
 
+// ⟨q-15d763dc⟩ NO KEY REACHES A PANE UNLESS ITS READY INPUT BOX IS POSITIVELY IDENTIFIED.
+//
+// Measured 2026-09-16 on a real Claude Code pane: with the /model picker open, a push typed its
+// text and pressed Enter. The picker took the Enter, wrote ~/.claude/settings.json, closed, and
+// left an empty `❯` prompt behind, so the push reported verified:true for a message Claude never
+// received. The same Enter on a permission prompt approves a tool call, and a message's text can
+// press a dialog's numeric option keys before any Enter. Any bus writer controls that text.
+// So readiness is decided BEFORE the first keystroke, from the SHAPE of the screen, and every
+// pusher (herdr.ts, tmux-pusher.mjs, coord-pusher.mjs) asks this one function. Do not re-implement it.
+//
+// PROFILES, decided once, from THIS PROCESS's environment at start and nowhere else:
+//   claude-code (default) — the only box shape known: a ─ rule, `❯` at column 0, a ─ rule,
+//                           then at most a few footer lines at the bottom of the screen.
+//                           Measured on Claude Code v2.1.273. Any other screen is HELD.
+//   none                  — the guard is off. For a harness with no profile yet (Aider, codex,
+//                           gemini-cli, opencode). Logged at start and surfaced in capabilities.
+// An unrecognised value is NOT "none": a typo must never unguard a seat.
+export const READY_PROFILES = Object.freeze(["claude-code", "none"]);
+export function resolveReadyProfile(raw) {
+  if (raw === undefined || raw === "") return { profile: "claude-code", raw: null };
+  if (READY_PROFILES.includes(raw)) return { profile: raw, raw };
+  return { profile: "claude-code", raw, warning: `AGENT_COORD_READY_PROFILE=${JSON.stringify(raw)} is not one of ${READY_PROFILES.join(", ")} — the guard stays ON (claude-code); a typo never unguards a seat` };
+}
+// Read ONCE, at module load, from process.env. Not re-read per call, so nothing that runs later in
+// the process (a message, a bus file, a tool call setting an env var) can switch the guard off.
+const READY_PROFILE_AT_START = Object.freeze(resolveReadyProfile(process.env.AGENT_COORD_READY_PROFILE));
+export function readyProfile() {
+  return READY_PROFILE_AT_START;
+}
+
+// The start-up line a pusher or server prints about its guard. Silent when guarded and unambiguous;
+// LOUD when the guard is off or the env value was not understood, so an unguarded seat is visible.
+export function readyProfileStartupLine(who) {
+  const p = READY_PROFILE_AT_START;
+  if (p.profile === "none") return `[${who}] ⛔ READY-BOX GUARD OFF (AGENT_COORD_READY_PROFILE=none, from this process's env): pushes are typed into panes WITHOUT checking for an input box — any open dialog or permission prompt can receive message text and Enter (q-15d763dc)\n`;
+  if (p.warning) return `[${who}] ⚠ ${p.warning}\n`;
+  return null;
+}
+
+// How many lines may sit below the input box's lower rule. Claude Code draws a footer there
+// (mode line, hints); a dialog, picker or autocomplete menu draws many more.
+export const READY_BOX_MAX_BELOW = 4;
+const RULE_RE = /^─{8,}$/;
+const BOX_LINE_RE = /^❯(?:\s|$)/;
+const MAX_DRAFT_LINES = 20;
+
+// Read the screen for Claude Code's input box. Returns:
+//   { ready: true,  draft, ghost, below, above, busy } — the box is on screen; draft "" means empty
+//   { ready: false, reason, unreadable? }              — no key may be sent
+//   { ready: true,  unguarded: true }                  — profile none: the caller's legacy path
+// `screen` may be plain or styled (herdr --format ansi, tmux capture-pane -e).
+export function readReadyBox(screen, profile = READY_PROFILE_AT_START.profile) {
+  if (profile === "none") return { ready: true, unguarded: true };
+  if (profile !== "claude-code") return { ready: false, reason: `unknown ready profile ${JSON.stringify(profile)} — held` };
+  if (screen === null || screen === undefined) return { ready: false, unreadable: true, reason: "the pane could not be read — no key was sent" };
+  const styled = String(screen).replace(/\r/g, "").split("\n");
+  const plain = styled.map((l) => stripAnsi(l).replace(/ /g, " ").replace(/\s+$/, ""));
+  let end = plain.length;
+  while (end > 0 && plain[end - 1].trim() === "") end--;
+  let p = -1;
+  for (let i = end - 1; i >= 0; i--) if (plain[i].includes("❯")) { p = i; break; }
+  if (p < 0) return { ready: false, reason: "no ❯ on screen — not Claude Code's input box (another harness, a shell, or a dialog without one)" };
+  if (!BOX_LINE_RE.test(plain[p])) return { ready: false, reason: `the last ❯ on screen is not at column 0 (${JSON.stringify(plain[p].trim().slice(0, 40))}) — a dialog, picker or menu row, not the input box` };
+  if (p === 0 || !RULE_RE.test(plain[p - 1].trim())) return { ready: false, reason: "the ❯ line has no ─ rule directly above it — not the input box" };
+  let q = -1;
+  for (let i = p + 1; i < end && i <= p + MAX_DRAFT_LINES; i++) {
+    if (RULE_RE.test(plain[i].trim())) { q = i; break; }
+    if (plain[i].includes("❯")) break;
+  }
+  if (q < 0) return { ready: false, reason: "the ❯ line has no ─ rule below it — not the input box" };
+  const belowLines = plain.slice(q + 1, end).filter((l) => l.trim() !== "");
+  if (belowLines.some((l) => RULE_RE.test(l.trim()))) return { ready: false, reason: "a second ruled box below the input — a dialog or menu is open" };
+  let real = "";
+  let ghost = "";
+  for (let i = p; i < q; i++) {
+    const part = partitionStyledLine(styled[i]);
+    real += " " + stripAnsi(part.real).replace(/ /g, " ");
+    ghost += " " + part.ghost;
+  }
+  const content = squash(real.replace(/^\s*❯/, ""));
+  const placeholder = PLACEHOLDER_PATTERN();
+  const draft = placeholder && new RegExp(placeholder).test(content) ? "" : content;
+  const busyRe = BUSY_PATTERN();
+  return {
+    ready: true,
+    draft,
+    ghost: squash(ghost) || null,
+    below: belowLines.length,
+    above: plain.slice(0, p - 1),
+    busy: busyRe ? new RegExp(busyRe).test(belowLines.join("\n")) : null,
+  };
+}
+
+// May a keystroke be sent at all? Ready box, EMPTY input (typing onto someone's draft concatenates
+// with it), and nothing drawn below the footer. `null` = yes; otherwise the reason nothing was sent.
+export function refusalBeforeKeys(box) {
+  if (!box.ready) return box.reason;
+  if (box.unguarded) return null;
+  if (box.draft) return `the input box already holds unsent text (${JSON.stringify(box.draft.slice(0, 40))}) — typing would join it`;
+  if (box.below > READY_BOX_MAX_BELOW) return `${box.below} lines drawn below the input box (the footer is at most ${READY_BOX_MAX_BELOW}) — a menu or dialog is open`;
+  return null;
+}
+
+// The pushers' form of refusalBeforeKeys: a pasteAndSubmit-shaped refusal, or null to proceed.
+function heldBeforeKeys(screen, target) {
+  const box = readReadyBox(screen);
+  const refusal = refusalBeforeKeys(box);
+  if (!refusal) return null;
+  return {
+    submitted: false,
+    verified: !box.unreadable, // true: we DID read the screen, and it is not a ready input box
+    pasted: false,
+    held: true,
+    attempts: 0,
+    reason: `held, nothing pasted into pane '${target}': ${refusal}`,
+  };
+}
+
+// Did the typed payload land IN the box (and not in whatever else might have taken the keys)?
+export function boxHoldsPayload(box, payload) {
+  if (!box.ready || box.unguarded || !box.draft) return false;
+  if (isPasteChip(box.draft)) return true;
+  const needle = squash(payload);
+  if (!needle) return false;
+  const head = needle.slice(0, 32);
+  return box.draft.includes(head) || (needle.startsWith(box.draft) && box.draft.length >= 8);
+}
+
+// After Enter: the box is back and EMPTY, and the transcript's LAST user-message echo is this
+// payload and is NEW. An empty box alone proves nothing: a dialog that ate the Enter and closed
+// leaves exactly that.
+//
+// THE ECHO SHAPE, measured on a live Claude Code v2.1.273 pane that the tmux pusher had delivered
+// into: a submitted message is drawn as `❯ <first line>` at column 0, its further lines indented
+// beneath, then a blank line; a message queued behind a running turn is drawn `  ❯ <first line>`
+// just above the box. Bus renders often share a first line ("[agent-coord] +1 routine …"), so
+// "a line carrying the head appeared" cannot be a set lookup: an older identical echo would
+// satisfy it. The whole echo block (the echo and its lines up to the first blank) must differ from
+// the one the screen showed before any key was sent. Spinner and status lines never enter it.
+const ECHO_RE = /^\s{0,2}❯ /;
+function lastEchoBlock(above) {
+  const lines = above ?? [];
+  let i = lines.length - 1;
+  while (i >= 0 && !ECHO_RE.test(lines[i])) i--;
+  if (i < 0) return null;
+  const block = [lines[i]];
+  for (let j = i + 1; j < lines.length && lines[j].trim() !== "" && /^\s/.test(lines[j]); j++) block.push(lines[j]);
+  return block.map((l) => squash(l)).join("\n");
+}
+export function transcriptGained(before, after, payload) {
+  if (!after.ready || after.unguarded || after.draft) return false;
+  const now = lastEchoBlock(after.above);
+  if (now === null) return false;
+  const first = now.split("\n")[0];
+  const line = squash(String(payload ?? "").split("\n").find((l) => l.trim()) ?? "");
+  const head = line.slice(0, 24);
+  // A short payload (a control command such as /clear) must match the echo exactly, not as a substring.
+  const matches = head.length >= 8 ? first.includes(head) : line !== "" && squash(first.replace(/^❯/, "")) === line;
+  if (!PASTE_CHIP_RE.test(first) && !matches) return false;
+  return now !== lastEchoBlock(before.above);
+}
+
 // Submit a CONTROL command (/clear, /compact, /reload-skills) — the path that must actually
 // run, not merely arrive.
 //
@@ -309,11 +471,18 @@ export async function submitControl(deps, payload) {
 
   const idleBudget = CONTROL_IDLE_WAIT_MS();
   const deadline = Date.now() + idleBudget;
-  let state = readPaneState(capture());
+  let screen = capture();
+  let state = readPaneState(screen);
   while (state.busy === true && idleBudget > 0 && Date.now() < deadline) {
     await sleep(VERIFY_POLL_MS() * 5);
-    state = readPaneState(capture());
+    screen = capture();
+    state = readPaneState(screen);
   }
+  // ⟨q-15d763dc⟩ No key before the ready input box is identified, read from the SAME screen the busy
+  // and draft guards below answer from. A dialog or picker row also matches PROMPT_PATTERN, so
+  // without this it would read as a draft at best, and as an empty input at worst.
+  const box = readReadyBox(screen);
+  if (!box.ready) return heldBeforeKeys(screen, target);
   if (state.busy === true) {
     return {
       submitted: false,
@@ -347,7 +516,9 @@ export async function submitControl(deps, payload) {
         `Styled input line: ${JSON.stringify(String(state.styledInputLine ?? "").slice(0, 160))}`,
     };
   }
-  return pasteAndSubmit(deps, payload, { bracketed: false, verify: true });
+  const below = refusalBeforeKeys(box);
+  if (below) return heldBeforeKeys(screen, target);
+  return pasteAndSubmit(deps, payload, { bracketed: false, verify: true, screen });
 }
 
 // Paste a payload into the target pane and submit it.
@@ -365,10 +536,16 @@ export async function submitControl(deps, payload) {
 // dropped or refused — no retry, no receipt of failure. Control commands
 // already verified; peer traffic gets the same loop now. Pass
 // `verify:false` explicitly to opt out (unknown-TUI / test escape hatch).
-export async function pasteAndSubmit(deps, payload, { bracketed = false, verify } = {}) {
+export async function pasteAndSubmit(deps, payload, { bracketed = false, verify, screen } = {}) {
   const { run, runStdin, target, buffer } = deps;
   const doVerify = verify === undefined ? bracketed : verify;
 
+  // ⟨q-15d763dc⟩ NOTHING IS PASTED until the screen is the ready, empty input box. The paste is held
+  // as firmly as the Enter: a digit pasted into an open dialog selects one of its options.
+  // `screen` is submitControl's own guard read, so a control command costs no second capture.
+  const held = heldBeforeKeys(screen ?? captureStyled(run, target), target);
+  if (held) return held;
+
   await runStdin(["load-buffer", "-b", buffer, "-"], payload);
   const paste = run(["paste-buffer", ...(bracketed ? ["-p"] : []), "-b", buffer, "-t", target, "-d"]);
   if (paste.status !== 0) {
@@ -383,11 +560,24 @@ export async function pasteAndSubmit(deps, payload, { bracketed = false, verify
   //   false — input line readable the whole time and the payload never
   //           appeared; refuse the Enter and say so (honest timeout, not a
   //           blind CR into someone's session).
-  //   null  — no readable input line (unknown TUI / capture failed); fall back
-  //           to the legacy fixed-delay path — unknown never blocks delivery.
+  //   null  — no readable input line (capture failed, or the box went away
+  //           after the paste). ⟨q-15d763dc⟩ This used to fall back to a blind
+  //           Enter ("unknown never blocks delivery"). Unreadable now means HELD:
+  //           an Enter nobody looked before is the Enter that lands in a dialog.
   const floor = sleep(ENTER_DELAY_MS());
   const landed = await pollUntilLanded(deps, payload);
   await floor;
+  if (landed === null) {
+    return {
+      submitted: false,
+      verified: false,
+      pasted: true,
+      attempts: 0,
+      reason:
+        `pasted into pane '${target}', but its input line could not be read afterwards (capture failed, or no line matched AGENT_COORD_PROMPT_PATTERN) — Enter NOT sent ` +
+        `(an unreadable screen is held, never answered with a blind Enter; check the pane for a stranded draft)`,
+    };
+  }
   if (landed === false) {
     return {
       submitted: false,
@@ -399,17 +589,34 @@ export async function pasteAndSubmit(deps, payload, { bracketed = false, verify
         `and check the pane for a stranded draft before resending)`,
     };
   }
+  // ⟨q-15d763dc⟩ ONE Enter, sent right after the landing read saw this payload in the input. The
+  // unconditional second Enter that used to follow it (150 ms later, no screen read) is gone: it
+  // landed in whatever opened after the first (qa's FAIL on #364). A menu that swallows the first
+  // Enter is answered by the retry below, which looks at the screen before every key.
   const e1 = run(["send-keys", "-t", target, "Enter"]);
   if (e1.status !== 0) throw new Error(`tmux send-keys: ${String(e1.stderr ?? "").trim()}`);
-  await sleep(ENTER_GAP_MS());
-  run(["send-keys", "-t", target, "Enter"]);
 
   if (!doVerify) return { submitted: true, verified: false, attempts: 1 };
 
   const retries = ENTER_RETRIES();
   for (let attempt = 1; ; attempt++) {
     const outcome = await pollUntilGone(deps, payload);
-    if (outcome === false) return { submitted: true, verified: true, attempts: attempt };
+    if (outcome === false) {
+      // "The payload left the input" is only a submit if the screen is still the ready box. A
+      // picker's `❯ 2. …` row also matches PROMPT_PATTERN and reads as an emptied input.
+      const after = readReadyBox(captureStyled(run, target));
+      if (!after.ready || (!after.unguarded && after.draft)) {
+        return {
+          submitted: false,
+          verified: false,
+          attempts: attempt,
+          reason:
+            `Enter sent to pane '${target}', but the screen after it is not the ready input box ` +
+            `(${after.ready ? "the box holds other text" : after.reason}) — a dialog may have taken the Enter; not verified`,
+        };
+      }
+      return { submitted: true, verified: true, attempts: attempt };
+    }
     if (outcome === null) {
       return {
         submitted: false,
@@ -440,6 +647,17 @@ export async function pasteAndSubmit(deps, payload, { bracketed = false, verify
     // since. Under the old tail-window check this fired on EVERY successful
     // submit — three Enters into a pane that had already run the command.
     await sleep(ENTER_GAP_MS());
+    // The loop head read the input; the retry Enter also needs the screen to still BE the ready box
+    // holding this payload, or it is the key that lands in a dialog.
+    const box = readReadyBox(captureStyled(run, target));
+    if (!box.unguarded && !boxHoldsPayload(box, payload)) {
+      return {
+        submitted: false,
+        verified: false,
+        attempts: attempt,
+        reason: `retry Enter NOT sent to pane '${target}': the screen is no longer the ready box holding the command (${box.ready ? "the box changed" : box.reason})`,
+      };
+    }
     run(["send-keys", "-t", target, "Enter"]);
   }
 }

package/hooks/tier.mjs

@@ -11,6 +11,7 @@
 
 import { isGateRunner } from "./roles.mjs";
 import { replayMarker } from "./replay.mjs";
+import { neutralizeControls } from "./control-bytes.mjs";
 
 // Typed protocol record → tier (Phase 8). The prefix table below is the same
 // vocabulary parsed out of text; reading the field instead removes the parse
@@ -222,7 +223,12 @@ export function injectLine(m) {
   // is still `[tag HH:MM from] ` and the marker is part of the TEXT, which is
   // correct — it is something the reader must see, not metadata about routing.
   text = `${replayMarker(m.replay)}${text}`;
-  return `  [${tag} ${hhmm} ${m.from}] ${text}`;
+  // ⟨q-e5cb3538⟩ — LAST, over the WHOLE line, so every field that reaches a pane is covered
+  // (tag, from, text, the record type in the handle) on every push path that renders here:
+  // herdr delivery, the tmux pusher and the remote pusher. A control byte in content is a
+  // keystroke in the recipient's session; it becomes a visible escape instead. Content line
+  // feeds are kept — see hooks/control-bytes.mjs for why, and for the byte class.
+  return neutralizeControls(`  [${tag} ${hhmm} ${m.from}] ${text}`);
 }
 
 // Which room is THIS agent's project room, derived from the bus naming

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.26.24",
+  "version": "0.26.26",
   "description": "File-backed MCP server for coordinating multiple AI coding agents (Claude Code, Cursor, Cline, etc.). Local stdio or networked over Streamable HTTP.",
   "type": "module",
   "bin": {
     "agent-coord-mcp": "dist/server.js",
     "coord-chat": "scripts/coord-chat.mjs",
-    "coord-pusher": "scripts/coord-pusher.mjs"
+    "coord-pusher": "scripts/coord-pusher.mjs",
+    "coord-token": "scripts/coord-token.mjs",
+    "coord-seat": "scripts/coord-seat.mjs"
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",

package/scripts/check-global-mcp-fallback.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// ⟨q-8c23e5a3⟩ acceptance (c) — a GLOBAL `agent-coord` MCP entry must never be a working
+// fallback. Claude Code resolves `.mcp.json` at project scope first, but falls back to a
+// user/global scope config when a project has none of its own — so a seat launched from a
+// project that forgot `--emit-mcp-config` does not fail loudly, it comes up healthy,
+// wearing whatever identity the global entry's token resolves to. That is the SAME class as
+// ⟨q-e439e4ad⟩ (an omitted, seat-specific fact silently answered by someone else's context)
+// one layer up, at config-resolution time instead of attach time.
+//
+// This is a DOCTOR, not a gate link: it inspects files outside this repo (the operator's
+// global Claude config), so its population is one machine's state, not this tree's — the
+// same distinction check-doc-links.mjs draws for its external file:// links. Run it by hand
+// after any global MCP config change: `node packages/coord-mcp/scripts/check-global-mcp-fallback.mjs`.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+/** Every location Claude Code can resolve a GLOBAL (non-project) `mcpServers` map from. */
+export function globalMcpConfigPaths(home = homedir()) {
+  return [path.join(home, ".claude", ".mcp.json"), path.join(home, ".claude", ".claude.json")];
+}
+
+/** Read one config file's `mcpServers` map, or `null` if absent/unreadable-as-JSON. */
+function mcpServersOf(file) {
+  if (!existsSync(file)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null; // unreadable is not this check's population — a parse-error gate exists elsewhere if needed
+  }
+  const servers = parsed?.mcpServers;
+  return servers && typeof servers === "object" && !Array.isArray(servers) ? servers : null;
+}
+
+/**
+ * Is a global `agent-coord` entry a WORKING fallback? "Working" means a seat that
+ * inherits it could actually authenticate as someone: an http/https url, plus either a
+ * non-empty bearer header or (advisory mode) no header at all — a url with an EMPTY or
+ * absent Authorization header, or no url, is not something a stray seat could complete a
+ * handshake through.
+ */
+export function isWorkingFallback(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const url = entry.url;
+  if (typeof url !== "string" || !/^https?:\/\//.test(url)) return false;
+  const auth = entry.headers?.Authorization;
+  if (typeof auth === "string" && /^Bearer\s+\S+/.test(auth)) return true;
+  // No header at all is advisory-mode shaped — still a working fallback IF a shared
+  // bearer is expected server-side, which this file cannot see. Treat "has a real url,
+  // no header" as working too: the absence of evidence it's inert is not evidence it is.
+  return auth === undefined;
+}
+
+/** Every global config path carrying a live `agent-coord` entry, with the reason. */
+export function findLiveGlobalFallbacks(home = homedir()) {
+  const hits = [];
+  for (const file of globalMcpConfigPaths(home)) {
+    const servers = mcpServersOf(file);
+    const entry = servers?.["agent-coord"];
+    if (entry && isWorkingFallback(entry)) hits.push({ file, entry });
+  }
+  return hits;
+}
+
+function main() {
+  const hits = findLiveGlobalFallbacks();
+  if (hits.length === 0) {
+    console.log("OK: no global `agent-coord` MCP entry is a working fallback on this machine.");
+    return;
+  }
+  console.error(
+    `⛔ ${hits.length} global MCP config(s) carry a WORKING \`agent-coord\` fallback — a seat ` +
+      `launched from a project with no per-seat .mcp.json (⟨q-8c23e5a3⟩'s --emit-mcp-config) ` +
+      `would inherit this identity silently instead of refusing at start:`,
+  );
+  for (const h of hits) console.error(`  ${h.file} -> mcpServers.agent-coord: ${JSON.stringify(h.entry)}`);
+  console.error(
+    "  Fix: remove the `agent-coord` key from each file above, or point its `url` at nothing " +
+      "reachable and its `headers.Authorization` at an empty/no token.",
+  );
+  process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/scripts/coord-pusher.mjs

@@ -37,7 +37,7 @@
 
 import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
-import { pasteAndSubmit as sharedPasteAndSubmit, submitControl as sharedSubmitControl } from "../hooks/submit.mjs";
+import { pasteAndSubmit as sharedPasteAndSubmit, submitControl as sharedSubmitControl, readyProfileStartupLine } from "../hooks/submit.mjs";
 // The pane's parse-contract line, single-sourced — see the note above formatBatch.
 import { injectLine } from "../hooks/tier.mjs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -58,6 +58,10 @@ const REFRESH_MS = parseInt(argv["refresh-ms"] ?? "30000", 10);
 if (!SERVER) die("--server (or AGENT_COORD_SERVER) is required");
 if (!TOKEN) die("--token (or AGENT_COORD_TOKEN) is required");
 if (!AGENT_ID) die("--agent (or AGENT_COORD_ID) is required");
+{
+  const guardLine = readyProfileStartupLine("coord-pusher");
+  if (guardLine) process.stderr.write(guardLine);
+}
 if (!TMUX_TARGET) die("--tmux (or AGENT_COORD_TMUX_TARGET) is required");
 
 const SAFE_ID = AGENT_ID.replace(/[^a-zA-Z0-9._-]/g, "_");

package/scripts/coord-seat.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// coord-seat — ⟨q-8c23e5a3⟩ acceptance (d): the FIVE manual steps of putting one agent
+// on the HTTP bus, composed into one command. Registering a seat used to mean: (1) mint a
+// token, (2) hand-write a per-project .mcp.json, (3) remember --mcp-config or silently
+// inherit whatever the global entry answers to, (4) find/create a pane and pass it to
+// attach_agent by hand (⟨q-e439e4ad⟩, now refused rather than misattached), (5) know which
+// role-card skill to hand the seat. Two of those five failed SILENTLY into the wrong
+// identity or the wrong terminal. This is the composite default path; the five steps
+// above remain available separately for anyone who wants to do one by hand.
+//
+// Usage:
+//   coord-seat <agent-id> --server <url> --dir <project-dir> --role <roleId> \
+//              [--pane <target>] [--project <name>] [--cmd claude] [--card <skill-name>]
+//
+// --pane is OPTIONAL here only: if omitted, coord-seat tries `herdr pane new` to create one
+// and use its id. If herdr cannot create a pane (binary absent, or no such subcommand on
+// this herdr version), it REFUSES rather than falling back to an omitted target — the one
+// thing this whole queue item exists to stop.
+//
+// ⛔ ALL ARGV PARSING LIVES INSIDE main(), NOT AT MODULE SCOPE: this file is imported
+// directly by its own tests to exercise resolvePane()/main() as functions, and top-level
+// code that reads process.argv would run (and die() on a bare `node --test`'s own argv)
+// the instant the import happened — the same class of defect this queue item is about,
+// just at import time instead of attach time.
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const COORD_TOKEN = path.join(HERE, "coord-token.mjs");
+
+function die(msg) {
+  process.stderr.write(`coord-seat: ${msg}\n`);
+  process.exit(1);
+}
+
+/** Try to mint a fresh pane through herdr. `null` if herdr can't (absent, or refuses). */
+function tryHerdrPaneNew(run = (args) => spawnSync("herdr", args, { encoding: "utf8" })) {
+  const r = run(["pane", "new"]);
+  if (r.error || r.status !== 0) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(r.stdout);
+  } catch {
+    return null;
+  }
+  return parsed?.result?.pane?.pane_id ?? parsed?.pane_id ?? null;
+}
+
+export function resolvePane(explicitPane, run) {
+  if (explicitPane) return explicitPane;
+  const minted = tryHerdrPaneNew(run);
+  if (minted) return minted;
+  die(
+    "no --pane given and `herdr pane new` could not mint one (binary absent, or this herdr " +
+      "version has no such subcommand) — refusing rather than emitting a config with an " +
+      "omitted pane. Create a pane yourself and pass --pane <target>.",
+  );
+}
+
+export function main(run = (args) => spawnSync("herdr", args, { encoding: "utf8" }), argv = process.argv.slice(2)) {
+  function opt(name, fallback) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : fallback;
+  }
+  const agentId = argv[0];
+  if (!agentId || agentId.startsWith("--")) die("usage: coord-seat <agent-id> --server <url> --dir <project-dir> --role <roleId> [--pane <target>]");
+  const server = opt("--server");
+  const dir = opt("--dir");
+  const role = opt("--role", "worker");
+  const project = opt("--project");
+  const cmd = opt("--cmd", "claude");
+  const card = opt("--card", `coord-${role}`);
+  if (!server) die("--server <url> is required");
+  if (!dir) die("--dir <project-dir> is required");
+
+  const pane = resolvePane(opt("--pane"), run);
+
+  const tokenArgs = ["add", agentId, "--emit-mcp-config", dir, "--server", server, "--pane", pane];
+  const minted = spawnSync(process.execPath, [COORD_TOKEN, ...tokenArgs], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  if (minted.status !== 0) die(`coord-token add failed:\n${minted.stderr}`);
+  process.stderr.write(minted.stderr);
+
+  const roleFlags = [`--id=${agentId}`, `--role=${role}`].concat(project ? [`--project=${project}`] : []);
+  console.error(
+    `\ncoord-seat '${agentId}' ready:\n` +
+      `  1. pane:    ${pane}\n` +
+      `  2. config:  ${dir}/.mcp.json (mode 600)\n` +
+      `  3. launch:  cd ${dir} && ${cmd}\n` +
+      `  4. attach:  attach_agent { agentId: "${agentId}", tmuxTarget: "${pane}", includeRoom: false }\n` +
+      `  5. hand off the role card: /${card} ${roleFlags.join(" ")}\n`,
+  );
+  return { pane, dir, agentId };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/scripts/coord-token.mjs

@@ -7,6 +7,13 @@
 //
 // Usage:
 //   scripts/coord-token.mjs add <agent-id>       mint (or rotate) a token, print it
+//     [--emit-mcp-config <dir>]                  ALSO write <dir>/.mcp.json (mode 600)
+//       --server <url>                             required with --emit-mcp-config: the
+//                                                    HTTP bus URL this seat's config points at
+//       --pane <target>                            required with --emit-mcp-config: the
+//                                                    herdr/tmux pane THIS seat will run in —
+//                                                    see ⟨q-8c23e5a3⟩ below for why this can't
+//                                                    be optional
 //   scripts/coord-token.mjs list                 list agent ids (never prints tokens)
 //   scripts/coord-token.mjs revoke <agent-id>    remove a token
 //   [--dir <coord-dir>]                          override AGENT_COORD_DIR
@@ -14,6 +21,15 @@
 // tokens.json is created 0600 (and re-chmod'd on every write) so secrets are
 // never group/other-readable. After add/revoke, SIGHUP the running bus to
 // reload its token map (kill -HUP <bus-pid>).
+//
+// ⟨q-8c23e5a3⟩ --emit-mcp-config REQUIRES --pane, not optionally accepts it: the whole
+// point is that a seat onboarded this way never has an OMITTED target to fall back from —
+// ⟨q-e439e4ad⟩ made the omitted-target case refuse at attach time, and this makes the
+// omission impossible one step earlier, at mint time, for every seat that goes through
+// this path. The printed instructions carry the exact `attach_agent` call with the pane
+// already filled in, because there is no server-side env var that means "this seat's pane"
+// under the shared HTTP daemon — one process, every seat, so a per-seat fact has to travel
+// in what the OPERATOR (or the agent's own first tool call) is handed, not in `process.env`.
 
 import { randomBytes } from "node:crypto";
 import {
@@ -69,6 +85,44 @@ function save(map) {
   chmodSync(TOKENS_FILE, 0o600); // enforce even when the file pre-existed looser
 }
 
+/**
+ * Write a project-local `.mcp.json` (⟨q-8c23e5a3⟩ acceptance (a)) whose `agent-coord`
+ * entry embeds this seat's own token in the `Authorization` header — never a shared
+ * default, so a project that gets its OWN config never depends on (or silently becomes)
+ * a global fallback. mode 600, same as tokens.json: a bearer token is a secret regardless
+ * of which file holds it. `pane` is recorded under `_agentCoordPane`, a key no MCP client
+ * reads or writes — it exists so a re-run of this script, or `coord-seat`, can recover the
+ * pane a config was minted for without re-asking the operator, and so a human reading the
+ * file sees the fact `attach_agent` will need, instead of it living only in scrollback.
+ */
+export function writeMcpConfig({ dir, agentId, server, token, pane }) {
+  mkdirSync(dir, { recursive: true });
+  const configPath = path.join(dir, ".mcp.json");
+  let existing = {};
+  if (existsSync(configPath)) {
+    try {
+      existing = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch (e) {
+      die(`${configPath} exists and is not valid JSON (${e.message}) — refusing to overwrite blindly`);
+    }
+  }
+  const config = {
+    ...existing,
+    mcpServers: {
+      ...(existing.mcpServers ?? {}),
+      "agent-coord": {
+        type: "http",
+        url: server,
+        headers: { Authorization: `Bearer ${token}` },
+        ...(pane ? { _agentCoordPane: pane } : {}),
+      },
+    },
+  };
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(configPath, 0o600);
+  return configPath;
+}
+
 const positional = argv.filter((a) => !a.startsWith("--"));
 const cmd = positional[0];
 const id = positional[1];
@@ -78,6 +132,17 @@ switch (cmd) {
     if (!id || !AGENT_ID_RE.test(id)) {
       die("usage: coord-token add <agent-id>  (id: [a-zA-Z0-9._-], <=64 chars)");
     }
+    const emitDir = opt("--emit-mcp-config");
+    const server = opt("--server");
+    const pane = opt("--pane");
+    if (emitDir && !server) die("--emit-mcp-config requires --server <url>");
+    if (emitDir && !pane) {
+      die(
+        "--emit-mcp-config requires --pane <target> — a config with no pane recorded is exactly " +
+          "the omitted-target case ⟨q-e439e4ad⟩ made attach_agent refuse; this refuses one step " +
+          "earlier instead of emitting a config that would hit that refusal on first use.",
+      );
+    }
     const map = load();
     const rotating = id in map;
     const token = "tk_" + randomBytes(24).toString("base64url");
@@ -89,10 +154,20 @@ switch (cmd) {
     process.stderr.write(
       `${rotating ? "rotated" : "minted"} token for '${id}' in ${TOKENS_FILE}\n`,
     );
-    process.stderr.write(
-      `SIGHUP the running bus to load it (kill -HUP <bus-pid>), then on the node:\n` +
-        `  AGENT_COORD_TOKEN=${token} scripts/coord-node.sh --server <url> --id ${id} --cmd claude\n`,
-    );
+    if (emitDir) {
+      const configPath = writeMcpConfig({ dir: emitDir, agentId: id, server, token, pane });
+      process.stderr.write(
+        `mcp config written: ${configPath} (mode 600)\n` +
+          `launch: cd ${emitDir} && claude\n` +
+          `first tool call — the pane is not optional, name it every time:\n` +
+          `  attach_agent { agentId: "${id}", tmuxTarget: "${pane}", includeRoom: false }\n`,
+      );
+    } else {
+      process.stderr.write(
+        `SIGHUP the running bus to load it (kill -HUP <bus-pid>), then on the node:\n` +
+          `  AGENT_COORD_TOKEN=${token} scripts/coord-node.sh --server <url> --id ${id} --cmd claude\n`,
+      );
+    }
     process.stdout.write(token + "\n"); // token alone on stdout, pipe/capture-friendly
     break;
   }