agent-coord-mcp 0.26.25 → 0.26.27

package/dist/transports/types.js

@@ -26,13 +26,28 @@
  * instead of reading the field, and a `string` discriminant cannot tell the
  * compiler that a branch was missed. Not a two-member union either — see (1).
  */
+/**
+ * ⟨q-ec020f6a⟩ LOCAL tmux-push was DELETED outright (0 of 13 live seats used it; keeping
+ * it meant a second delivery mechanism — hooks/tmux-pusher.mjs, now removed — plus a
+ * role-card precondition that halted every live herdr seat on a false requirement).
+ *
+ * `TMUX_PUSH` stays DEFINED AND EXPORTED, but OUT of `TransportKind`/`TRANSPORT_KINDS`, for
+ * exactly one reason: a marker written to disk before this change can still literally read
+ * `"tmux-push"`, and `isLocallyProbeable`/`isTmuxKind` below must keep classifying that
+ * HISTORICAL value correctly (never `"dead"` where it used to read `"unknown"`) even
+ * though nothing can construct a NEW one — `resolveTransport` has no case for it and
+ * `config.ts` refuses it. Classifying old data and constructing new data are different
+ * questions; removing it from the union answers only the second.
+ */
 export const TMUX_PUSH = "tmux-push";
 export const TMUX_PUSH_REMOTE = "tmux-push-remote";
 export const HERDR = "herdr";
-export const TRANSPORT_KINDS = [TMUX_PUSH, TMUX_PUSH_REMOTE, HERDR];
+export const TRANSPORT_KINDS = [TMUX_PUSH_REMOTE, HERDR];
 /**
- * The tmux family. Both members are delivered by a pusher process typing into a
- * pane; they differ in WHERE that pane is, which is why liveness splits below.
+ * The tmux family, for LIVENESS CLASSIFICATION of whatever a marker on disk says —
+ * including the historical, no-longer-constructible local kind (`TMUX_PUSH`, above).
+ * Both members are delivered by a pusher process typing into a pane; they differed in
+ * WHERE that pane was, which is why liveness splits below.
  *
  * THIS IS THE ONE PLACE THE TMUX LITERALS LIVE. Twelve call sites used to spell
  * them; they now ask.

package/dist/transports/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transports/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAoB,CAAC;AAC9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAA2B,CAAC;AAC5D,MAAM,CAAC,MAAM,KAAK,GAAG,OAAgB,CAAC;AAItC,MAAM,CAAC,MAAM,eAAe,GAA6B,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,CAAU,CAAC;AAEvG;;;;;;GAMG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAElE,mEAAmE;AACnE,MAAM,UAAU,UAAU,CAAC,SAA6B;IACtD,OAAO,SAAS,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAA6B;IAC9D,OAAO,SAAS,KAAK,SAAS,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAA6B;IAC5D,OAAO,SAAS,KAAK,gBAAgB,CAAC;AACxC,CAAC;AAyDD;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAsD;IAC7E,OAAO,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,UAAU,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAmB,MAAS,EAAE,MAA0B;IAChF,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACnD,CAAC;AAeD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAU,CAAC;AAGnE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;AAC3I,MAAM,CAAC,MAAM,aAAa,GAAwC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;AAKxJ,iFAAiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,eAAe,CAAU,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transports/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AACH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAoB,CAAC;AAC9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAA2B,CAAC;AAC5D,MAAM,CAAC,MAAM,KAAK,GAAG,OAAgB,CAAC;AAItC,MAAM,CAAC,MAAM,eAAe,GAA6B,CAAC,gBAAgB,EAAE,KAAK,CAAU,CAAC;AAE5F;;;;;;;;GAQG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAElE,mEAAmE;AACnE,MAAM,UAAU,UAAU,CAAC,SAA6B;IACtD,OAAO,SAAS,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAA6B;IAC9D,OAAO,SAAS,KAAK,SAAS,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAA6B;IAC5D,OAAO,SAAS,KAAK,gBAAgB,CAAC;AACxC,CAAC;AAyDD;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAsD;IAC7E,OAAO,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,UAAU,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAmB,MAAS,EAAE,MAA0B;IAChF,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACnD,CAAC;AAeD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAU,CAAC;AAGnE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;AAC3I,MAAM,CAAC,MAAM,aAAa,GAAwC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;AAKxJ,iFAAiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,eAAe,CAAU,CAAC"}

package/hooks/submit.mjs

@@ -323,7 +323,18 @@ export function readyProfileStartupLine(who) {
 // 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,}$/;
+// ⟨q-c8032c5f⟩ herdr's `pane read --source visible` can draw a SHORT SINGLE-TOKEN pane label
+// into the middle of an otherwise-unbroken rule (measured on a live seat: 201 U+2500 dashes
+// with " qa2 " spliced in near the end) — herdr's own frame chrome overlaid onto the exact
+// row Claude Code drew as a plain rule, not something Claude Code's own render ever does.
+// A pure exact-match (`/^─{8,}$/`) read that as "not a rule at all" and held every push to
+// that seat: the line WAS the rule, annotated, and the annotation is what broke the match —
+// not the pane, not the transport, not the seat. Tolerate exactly one such label (a single
+// run of non-space, non-dash characters, flanked by spaces, flanked by dashes on both sides)
+// and nothing looser: multi-word content, a label with no dashes on one side, or two labels
+// still fail — those are genuinely not a rule, and loosening further would just move the
+// false-refusal into a false-accept instead of fixing it.
+const RULE_RE = /^─{8,}(?: [^\s─]+ )?─*$/;
 const BOX_LINE_RE = /^❯(?:\s|$)/;
 const MAX_DRAFT_LINES = 20;
 

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.26.25",
+  "version": "0.26.27",
   "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-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;
   }

package/scripts/stop-agent.sh

@@ -1,10 +1,14 @@
 #!/usr/bin/env bash
-# stop-agent.sh — tear down an agent spawned by spawn-agent.sh.
-# Kills the tmux session and the tmux-pusher daemon.
+# stop-agent.sh — tear down a `coord-<id>` tmux session and its `pusher-<id>.pid`.
+#
+# ⟨q-ec020f6a⟩: spawn-agent.sh (the LOCAL tmux-push spawner) is gone, but this script is
+# generic over the pid-file/session-name convention, not over which pusher wrote it — and
+# coord-node.sh (the REMOTE onboarding path, still fully supported) uses the same
+# convention and documents this script as its own teardown. Kept for that reason.
 #
 # Usage:
-#   scripts/stop-agent.sh --id frontend
-#   scripts/stop-agent.sh --id frontend --dir /custom/coord/dir
+#   scripts/stop-agent.sh --id worker-2
+#   scripts/stop-agent.sh --id worker-2 --dir /custom/coord/dir
 
 set -euo pipefail
 

package/src/capabilities.ts

@@ -48,7 +48,7 @@ import { injectLine } from "../hooks/tier.mjs";
 import { findControlByte } from "../hooks/control-bytes.mjs";
 // ⟨q-15d763dc⟩ The ready-box guard's profile, as this process read it from its own env at start.
 // @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
-import { readyProfile } from "../hooks/submit.mjs";
+import { readyProfile, readReadyBox } from "../hooks/submit.mjs";
 import { subscriptionHealth } from "./tools/events.js";
 import {
   configuredTransport,
@@ -65,7 +65,7 @@ import { detectSpread } from "./server-spread.js";
 import { answeringServerIdentity } from "./tools/registry.js";
 import { HerdrTransport, herdrKeyName } from "./transports/herdr.js";
 import { tickVerdict } from "./tools/tick.js";
-import { ensureHerdrTail, herdrTailState, newMessagesIn, stopHerdrTail } from "./tools/herdr-tail.js";
+import { ensureHerdrTail, herdrTailState, newContext, newMessagesIn, stopHerdrTail } from "./tools/herdr-tail.js";
 import { HERDR, TICK_READS_AS, TICK_STORED_AS, type TickState } from "./transports/types.js";
 
 export type ProbeResult = {
@@ -349,6 +349,77 @@ const PROBES: Probe[] = [
       }
     },
   },
+  {
+    // ⛔⛔ ⟨q-cdb5b007⟩ — the HTTP daemon started NO tails at all, so any seat one message behind
+    // was permanently and silently deaf. This probe exists because the PREVIOUS probe could not
+    // see that: it starts a tail by calling `ensureHerdrTail` directly, which is exactly what
+    // production never did under token auth. A capability that only the test calls is not present.
+    //
+    // Probed here: a tail started the way `startTailOnBind` now starts it types NOTHING that
+    // predates it. That is the half a seat can check about ITSELF; whether this build's auth path
+    // reaches it is reported at runtime under `herdrTail`, which must be non-empty on a live
+    // daemon. Label and code disagree by design — `versionLabel` reads package.json on disk.
+    id: "http-prebound-starts-tail-at-eof",
+    since: "0.26.26",
+    run: () => {
+      const probeId = `__probe-tail-eof-${process.pid}`;
+      const dir = mkdtempSync(path.join(tmpdir(), "probe-tail-eof-"));
+      try {
+        const seeded = newContext(true);
+        const inherited = newContext(false);
+        const hasSeedFields = typeof seeded.seedEof === "boolean" && seeded.seeded instanceof Set;
+        // A seeded context adopts EOF on first sight of a source; an inherited one does not.
+        const scripted = { kind: HERDR } as unknown as NonNullable<Parameters<typeof ensureHerdrTail>[1]>["transport"];
+        const seededStart = ensureHerdrTail(probeId, {
+          transport: scripted,
+          pollMs: 3_600_000,
+          seedEof: true,
+          tail: async () => ({ delivered: [], held: [] }),
+        });
+        const running = herdrTailState().some((s) => s.agentId === probeId && s.running);
+        const present = hasSeedFields && seeded.seedEof === true && inherited.seedEof === false && seededStart.started && running;
+        return {
+          present,
+          evidence: `newContext(true).seedEof=${seeded.seedEof} · newContext(false).seedEof=${inherited.seedEof} · per-source seeded set=${seeded.seeded instanceof Set} · ensureHerdrTail({seedEof}) started=${seededStart.started} running=${running} -> present=${present}`,
+        };
+      } finally {
+        stopHerdrTail(probeId);
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  },
+  {
+    // ⛔⛔ ⟨q-c8032c5f⟩ — the ready-box guard HELD EVERY PUSH to a live seat (ticks 191,
+    // delivered 0, held 98) reporting "the ❯ line has no ─ rule directly above it" against a pane
+    // that WAS ready. herdr splices the pane's own label into the frame, so the rule Claude Code
+    // drew as plain dashes arrives as `──… qa2 ─`. `RULE_RE` demanded an unbroken dash line and
+    // read the annotated one as not-a-rule: a false negative in the matcher, reported as a fact
+    // about the pane. The seat stayed queued and functional for PULL and simply never WOKE.
+    //
+    // ⚠ THE NEGATIVES ARE THE PROBE. Accepting the label is one line; accepting it WITHOUT opening
+    // a false-accept is the property. A matcher that took any annotated rule would pass a
+    // positive-only probe while typing into dialogs and menus — so a multi-word label, a label
+    // with no dash after it, and two labels are each asserted REFUSED alongside the accept.
+    id: "ready-box-tolerates-pane-label",
+    since: "0.26.27",
+    run: () => {
+      const D = "─".repeat(60);
+      const screen = (rule: string) => [`${D} above ${D}`, rule, "❯", D, "  ⏵⏵ bypass permissions on"].join("\n");
+      const readyOf = (rule: string) => readReadyBox(screen(rule), "claude-code") as { ready: boolean; reason?: string };
+
+      const labelled = readyOf(`${D} qa2 ${D}`).ready === true; // the live failure, now accepted
+      const plain = readyOf(D).ready === true; // control: the un-annotated rule must still work
+      const multiWord = readyOf(`${D} two words ${D}`).ready === false;
+      const noTrailingDash = readyOf(`${D} qa2 `).ready === false;
+      const twoLabels = readyOf(`${D} a ${D} b ${D}`).ready === false;
+
+      const present = labelled && plain && multiWord && noTrailingDash && twoLabels;
+      return {
+        present,
+        evidence: `herdr-labelled rule accepted=${labelled} · plain rule still accepted=${plain} · REFUSED: multi-word=${multiWord}, no-trailing-dash=${noTrailingDash}, two-labels=${twoLabels} -> present=${present}`,
+      };
+    },
+  },
   {
     // ⟨q-1c95f7d4⟩ Phase 5.4 Task 5 — the external tick, probed by CALLING the code that
     // decides what a reading MEANS (every probe here is synchronous, so the async read is
@@ -495,8 +566,8 @@ export type TransportCapability = {
   agrees: boolean;
   /** What was called and what came back. */
   evidence: string;
-  /** Where `configured` came from — config file, env, or the built-in default. */
-  configuredSource: "config" | "env" | "default";
+  /** Where `configured` came from — config file or env. ⟨q-ec020f6a⟩: no built-in default. */
+  configuredSource: "config" | "env";
   /**
    * MIXED FLEET, MADE LOUD (3.4). Agents whose marker names a transport other
    * than the running one. Whole-fleet is the rule; this is the code noticing

package/src/server.ts

@@ -845,9 +845,8 @@ async function main() {
   // branching in send_command or attach.
   try {
     const t = initTransportFromConfig();
-    if (t.source !== "default") {
-      console.error(`[agent-coord-mcp] transport: ${t.kind} (from ${t.source})`);
-    }
+    // ⟨q-ec020f6a⟩: no built-in default any more — every resolution has a real source, always logged.
+    console.error(`[agent-coord-mcp] transport: ${t.kind} (from ${t.source})`);
     // ⛔ A HERDR SEAT MUST TAIL ITS OWN INBOX, OR IT IS DEAF TO EVERY TMUX SENDER.
     // The send-time path can only see the SENDER's transport (a module-level singleton), so a
     // tmux seat's server can never type into a herdr pane. The duty belongs to the seat that
@@ -1077,6 +1076,16 @@ async function startHttp(port: number): Promise<void> {
     const tokenMap = getTokenMap();
     if (tokenMap) {
       const agent = tokenMap.get(bearer);
+      // ⛔ THE ONLY PLACE A PRE-BOUND SEAT CAN GET A TAIL. The `startTailOnBind` sites in the tool
+      // path all sit behind `bound === undefined` — the TOFU claim. Here identity arrives already
+      // decided by the bearer, that branch is unreachable, and before this line NO tail ever
+      // started under HTTP (⟨q-cdb5b007⟩: `herdrTail: []`, and send-time delivery deferring to a
+      // tail that does not exist drops the message permanently and silently).
+      //
+      // Deliberately lazy rather than a loop over the whole token map at boot: only a seat that
+      // actually connects gets a tail, so a 20-agent map does not spawn 20 timers for seats that
+      // may not exist. Idempotent — steady state is one Map lookup per request.
+      if (agent) startTailOnBind(agent);
       return agent ? { ok: true, agent } : { ok: false };
     }
     // Advisory mode: only check the shared bearer matches.

package/src/tools/herdr-tail.ts

@@ -63,8 +63,18 @@ export type TailContext = {
   hw: Map<string, number>;
   /** Last seen size per source: a source that has not grown costs one stat. */
   sizes: Map<string, number>;
+  /**
+   * ⛔ START AT EOF, NEVER AT WHATEVER THE CURSOR FILE HAPPENS TO SAY. A tail is a LIVE push
+   * mechanism, not a mail reader: nothing that predates its start belongs on the pane. Measured
+   * 2026-09-17 — a daemon restart reset every push cursor to ~0, so a tail starting from disk
+   * state would have typed a 3.4MB inbox into one seat's pane. `read_messages` still serves that
+   * history on demand; that is the verb for it.
+   */
+  seedEof: boolean;
+  /** Sources already seeded — a room discovered on a later refresh is seeded on ITS first sight, not skipped. */
+  seeded: Set<string>;
 };
-export const newContext = (): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), sizes: new Map() });
+export const newContext = (seedEof = false): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), sizes: new Map(), seedEof, seeded: new Set() });
 
 const keyOf = (s: { kind: string; chan?: string }) => (s.kind === "dm" ? "dm" : `room:${s.chan}`);
 const sizeOf = (file: string): number => {
@@ -127,6 +137,15 @@ export async function tailOnce(
     // ⭐ THE IDLE PATH: a source that has not grown since the last tick costs this one stat.
     if (ctx.sizes.get(key) === size) continue;
     ctx.sizes.set(key, size);
+    // ⛔ FIRST SIGHT OF A SOURCE UNDER seedEof: adopt EOF and type NOTHING. This is the only place
+    // the starting offset is decided, and it is decided EXPLICITLY rather than inherited from a
+    // cursor file that a restart may have reset. Per source, so a room joined later seeds on its
+    // own first sight instead of replaying its history.
+    if (ctx.seedEof && !ctx.seeded.has(key)) {
+      ctx.seeded.add(key);
+      ctx.hw.set(key, size);
+      continue;
+    }
     const from = await offsetOf(agentId, src, ctx);
     if (size <= from) continue;
 
@@ -208,12 +227,12 @@ export function stopAllHerdrTails(): void {
  */
 export function ensureHerdrTail(
   agentId: string,
-  opts: { transport?: Transport; pollMs?: number; tail?: (id: string, ctx: TailContext) => Promise<TailOutcome> } = {},
+  opts: { transport?: Transport; pollMs?: number; seedEof?: boolean; tail?: (id: string, ctx: TailContext) => Promise<TailOutcome> } = {},
 ): { started: boolean; running: boolean; why: string } {
   const t = opts.transport ?? activeTransport();
   if (!t || t.kind !== HERDR) return { started: false, running: false, why: `transport is ${t?.kind ?? "unwired"}, not herdr — a tmux seat is woken by its pusher` };
   if (running.has(agentId)) return { started: false, running: true, why: "already tailing this agent in this process" };
-  const ctx = newContext();
+  const ctx = newContext(opts.seedEof === true);
   const run = opts.tail ?? ((id: string, c: TailContext) => tailOnce(id, { transport: t, ctx: c }));
   const rec: TailRecord = { agentId, startedAt: new Date().toISOString(), ticks: 0, delivered: 0, held: 0, lastTickAt: null, lastWhy: null, stop: () => {} };
   let inFlight = false;
@@ -237,8 +256,21 @@ export function ensureHerdrTail(
   return { started: true, running: true, why: `tailing ${agentId}'s inbox and rooms every ${opts.pollMs ?? DEFAULT_POLL_MS}ms` };
 }
 
-/** The hook the server calls at EVERY identity binding — `join`, a gated first claim, or the env var. */
+/**
+ * The hook the server calls at EVERY identity binding — `join`, a gated first claim, the env var,
+ * or (HTTP) an authenticated request from a PRE-BOUND identity.
+ *
+ * ⛔ THE BINDING TRANSITION IS NOT REACHABLE UNDER HTTP, WHICH IS WHY THIS ALSO HANGS OFF AUTH.
+ * The `bound === undefined` sites below only fire when a session CLAIMS an id. A token-authenticated
+ * daemon resolves identity per request and reports `pre-bound (N agents)`, so `bound` is never
+ * undefined and NO tail ever started — measured 2026-09-17 as `herdrTail: []` on a freshly
+ * restarted daemon whose seats had re-joined after it. With the send-time path deferring owed
+ * messages to "the recipient's own tail", a tail that never exists makes that deferral a permanent
+ * silent drop: one message behind and the seat is deaf for good (⟨q-cdb5b007⟩).
+ *
+ * Idempotent, so the per-request call costs one Map lookup once the tail is up.
+ */
 export function startTailOnBind(agentId: string, log: (line: string) => void = (l) => console.error(l)): void {
-  const r = ensureHerdrTail(agentId);
+  const r = ensureHerdrTail(agentId, { seedEof: true });
   if (r.started) log(`[agent-coord-mcp] herdr tail: ${r.why}`);
 }