@thehammer/danx-dashboard-mcp 0.1.64 → 0.1.66

package/README.md

@@ -38,19 +38,19 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 
 A bare `plan_get` (no `fields`) returns only the plan's cheap scalars — `plan`, `boards`, `cardCount`, `bucketCounts`, `session`, `sessionListenerAttached` — plus `available_field_groups` naming what else exists. Pass `fields` to opt into `cards` (paged: `cards_offset`, default 0, and `cards_limit`, 1..1000, default 200, pick the page; the response carries `cards_total` and `cards_offset`, so page with `cards_offset` while `cards_offset + cards.length < cards_total` — either paging arg without `cards` in `fields` is a 400), `records` (every goal/rule/caveat) or `records:goal` / `records:rule` / `records:caveat` (just one kind), `architecture`, and `sessions`. A `plan_get` made only to grab a hash before a one-line edit no longer pays for the architecture document or every member card.
 
-## `listen` — a working session's event listener
+## `bridge` — a working session's event stream client
 
-`plan_connect` connects the session to a plan AND returns `listener: {command, persistent: true, instruction}`. The agent arms `command` with Claude Code's Monitor tool (`persistent: true`); every line the command prints becomes a notification that wakes the session.
+A program runs this, not an agent: the danxbot Claude Code plugin's plan event bridge spawns `bridge` for a session, relays each event's `text` into the session, and stores the delivered ids. `plan_connect` only connects the session; it mints no ticket.
 
 ```bash
-npx -y @thehammer/danx-dashboard-mcp@<version> listen --stream <dashboard>/api/plan-sessions/stream --ticket <ticket> --lease-ms <ms>
+DANXBOT_DASHBOARD_URL=<dashboard> DANXBOT_DISPATCH_TOKEN=<token> CLAUDE_CODE_SESSION_ID=<session> \
+  npx -y @thehammer/danx-dashboard-mcp@<version> bridge [--resume-ids <id>,<id>,...]
 ```
 
-All three flags come from the dashboard's own ticket response; `plan_connect` assembles the command, so never build it by hand.
-
-- **Credential.** `--ticket` is a listener ticket minted by `POST /api/plan-sessions/me/stream-ticket` for THIS session only. It authorizes reading that one session's event stream and nothing else, and stops the moment the credential that minted it is revoked — the MCP server's own token never appears in the command. Minting a new one (calling `plan_connect` again) ends the previous listener; a second connection with the same ticket replaces the first.
-- **Output.** Exactly one line per event on the connected plan's cards — `[DX-8 "Title" repo:board] newms87 answered "Which rollout order?": chose "Pause E2E" — note: "only this week"`, `… answered "…": "<free-form answer>"`, `… commented: "…"`, `… set requires_human: "…"`, `… cleared requires_human`, `… blocked the card: "…"`, `… unblocked the card`. Nothing for keep-alives or reconnects. The session's own writes are never echoed back to it. An event it cannot read still produces one `could not read event` line.
-- **Reconnect.** A read-idle timeout (three missed keep-alives) turns a silently dead connection into a drop. Capped exponential backoff (1s → 30s) that resets only after a healthy connection, with `Last-Event-ID`, so a dashboard restart replays what was missed and nothing is printed twice. One final `[danx-dashboard listen] …` line and exit when the ticket is refused or revoked (exit 1), when a newer listener takes over (exit 0), or after `--lease-ms` without a healthy connection (exit 1) — the remedy is always `plan_connect` again.
+- **Credential.** The credential and session come from the environment; `--resume-ids` is the only argument and holds no secret. `bridge` mints the session's listener ticket (`POST /api/plan-sessions/me/stream-ticket`, 10 s timeout) and keeps it in the process. A ticket authorizes reading that one session's event stream and nothing else, and is only issued while the session is connected to a plan. Minting a new one ends the previous listener.
+- **Output — JSON Lines.** One `{"type":"event","id":<id|null>,"text":"…"}` per event on the connected plan's cards, where `text` is `[DX-8 "Title" repo:board] newms87 answered "Which rollout order?": chose "Pause E2E" — note: "only this week"`, `… answered "…": "<free-form answer>"`, `… commented: "…"`, `… set requires_human: "…"`, `… cleared requires_human`, `… blocked the card: "…"`, or `… unblocked the card`. An event it cannot read still produces one, with a `could not read event` text. Nothing for keep-alives, reconnects or re-mints. The session's own writes are never echoed back to it.
+- **Stopping.** Last, one `{"type":"stopped","reason":"…","detail":"…"}` and exit, only on a terminal outcome: `not_connected`, `unauthorized` (401/403), `mint_refused` (any other non-transient refusal), `mint_bad_response`, `superseded` / `replaced` (exit 0), `revoked`, or `refused` (two freshly minted tickets refused in a row). A transient mint failure (network, timeout, 408, 429, 5xx) backs off and retries; a lapsed ticket lease re-mints.
+- **Reconnect and resume.** A read-idle timeout (three missed keep-alives) turns a silently dead connection into a drop. Capped exponential backoff (1s → 30s) that resets only after a healthy connection, with `Last-Event-ID`, so a dashboard restart replays what was missed and nothing is emitted twice. `--resume-ids` carries the same guarantee across a process restart: the ids already delivered seed the duplicate guard, and the highest is the first `Last-Event-ID`. The dashboard floors that replay at the later of the session's first ticket and when it joined its current plan, so a restart loses nothing and a plan move replays nothing from before the move.
 
 ## Build + test
 

package/dist/bridge.js

@@ -0,0 +1,236 @@
+/**
+ * `danx-dashboard-mcp bridge [--resume-ids <event-id>[,<event-id>...]]` — the ONE
+ * client of a working session's dashboard event stream.
+ *
+ * WHO RUNS IT. The danxbot Claude Code plugin's plan event bridge
+ * (`danxbot/scripts/plan-event-bridge.mjs` in claude-plugins) spawns it once per
+ * session and owns only process lifecycle, the delivered-id cursor, and posting
+ * each event into the session's inbox. Everything about the dashboard's HTTP
+ * contract lives HERE, next to the MCP server that already speaks it, and is
+ * tested here.
+ *
+ * WHAT IT DOES.
+ *   1. Reads `DANXBOT_DASHBOARD_URL`, `DANXBOT_DISPATCH_TOKEN` and
+ *      `CLAUDE_CODE_SESSION_ID` from its environment.
+ *   2. Mints the session's listener ticket (`POST /api/plan-sessions/me/stream-ticket`)
+ *      with a timeout. The ticket stays in this process.
+ *   3. Streams through `runListener` (`listen.ts`), which reconnects within the
+ *      ticket, and re-mints when that ticket's lease runs out or a fresh ticket is
+ *      refused once.
+ *   4. Writes JSON Lines to stdout: `{type:"event", id, text}` per event, and ONE
+ *      final `{type:"stopped", reason, detail}` before exiting.
+ *
+ * TERMINAL OUTCOMES — each ends the process with its stop record, never a retry:
+ *   - `not_connected`     the mint answered 409 `session_not_connected`;
+ *   - `unauthorized`      the mint answered 401 / 403;
+ *   - `mint_refused`      any other non-transient mint refusal (400, 404, …);
+ *   - `mint_bad_response` a 2xx mint whose body is not a ticket;
+ *   - `superseded` / `replaced` (exit 0) — another listener now holds the session;
+ *   - `revoked`           the dashboard revoked the ticket or its issuer;
+ *   - `refused`           freshly minted tickets were refused twice in a row.
+ * Transient mint failures (network, timeout, 408, 429, 5xx) back off and retry: the
+ * process lives exactly as long as its session, and the plugin ends it.
+ *
+ * THE ENVIRONMENT, NOT ARGV, CARRIES THE CREDENTIAL. A command line is readable by
+ * every process on the machine; `--resume-ids` is the only argument and holds no
+ * secret.
+ */
+import { oneLine } from "./one-line.js";
+import { DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, READ_IDLE_TIMEOUT_MS, runListener, } from "./listen.js";
+export const BRIDGE_SUBCOMMAND = "bridge";
+export const STREAM_TICKET_PATH = "/api/plan-sessions/me/stream-ticket";
+export const SESSION_ID_HEADER = "x-danx-session-id";
+/** How long one ticket mint may take before it counts as a transient failure. */
+export const MINT_TIMEOUT_MS = 10_000;
+export const MINT_INITIAL_BACKOFF_MS = 1_000;
+export const MINT_MAX_BACKOFF_MS = 60_000;
+/** A freshly minted ticket refused this many times in a row is a terminal outcome, not a loop. */
+export const MAX_REFUSED_TICKETS_IN_A_ROW = 2;
+const TRANSIENT_CLIENT_STATUSES = new Set([408, 429]);
+const TAKEOVER_REASONS = new Set(["superseded", "replaced"]);
+const USAGE = `usage: DANXBOT_DASHBOARD_URL=<url> DANXBOT_DISPATCH_TOKEN=<token> CLAUDE_CODE_SESSION_ID=<session-id> ` +
+    `danx-dashboard-mcp ${BRIDGE_SUBCOMMAND} [--resume-ids <event-id>[,<event-id>...]]`;
+function positiveInteger(raw) {
+    const n = Number(raw);
+    return Number.isSafeInteger(n) && n > 0 && String(n) === raw ? n : null;
+}
+/** Parse the one optional flag and the three required environment values; anything else is refused. */
+export function parseBridgeArgs(argv, env) {
+    const withResume = argv.length === 2 && argv[0] === "--resume-ids" && argv[1] !== "";
+    if (argv.length !== 0 && !withResume)
+        throw new Error(USAGE);
+    const dashboardUrl = env.DANXBOT_DASHBOARD_URL;
+    const token = env.DANXBOT_DISPATCH_TOKEN;
+    const sessionId = env.CLAUDE_CODE_SESSION_ID;
+    if (!dashboardUrl || !token || !sessionId)
+        throw new Error(USAGE);
+    const resumeIds = withResume ? argv[1].split(",").map(positiveInteger) : [];
+    if (resumeIds.some((id) => id === null))
+        throw new Error(USAGE);
+    return { dashboardUrl: dashboardUrl.replace(/\/+$/, ""), token, sessionId, resumeIds: resumeIds };
+}
+function errorCodeOf(body) {
+    return typeof body === "object" && body !== null && typeof body.error === "string"
+        ? body.error
+        : null;
+}
+/** What is wrong with a 2xx mint body, or `null` when it is a ticket. Never echoes the body. */
+function badTicketReason(body) {
+    if (typeof body !== "object" || body === null)
+        return "the body is not a JSON object";
+    const b = body;
+    if (typeof b.ticket !== "string" || b.ticket === "")
+        return "ticket is not a non-empty string";
+    if (typeof b.streamPath !== "string" || !b.streamPath.startsWith("/"))
+        return "streamPath is not a path";
+    if (typeof b.leaseMs !== "number" || !Number.isSafeInteger(b.leaseMs) || b.leaseMs <= 0) {
+        return "leaseMs is not a positive integer";
+    }
+    return null;
+}
+/** Mint this session's listener ticket, classifying every way that can end. */
+export async function mintTicket(options, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.mintTimeoutMs);
+    try {
+        let status;
+        let text;
+        try {
+            const response = await deps.fetch(`${options.dashboardUrl}${STREAM_TICKET_PATH}`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    [SESSION_ID_HEADER]: options.sessionId,
+                },
+                body: "{}",
+                signal: controller.signal,
+            });
+            status = response.status;
+            text = await response.text();
+        }
+        catch (err) {
+            return {
+                kind: "transient",
+                detail: controller.signal.aborted
+                    ? `ticket mint timed out after ${deps.mintTimeoutMs} ms`
+                    : `ticket mint failed: ${err.message}`,
+            };
+        }
+        if (status >= 500 || TRANSIENT_CLIENT_STATUSES.has(status)) {
+            return { kind: "transient", detail: `ticket mint HTTP ${status}` };
+        }
+        let body = null;
+        try {
+            body = text === "" ? null : JSON.parse(text);
+        }
+        catch {
+            body = null;
+        }
+        if (status === 409 && errorCodeOf(body) === "session_not_connected") {
+            return { kind: "terminal", reason: "not_connected", detail: "the session is not connected to a plan" };
+        }
+        if (status === 401 || status === 403) {
+            return { kind: "terminal", reason: "unauthorized", detail: `ticket mint HTTP ${status} ${oneLine(text, 300)}` };
+        }
+        if (status < 200 || status >= 300) {
+            return { kind: "terminal", reason: "mint_refused", detail: `ticket mint HTTP ${status} ${oneLine(text, 300)}` };
+        }
+        const bad = badTicketReason(body);
+        if (bad !== null) {
+            return { kind: "terminal", reason: "mint_bad_response", detail: `ticket mint HTTP ${status}: ${bad}` };
+        }
+        const ticket = body;
+        return {
+            kind: "ticket",
+            ticket: ticket.ticket,
+            streamUrl: `${options.dashboardUrl}${ticket.streamPath}`,
+            leaseMs: ticket.leaseMs,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Mint, stream, re-mint — until a terminal outcome, which it writes as the one
+ * `stopped` record. Returns 0 when another listener took over, 1 otherwise.
+ */
+export async function runBridge(options, deps) {
+    const delivered = options.resumeIds.slice(-DELIVERED_ID_MEMORY);
+    const stop = (reason, detail, code) => {
+        deps.write({ type: "stopped", reason, detail });
+        return code;
+    };
+    let backoff = MINT_INITIAL_BACKOFF_MS;
+    let refusedInRow = 0;
+    for (;;) {
+        const minted = await mintTicket(options, deps);
+        if (minted.kind === "terminal")
+            return stop(minted.reason, minted.detail, 1);
+        if (minted.kind === "transient") {
+            await deps.sleep(backoff);
+            backoff = Math.min(MINT_MAX_BACKOFF_MS, backoff * 2);
+            continue;
+        }
+        backoff = MINT_INITIAL_BACKOFF_MS;
+        const run = { stopped: null, emitted: false };
+        const startedAt = deps.now();
+        await runListener({ streamUrl: minted.streamUrl, ticket: minted.ticket, leaseMs: minted.leaseMs, resumeIds: [...delivered] }, {
+            ...deps,
+            write: (output) => {
+                if (output.type === "stopped") {
+                    run.stopped = output;
+                    return;
+                }
+                run.emitted = true;
+                if (output.id !== null) {
+                    delivered.push(output.id);
+                    if (delivered.length > DELIVERED_ID_MEMORY)
+                        delivered.shift();
+                }
+                deps.write(output);
+            },
+        });
+        const stopped = run.stopped;
+        if (stopped === null)
+            throw new Error("the stream reader ended without a stop record");
+        if (TAKEOVER_REASONS.has(stopped.reason))
+            return stop(stopped.reason, stopped.detail, 0);
+        if (stopped.reason === "lease_expired") {
+            refusedInRow = 0;
+            continue;
+        }
+        if (stopped.reason === "refused") {
+            const provedHealthy = run.emitted || deps.now() - startedAt >= HEALTHY_CONNECTION_MS;
+            refusedInRow = provedHealthy ? 1 : refusedInRow + 1;
+            if (refusedInRow >= MAX_REFUSED_TICKETS_IN_A_ROW) {
+                return stop("refused", `${stopped.detail} (a freshly minted ticket was refused ${refusedInRow} times in a row)`, 1);
+            }
+            continue;
+        }
+        return stop(stopped.reason, stopped.detail, 1);
+    }
+}
+/** The bin's `bridge` subcommand, wired to the real process. */
+export async function runBridgeCommand(argv, env = process.env) {
+    let options;
+    try {
+        options = parseBridgeArgs(argv, env);
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n`);
+        return 2;
+    }
+    return runBridge(options, {
+        fetch: (input, init) => fetch(input, init),
+        write: (output) => {
+            process.stdout.write(`${JSON.stringify(output)}\n`);
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: Date.now,
+        readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
+        mintTimeoutMs: MINT_TIMEOUT_MS,
+    });
+}

package/dist/handlers.js

@@ -887,39 +887,6 @@ export async function planGet(client, args = {}) {
         query,
     });
 }
-function readIssuedTicket(body) {
-    const b = body;
-    return b !== null &&
-        typeof b.ticket === "string" &&
-        b.ticket !== "" &&
-        typeof b.streamPath === "string" &&
-        typeof b.leaseMs === "number"
-        ? { ticket: b.ticket, streamPath: b.streamPath, leaseMs: b.leaseMs }
-        : null;
-}
-/**
- * The exact shell command a Monitor runs. The ticket is the only credential in
- * it; the stream URL and lease come from the dashboard's own ticket response, so
- * the listener carries no copy of either.
- */
-export function listenCommand(target, issued) {
-    const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
-    const streamUrl = `${target.baseUrl.replace(/\/+$/, "")}${issued.streamPath}`;
-    return (`npx -y ${target.packageSpec} listen --stream ${quote(streamUrl)} ` +
-        `--ticket ${quote(issued.ticket)} --lease-ms ${issued.leaseMs}`);
-}
-function listenerNotArmed(status, connected, ticketResponse) {
-    return {
-        ok: false,
-        status,
-        body: {
-            error: "listener_not_armed",
-            message: "This session IS now connected to the plan, but no listener ticket was issued, so no listener can be armed and this plan's events will NOT reach this session. Resolve the problem below and call plan_connect again.",
-            connected,
-            ticket_response: ticketResponse,
-        },
-    };
-}
 /**
  * Connect THIS session to a plan — the same write the operator's Connect
  * action performs, reaching the same server-side code path. `me` in the URL
@@ -929,50 +896,19 @@ function listenerNotArmed(status, connected, ticketResponse) {
  * A session already on another plan is MOVED, and the response says which
  * plan it left (`movedFrom`).
  *
- * THEN IT ARMS THE LISTENER. A connected session must hear about its plan's
- * cards the moment something happens, so the reply carries the exact Monitor
- * command to run. The command holds a stream TICKET this server mints for the
- * session — never this server's own long-lived token, which must not appear in
- * a command line. Minting a ticket replaces the session's previous one, so
- * re-connecting (after a restart, or to re-arm) leaves exactly one listener.
- *
- * A refused ticket is NOT reported as a successful connect: the binding did
- * happen, but a session that believes it is listening when it is not would miss
- * the operator's answer silently, so the whole call fails loud and says both.
+ * IT DOES NOTHING ABOUT HEARING THE PLAN'S EVENTS, deliberately. Delivery belongs
+ * to the danxbot Claude Code plugin's plan event bridge, a background process
+ * that holds the session's ONE listener ticket and starts when this tool
+ * succeeds. The dashboard keeps one ticket per session, so a ticket minted here
+ * would end the bridge's stream.
  */
-export async function planConnect(client, args, listener) {
-    const connected = await client.request({
+export async function planConnect(client, args) {
+    return client.request({
         method: "POST",
         path: "/me/plan",
         basePath: PLAN_SESSIONS_BASE_PATH,
         body: { plan_id: args.plan_id },
     });
-    if (!connected.ok)
-        return connected;
-    let issued;
-    try {
-        issued = await client.request({
-            method: "POST",
-            path: "/me/stream-ticket",
-            basePath: PLAN_SESSIONS_BASE_PATH,
-        });
-    }
-    catch (err) {
-        // The binding already happened; a thrown ticket request must not erase that fact.
-        return listenerNotArmed(502, connected.body, { error: err instanceof Error ? err.message : String(err) });
-    }
-    const ticket = issued.ok ? readIssuedTicket(issued.body) : null;
-    if (ticket === null) {
-        return listenerNotArmed(issued.ok ? 502 : issued.status, connected.body, issued.body);
-    }
-    return {
-        ...connected,
-        listener: {
-            command: listenCommand(listener, ticket),
-            persistent: true,
-            instruction: "Arm this now with the Monitor tool (command above, persistent: true). Every comment, answer, requires_human change and block/unblock on this plan's cards will then arrive as a notification within seconds — do not poll for them. If the Monitor prints that it gave up or was ended, call plan_connect again and arm the new command.",
-        },
-    };
 }
 /** Add a goal, rule or caveat to the connected plan. `context` is sent only when given. */
 export async function planAddRecord(client, args) {

package/dist/index.js

@@ -81,10 +81,9 @@
  * agent reads `body.error` + structured fields to decide next action.
  * 5xx and network failures throw — never silently swallowed.
  */
-import { createRequire } from "node:module";
 import { basename } from "node:path";
 import { isEntrypointModule } from "./entrypoint.js";
-import { LISTEN_SUBCOMMAND, runListenCommand } from "./listen.js";
+import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -170,16 +169,6 @@ function readSessionConfig() {
     const fallback = cwdName === "" ? `session ${id.slice(0, 8)}` : cwdName;
     return { id, title: readEnvOptional("DANX_SESSION_TITLE") ?? fallback };
 }
-/**
- * This build's own npm spec. `plan_connect` hands out a `listen` command pinned to
- * it, so the listener that runs is always the one written for the stream this
- * server's dashboard speaks — never whatever `npx` happens to have cached.
- * `package.json` sits one level above both `src/` (tsx) and `dist/` (the bin).
- */
-const PACKAGE_SPEC = (() => {
-    const pkg = createRequire(import.meta.url)("../package.json");
-    return `${pkg.name}@${pkg.version}`;
-})();
 export const server = new McpServer({
     name: "danx-dashboard-mcp",
     version: "0.1.0",
@@ -275,19 +264,19 @@ const boardField = {
         .string()
         .min(1)
         .optional()
-        .describe("Target another board by its qualified id `<repo>:<slug>` (e.g. `platform:the-supply-operations-hub`); omit to use this dispatch's board. Unknown board → 404."),
+        .describe("Target another board by its qualified id `<repo>:<slug>`; omit for this dispatch's board. Unknown → 404."),
 };
 // The three prose fields of a card, each with ONE job. Shared by issue_create
 // (root + phase children) and issue_edit so the guidance an agent reads is
 // identical wherever it writes the field.
-const TITLE_DESCRIBE = 'Short, specific label that names the domain, so a reader recognises the card without opening it (e.g. "Guest checkout rejects carts holding a gift card"). Never a generic phrase like "2 real decisions needed", "Fix bug" or "Follow-up".';
-const SUMMARY_DESCRIBE = "1–3 plain-language sentences — no markdown, no jargon — for someone who has never seen this codebase: what the card is about and why it matters. Always shown, never collapsed. It must stand on its own: not a second title, not a teaser for the description.";
+const TITLE_DESCRIBE = 'Short, specific label naming the domain, so a reader recognises the card unopened (e.g. "Guest checkout rejects carts holding a gift card"). Never generic ("2 real decisions needed", "Fix bug", "Follow-up").';
+const SUMMARY_DESCRIBE = "1–3 plain-language sentences, no markdown/jargon, for someone new to this codebase: what the card is and why it matters. Always shown, never collapsed — not a second title, not a teaser for the description.";
 const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, technical detail; markdown, collapsed by default. A question for the operator and its options go in issue_problem, not here.';
 // ---------------- issue_list ----------------
 server.tool("issue_list", 
 // DX-2735: trimmed to pay for the problem tools inside the work-profile
 // injected-surface budget — same facts, no repeated prose.
-"List cards via GET /api/issues on this dispatch's board, or `board` (`<repo>:<slug>`; unknown → 404). `filter`: type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, q (free text over id+title+description). THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash), no joins; opt into heavy data with `fields` groups: description (+ summary), problems (open_problem_count), ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort. `sort`: [{column, order}] over id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at; default priority desc, repo_name asc, numeric-id tiebreaker. `limit`/`offset` page (uncapped by default). issue_get reads one card in full.", {
+"List cards via GET /api/issues. Board-scoped; see `board`. `filter`: type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, q (free text over id+title+description). THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash), no joins; opt into heavy data with `fields` groups: description (+ summary), problems (open_problem_count), ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort. `sort`: [{column, order}] over id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at; default priority desc, repo_name asc, numeric-id tiebreaker. `limit`/`offset` page (uncapped by default). issue_get reads one card in full.", {
     filter: z
         .object({
         q: z.string().optional(),
@@ -324,7 +313,7 @@ server.tool("issue_get",
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
-server.tool("issue_create", 'Create a card via POST /api/issues on this dispatch\'s board, or another via `board` (`<repo>:<slug>`; unknown → 404). type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `gate_decisions` is REQUIRED when the board has an OPTIONAL quality gate for the card\'s type: a missing one fails closed with 400 `{error, required_gate_decisions:[...]}` naming each gate — retry with one `{gate, enabled, note}` per listed gate. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child: true only when it should enter automatic triage/dispatch without human review; absent → false.', {
+server.tool("issue_create", 'Create a card via POST /api/issues. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `gate_decisions` is REQUIRED when the board has an OPTIONAL quality gate for the card\'s type: a missing one fails closed with 400 `{error, required_gate_decisions:[...]}` naming each gate — retry with one `{gate, enabled, note}` per listed gate. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child: true only when it should enter automatic triage/dispatch without human review; absent → false.', {
     type: z.enum(ISSUE_TYPES),
     title: z.string().min(1).describe(TITLE_DESCRIBE),
     summary: z.string().min(1).optional().describe(SUMMARY_DESCRIBE),
@@ -376,7 +365,7 @@ server.tool("issue_create", 'Create a card via POST /api/issues on this dispatch
     ...boardField,
 }, async (args) => jsonResult(await issueCreate(client, args, config.board)));
 // ---------------- issue_edit ----------------
-server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type, content_hash. Any other key (lifecycle, triage, dependencies, retro, requires_human, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro. `type`: Story/Bug/Chore makes a card eligible for autonomous pickup; Task or a container (Epic/Feature) removes that eligibility — how a planning item becomes work. `priority` (a tier word or a number) is the ONLY way to set priority; a "Priority:" line in the description changes nothing. CHECKLISTS: each item has one status `incomplete|failing|passing|cancelled|deferred`; `deferred` (work done, a real-world/post-deploy check outstanding) REQUIRES `detail`, and a `📡`-prefixed item can never be `passing`. `ac` edits the default "Acceptance Criteria" checklist (items matched by check_item_id, else exact title); `checklists` REPLACES every named checklist with full status control (`{name, items:[{label, detail?, status}]}`). Send `ac` OR `checklists`, not both (400). `list_id` pins the card to a list by id or display NAME; its type must match the card\'s current derived status (400 otherwise — ready a card before pinning it to a `ready` queue); null clears the pin. `content_hash` (DX-2741) is the card\'s optimistic-concurrency token — REQUIRED (never optional/defaulted) whenever the edit touches `title` / `description` / `checklists` (NOT `ac`, which keeps its own check_item_id/title diffing): a missing hash on one of those fields 400s, a stale one 409s `stale_issue_content` carrying `currentHash` + `currentTitle` + `currentDescription`. Read it off `issue_get`/`issue_list`\'s `content_hash` scalar field (present even in the minimal response) immediately before editing; on a 409, re-`issue_get` and retry with the fresh hash — never blindly.', {
+server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type, content_hash. Any other key (lifecycle, triage, dependencies, retro, requires_human, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro. `type`: Story/Bug/Chore = eligible for autonomous pickup; Task or a container (Epic/Feature) removes that eligibility — how a planning item becomes work. `priority` (a tier word or a number) is the ONLY way to set priority; a "Priority:" line in the description does nothing. CHECKLISTS: each item has one status `incomplete|failing|passing|cancelled|deferred`; `deferred` (work done, a real-world/post-deploy check outstanding) REQUIRES `detail`, and a `📡`-prefixed item can never be `passing`. `ac` edits the default "Acceptance Criteria" checklist (items matched by check_item_id, else exact title); `checklists` REPLACES every named checklist with full status control (`{name, items:[{label, detail?, status}]}`). Send `ac` OR `checklists`, not both (400). `list_id` pins the card to a list by id or display NAME; its type must match the card\'s current derived status (400 otherwise — e.g. ready the card first before pinning it to a `ready`-type list); null clears the pin. `content_hash` (DX-2741) is the card\'s optimistic-concurrency token — REQUIRED whenever the edit touches `title` / `description` / `checklists` (NOT `ac`, which keeps its own check_item_id/title diffing): missing → 400, stale → 409 `stale_issue_content` carrying `currentHash` + `currentTitle` + `currentDescription`. Read it off `issue_get`/`issue_list`\'s `content_hash` scalar (present even minimal); on 409, re-`issue_get` and retry with the fresh hash — never blindly.', {
     id: z.string().min(1),
     title: z.string().min(1).optional().describe(TITLE_DESCRIBE),
     summary: z
@@ -476,7 +465,7 @@ const CHECKLIST_ITEM_INPUT = z.object({
     detail: z.string().optional(),
     status: z.enum(CHECKLIST_ITEM_STATUSES).optional(),
 });
-server.tool("issue_checklist", "Targeted checklist CUD via /api/issues/:id/checklists[/:cid[/items[/:iid]]] (DX-1362). Mutates ONE checklist or item WITHOUT the wholesale `issue_edit({checklists})` replace — use this for the common case (flip an item's status, add/rename a checklist, add/edit/remove an item); the wholesale path silently DROPS any checklist you omit and churns every item id (orphaning its Trello mirror), so prefer this for single-item changes. Action-dispatched: add_list (POST :id/checklists {name, items?}) — create a named checklist, optionally with initial items; update_list (PATCH :id/checklists/:cid {name}) — rename; remove_list (DELETE :id/checklists/:cid) — soft-delete the checklist (audit trail preserved); add_item (POST :id/checklists/:cid/items {label, detail?, status?}) — append an item (status defaults `incomplete`); update_item (PATCH :id/checklists/:cid/items/:iid {label?, detail?, status?}) — change ONLY the fields you pass, in place (the item keeps its id + Trello linkage; at least one field required); remove_item (DELETE :id/checklists/:cid/items/:iid) — soft-delete one item. Status: incomplete|failing|passing|cancelled|deferred (terminal = passing|cancelled|deferred; DX-2653 added `deferred` — the honest disposition for a criterion whose work is done but names a real-world/post-deploy check still outstanding, REQUIRES a non-empty `detail`). checklist_id is required for every action except add_list; item_id for update_item/remove_item. Each returns the {ok,status,body} envelope; unknown card/checklist/item → 404, invalid status → 400. ADDITIVE — the wholesale `issue_edit({checklists})` path stays for bulk authoring.", {
+server.tool("issue_checklist", "Targeted checklist CUD via /api/issues/:id/checklists[/:cid[/items[/:iid]]] (DX-1362). Mutates ONE checklist/item without the wholesale `issue_edit({checklists})` replace, which DROPS any checklist you omit and churns every item id (orphaning its Trello mirror) — prefer this for single-item changes. Action-dispatched: add_list (POST :id/checklists {name, items?}) — create a named checklist, optionally with initial items; update_list (PATCH :id/checklists/:cid {name}) — rename; remove_list (DELETE :id/checklists/:cid) — soft-delete the checklist (audit trail preserved); add_item (POST :id/checklists/:cid/items {label, detail?, status?}) — append an item (status defaults `incomplete`); update_item (PATCH :id/checklists/:cid/items/:iid {label?, detail?, status?}) — change ONLY the fields you pass, in place (keeps id + Trello link; ≥1 field required); remove_item (DELETE :id/checklists/:cid/items/:iid) — soft-delete one item. Status: incomplete|failing|passing|cancelled|deferred (terminal = passing|cancelled|deferred; DX-2653 added `deferred` — the honest disposition for a criterion whose work is done but names a real-world/post-deploy check still outstanding, REQUIRES a non-empty `detail`). checklist_id is required for every action except add_list; item_id for update_item/remove_item. Each returns the {ok,status,body} envelope; unknown card/checklist/item → 404, invalid status → 400. ADDITIVE — `issue_edit({checklists})` still works for bulk authoring.", {
     id: z.string().min(1),
     action: z.enum([
         "add_list",
@@ -505,7 +494,7 @@ const SOLUTION_FIELDS = {
     con: z.string().optional(),
     recommended: z.boolean().optional(),
 };
-server.tool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: each is one statement the operator must resolve (a question, or a flaw in the plan) with its own solutions and answers — one problem per question. OPEN = not yet answered; the card needs a human until none is open, and issue_requires_human set is refused 409 `no_open_problem` until one is. list → live problems in order, each {id, statement, content_hash, open, solutions[], decisions[]}; add {statement, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form); edit :pid {base_hash, statement}; remove :pid {base_hash} (409 `last_open_problem` while requires_human is set). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard.", {
+server.tool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: one statement the operator must resolve (a question, or a flaw in the plan), each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human until none is open, and issue_requires_human set is refused 409 `no_open_problem` until one is. list → live problems in order, each {id, statement, content_hash, open, solutions[], decisions[]}; add {statement, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form); edit :pid {base_hash, statement}; remove :pid {base_hash} (409 `last_open_problem` while requires_human is set). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard.", {
     id: z.string().min(1),
     action: z.enum(["list", "add", "edit", "remove"]),
     problem_id: z.number().int().positive().optional().describe("edit/remove"),
@@ -547,7 +536,7 @@ server.tool("issue_requires_human", "Set/clear the requires_human gate via /api/
     ...boardField,
 }, async (args) => jsonResult(await issueRequiresHuman(client, args)));
 // ---------------- issue_quality_gate ----------------
-server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the only post-create way (issue_create takes gate_decisions; issue_edit refuses gate keys). PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate → 400. The board state per gate is tri-state: `required` always runs, `optional` runs WHEN this flag is true (optional is NOT off), `disabled` never runs. Optional `effort_level` overrides a `plan-*` gate's reviewer rung (null clears it). The write always succeeds and returns `{issue, applied: true, effective, reason}` — read `effective` (does the gate now run) and `reason` (why the board overrode your value), not just the 200. Pass `board` to target another board.", {
+server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the only post-create way (issue_create takes gate_decisions; issue_edit refuses gate keys). PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate → 400. The board state per gate is tri-state: `required` always runs, `optional` runs WHEN this flag is true (optional is NOT off), `disabled` never runs. Optional `effort_level` overrides a `plan-*` gate's reviewer rung (null clears it). The write always succeeds and returns `{issue, applied: true, effective, reason}` — read `effective` (does the gate now run) and `reason` (why the board overrode your value), not just the 200. Board-scoped; see `board`.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",
@@ -562,7 +551,7 @@ server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via P
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGate(client, args)));
 // ---------------- issue_quality_gate_verdict ----------------
-server.tool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate VERDICT via PATCH /api/issues/:id/quality-gates/:gate {status, message} — the same write the dashboard Gates-tab Pass / Fail / Revert controls perform (DX-1373). SIBLING of `issue_quality_gate`, not a replacement: that one flips the per-card `required` FLAG (does this gate run at all), THIS one records the VERDICT (did it pass) — the server exposes them as POST vs PATCH on the same resource and neither substitutes for the other. **Use this to close out a card you picked up with `issue_transition pickup {manual:true}`** (DX-946 operator-session self-pickup): `issue_transition complete` REFUSES 409 (`failed_gate: \"quality_gate_post\"`, `failed_post_gates[]`) while any required POST gate (`code-quality` / `code-test-quality` / `code-architecture`) is not `pass`, so without a verdict a manually-claimed card can never reach Done — it strands In Progress and its `conflict_on` / `waiting_on` edges then stall OTHER cards' dispatch. `status`: `pass` | `fail` | `pending` (revert a prior verdict, clears the message). `message` is the accountability record for the override and is REQUIRED at >= 20 characters for `pass`/`fail` (shorter → 400); it is ignored for `pending`. Record the REAL reviewer finding here, not a rubber stamp — this is a human-attributed override, stamped with the operator actor, and it is what a later reader sees instead of a reviewer dispatch. A manual verdict is a PURE row write: unlike the worker's in-dispatch gate route it fires NO side effects — a manual `fail` never blocks the card and a manual `pass` never releases a dispatch. Unknown gate → 400; status outside the three values → 400; unknown card → 404. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
+server.tool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate VERDICT via PATCH /api/issues/:id/quality-gates/:gate {status, message} — the same write the dashboard Gates-tab Pass / Fail / Revert controls perform (DX-1373). SIBLING of `issue_quality_gate`, not a replacement: that one flips the per-card `required` FLAG (does this gate run at all), THIS one records the VERDICT (did it pass) — POST vs PATCH on the same resource, neither substitutes for the other. **Use this to close out a card you picked up with `issue_transition pickup {manual:true}`** (DX-946 operator-session self-pickup): `issue_transition complete` REFUSES 409 (`failed_gate: \"quality_gate_post\"`, `failed_post_gates[]`) while any required POST gate (`code-quality` / `code-test-quality` / `code-architecture`) is not `pass`, so without a verdict a manually-claimed card can never reach Done — it strands In Progress and its `conflict_on` / `waiting_on` edges then stall OTHER cards' dispatch. `status`: `pass` | `fail` | `pending` (revert a prior verdict, clears the message). `message` is the accountability record for the override, REQUIRED at >= 20 characters for `pass`/`fail` (shorter → 400), ignored for `pending`. Record the REAL reviewer finding, not a rubber stamp — a human-attributed override, stamped with the operator actor, standing in for a reviewer dispatch. A manual verdict is a PURE row write: no side effects — a manual `fail` never blocks the card and a manual `pass` never releases a dispatch. Unknown gate → 400; bad status → 400; unknown card → 404. Board-scoped; see `board`.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",
@@ -577,7 +566,7 @@ server.tool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGateVerdict(client, args)));
 // ---------------- issue_retro ----------------
-server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retro. Body: {good, bad, action_item_ids[], commits[], tests[]}. REFUSES 409 unless the card is terminal (completed_at OR cancelled_at) — retro ships when work concludes. Replace semantics: good/bad upsert; action_item_ids[] + commits[] + tests[] soft-delete prior live rows and insert with fresh ordinals. action_item_ids[] entries MUST match <PREFIX>-N. commits[] entries take {sha, subject?}. tests[] (DX-1646) is REQUIRED (empty array allowed — the \"ran no tests\" case): one row per test GROUP that ran (a whole suite/class — name the group, do NOT list individual unit tests) or per individual e2e test (kind:'e2e', listed explicitly since they are few + expensive). Each row: {name, kind:'group'|'e2e', num_tests, num_passing_tests, duration_ms} required; num_assertions + num_passing_assertions NULLABLE (vitest surfaces no assertion totals — pass null or omit).", {
+server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retro. Body: {good, bad, action_item_ids[], commits[], tests[]}. REFUSES 409 unless the card is terminal (completed_at OR cancelled_at) — retro ships when work concludes. Replace semantics: good/bad upsert; action_item_ids[] + commits[] + tests[] soft-delete prior live rows and insert with fresh ordinals. action_item_ids[] entries MUST match <PREFIX>-N. commits[] entries take {sha, subject?}. tests[] (DX-1646) is REQUIRED (empty array allowed — the \"ran no tests\" case): one row per test GROUP that ran (a whole suite/class — name the group, do NOT list individual unit tests) or per individual e2e test (kind:'e2e', few + expensive so listed explicitly). Each row: {name, kind:'group'|'e2e', num_tests, num_passing_tests, duration_ms} required; num_assertions + num_passing_assertions NULLABLE (vitest has no assertion totals — pass null or omit).", {
     id: z.string().min(1),
     good: z.string(),
     bad: z.string(),
@@ -607,7 +596,7 @@ server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retr
 // route's MAX_DECODED_BYTES (src/issues/write/attachments.ts). This package is
 // a separate published artifact and cannot import that constant, so the number
 // is restated here as prose — keep the two in sync if the backend ceiling moves.
-server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/issues/:id/attachments. Pass `id` (the card) and `file_path` (an ABSOLUTE path to a file on the dispatch's shared filesystem — e.g. a screenshot, exported CSV, or diagram you wrote). This MCP server reads the bytes, infers the MIME type from the extension, and uploads through the dashboard, which: stores the bytes in S3, inserts ONE danxbot-origin issue_attachments row, and auto-mirrors the file to the card's linked Trello card AND its Slack card-view thread (DX-1122 outbound projection) — no extra step needed. Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to attach on another board (unknown board → 404). Fail-loud: a relative/empty path is rejected at the MCP boundary, and a missing/unreadable file throws BEFORE any upload (no partial S3 object, no row). 25 MB decoded ceiling (413). Returns the hydrated issue plus the new attachment id.", {
+server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/issues/:id/attachments. Pass `id` (the card) and `file_path` (an ABSOLUTE path to a file on the dispatch's shared filesystem — e.g. a screenshot, exported CSV, or diagram you wrote). This MCP server reads the bytes, infers the MIME type from the extension, and uploads through the dashboard, which: stores the bytes in S3, inserts ONE danxbot-origin issue_attachments row, and auto-mirrors the file to the card's linked Trello card AND its Slack card-view thread (DX-1122 outbound projection) — no extra step needed. Board-scoped; see `board`. Fail-loud: a relative/empty path is rejected at the MCP boundary, and a missing/unreadable file throws BEFORE any upload (no partial S3 object, no row). 25 MB decoded ceiling (413). Returns the hydrated issue plus the new attachment id.", {
     id: z.string().min(1),
     file_path: z
         .string()
@@ -616,11 +605,11 @@ server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/
     ...boardField,
 }, async (args) => jsonResult(await issueAttach(client, args)));
 // ---------------- repo_knowledge_get ----------------
-server.tool("repo_knowledge_get", "Fetch the board's working-knowledge markdown doc via GET /api/repo-knowledge (DX-1128, Story 2). Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to read another board's doc. Returns `{ok, status, body: {content, contentHash, updatedAt, updatedBy, boardId}}` — an unset doc reads as the empty view (`content: \"\"`, `contentHash: \"\"`), NOT a 404. Ground exploratory answers in `content`; before `repo_knowledge_set`, ALWAYS `repo_knowledge_get` immediately first and pass its `contentHash` back as `base_hash` — the server's optimistic-concurrency guard rejects a stale write.", {
+server.tool("repo_knowledge_get", "Fetch the board's working-knowledge markdown doc via GET /api/repo-knowledge (DX-1128, Story 2). Board-scoped; see `board`. Returns `{ok, status, body: {content, contentHash, updatedAt, updatedBy, boardId}}` — an unset doc reads as the empty view (`content: \"\"`, `contentHash: \"\"`), NOT a 404. Ground exploratory answers in `content`; before `repo_knowledge_set`, ALWAYS `repo_knowledge_get` immediately first and pass its `contentHash` back as `base_hash` — the server's optimistic-concurrency guard rejects a stale write.", {
     ...boardField,
 }, async (args) => jsonResult(await repoKnowledgeGet(client, args)));
 // ---------------- repo_knowledge_set ----------------
-server.tool("repo_knowledge_set", 'Write the board\'s working-knowledge markdown doc via PUT /api/repo-knowledge (DX-1128, Story 2). Board-scoped; defaults to the dispatch\'s board. `base_hash` MUST be the `contentHash` from the immediately-prior `repo_knowledge_get` call ("" for the true first write, when the board has no doc yet) — the server compares it against the CURRENT hash and, on mismatch, fails loud with `{ok: false, body: {error: "stale_repo_knowledge", currentHash}}` rather than silently overwriting a concurrent write. On that refusal: re-`repo_knowledge_get`, re-merge your insight into the fresh content, and retry `repo_knowledge_set` with the new hash. On success, persists to the DB, publishes `repo-knowledge:updated` over SSE (live in the dashboard editor), and returns the new view.', {
+server.tool("repo_knowledge_set", 'Write the board\'s working-knowledge markdown doc via PUT /api/repo-knowledge (DX-1128, Story 2). Board-scoped; see `board`. `base_hash` MUST be the `contentHash` from the immediately-prior `repo_knowledge_get` call ("" for the true first write, when the board has no doc yet) — the server compares it against the CURRENT hash and, on mismatch, fails loud with `{ok: false, body: {error: "stale_repo_knowledge", currentHash}}` rather than silently overwriting a concurrent write. On that refusal: re-`repo_knowledge_get`, re-merge your insight into the fresh content, and retry `repo_knowledge_set` with the new hash. On success, persists to the DB, publishes `repo-knowledge:updated` over SSE (live in the dashboard editor), and returns the new view.', {
     content: z.string(),
     base_hash: z
         .string()
@@ -629,11 +618,11 @@ server.tool("repo_knowledge_set", 'Write the board\'s working-knowledge markdown
     ...boardField,
 }, async (args) => jsonResult(await repoKnowledgeSet(client, args)));
 // ---------------- brief_list ----------------
-server.tool("brief_list", "List the board's named Brief pages via GET /api/brief (DX-2083 / DX-2484). Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to list another board's pages. Returns `{boardId, pages: [{slug, title, contentHash, sortOrder, updatedAt, updatedBy}]}` — metadata only, no page content (use `brief_get_page` for that). This is the list+page-shaped sibling of `repo_knowledge_get`/`repo_knowledge_set` (one board-level doc) — Brief pages are MANY named pages per board (the Goals / Architecture / Rules / Caveats tabs), keyed by `(board, slug)`. The reserved `index` slug always exists — every board carries exactly one.", {
+server.tool("brief_list", "List the board's named Brief pages via GET /api/brief (DX-2083 / DX-2484). Board-scoped; see `board`. Returns `{boardId, pages: [{slug, title, contentHash, sortOrder, updatedAt, updatedBy}]}` — metadata only, no page content (use `brief_get_page` for that). This is the list+page-shaped sibling of `repo_knowledge_get`/`repo_knowledge_set` (one board-level doc) — Brief pages are MANY named pages per board (the Goals / Architecture / Rules / Caveats tabs), keyed by `(board, slug)`. The reserved `index` slug always exists — every board carries exactly one.", {
     ...boardField,
 }, async (args) => jsonResult(await briefList(client, args)));
 // ---------------- brief_get_page ----------------
-server.tool("brief_get_page", 'Fetch one Brief page by slug via GET /api/brief/page?slug=<slug> (DX-2083 / DX-2484). Board-scoped; defaults to the dispatch\'s board. Returns `{boardId, slug, title, content, contentHash, sortOrder, updatedAt, updatedBy}` — a missing/not-yet-created page reads as the empty view (`content: ""`, `contentHash: ""`), NOT a 404, matching `repo_knowledge_get`\'s convention. Before `brief_set_page`, ALWAYS `brief_get_page` immediately first and pass its `contentHash` back as `base_hash` — the server\'s optimistic-concurrency guard rejects a stale write.', {
+server.tool("brief_get_page", 'Fetch one Brief page by slug via GET /api/brief/page?slug=<slug> (DX-2083 / DX-2484). Board-scoped; see `board`. Returns `{boardId, slug, title, content, contentHash, sortOrder, updatedAt, updatedBy}` — a missing/not-yet-created page reads as the empty view (`content: ""`, `contentHash: ""`), NOT a 404, matching `repo_knowledge_get`\'s convention. Before `brief_set_page`, ALWAYS `brief_get_page` immediately first and pass its `contentHash` back as `base_hash` — the server\'s optimistic-concurrency guard rejects a stale write.', {
     slug: z
         .string()
         .min(1)
@@ -641,7 +630,7 @@ server.tool("brief_get_page", 'Fetch one Brief page by slug via GET /api/brief/p
     ...boardField,
 }, async (args) => jsonResult(await briefGetPage(client, args)));
 // ---------------- brief_set_page ----------------
-server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug=<slug> (DX-2083 / DX-2484). Board-scoped; defaults to the dispatch\'s board. Body: `{content, title?, sortOrder?, base_hash?}` — mirrors `repo_knowledge_set`\'s optimistic-concurrency shape but targets one named page instead of the board\'s single working-knowledge doc. `base_hash` MUST be the `contentHash` from the immediately-prior `brief_get_page` call ("" for a true first write, when the page doesn\'t exist yet) — the server compares it against the CURRENT hash and, on mismatch, fails loud with `{ok: false, body: {error: "stale_brief_page", currentHash}}` rather than silently overwriting a concurrent write — re-get, re-merge, and retry on that refusal, never retry blindly or overwrite. On success, persists to the DB, publishes `brief:updated` over SSE, and returns the new view. NO delete tool is exposed on this surface — the reserved `index` slug can never be deleted through the tool surface, matching the route\'s own refusal; deleting a non-index page is dashboard-UI-only for now.', {
+server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug=<slug> (DX-2083 / DX-2484). Board-scoped; see `board`. Body: `{content, title?, sortOrder?, base_hash?}` — mirrors `repo_knowledge_set`\'s optimistic-concurrency shape but targets one named page instead of the board\'s single working-knowledge doc. `base_hash` MUST be the `contentHash` from the immediately-prior `brief_get_page` call ("" for a true first write, when the page doesn\'t exist yet) — the server compares it against the CURRENT hash and, on mismatch, fails loud with `{ok: false, body: {error: "stale_brief_page", currentHash}}` rather than silently overwriting a concurrent write — re-get, re-merge, and retry on that refusal, never retry blindly or overwrite. On success, persists to the DB, publishes `brief:updated` over SSE, and returns the new view. NO delete tool is exposed on this surface — the reserved `index` slug can never be deleted through the tool surface, matching the route\'s own refusal; deleting a non-index page is dashboard-UI-only for now.', {
     slug: z
         .string()
         .min(1)
@@ -665,8 +654,8 @@ server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug
 // plan id — and it can only ever bind the caller's own session. `plan_create`
 // also takes no plan id, but for a different reason: it MAKES a plan rather
 // than acting on one, so there is no existing plan for an id to name yet.
-server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped: a plan is a named, dated set of cards an operator assembled by hand, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session, sessionListenerAttached}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). `sessionListenerAttached` says whether your event listener is running: `false` while connected to a plan means you will NOT hear about its cards — call `plan_connect` again and arm the Monitor it returns. NOTE this is NOT the board Brief (`brief_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
-server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{plan, boards, cardCount, bucketCounts, session, sessionListenerAttached, available_field_groups}` — no member cards, no goals/rules/caveats, no architecture body. Pass `fields` to opt into the rest, one call at a time: `cards` (member cards, PAGED: `cards_offset` (default 0) and `cards_limit` (1.." + LIST_PAGE_MAX_LIMIT + ", default " + PLAN_GET_CARDS_DEFAULT_LIMIT + ") pick the page, in card-reference order (board prefix, then card number — stable while cards are edited, so pages never repeat or skip a card unless the plan's membership changes between reads), and the response carries `cards_total` and `cards_offset` — page with cards_offset while cards_offset + cards.length < cards_total; either paging arg without `fields: [\"cards\"]` is a 400), `records` (every goal+rule+caveat, keyed by kind) or `records:goal` / `records:rule` / `records:caveat` (just that one kind — cheaper than the full union), `architecture` (`{sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}`), `sessions` (every session connected to the plan). `session`/`sessionListenerAttached` (your own connection state) and `available_field_groups` ride EVERY response, gated or not. `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `contentHash` back as `base_hash`.", {
+server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped: a plan is a named, dated set of cards an operator assembled by hand, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session, sessionListenerAttached}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). `sessionListenerAttached` says whether your session's event stream is attached (the danxbot plugin's plan event bridge holds it). It is `false` for a few seconds right after `plan_connect` while the bridge starts; still `false` after that while connected means its card events are NOT reaching you — tell the operator. There is nothing to arm. NOTE this is NOT the board Brief (`brief_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
+server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id` to read ANY plan; OMIT to read the plan this session is connected to — omitting while connected to none fails loud `{error: \"session_not_connected\"}`, connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{plan, boards, cardCount, bucketCounts, session, sessionListenerAttached, available_field_groups}` — no cards, records, or architecture body. Pass `fields` to opt into: `cards` (member cards, PAGED: `cards_offset` (default 0) and `cards_limit` (1.." + LIST_PAGE_MAX_LIMIT + ", default " + PLAN_GET_CARDS_DEFAULT_LIMIT + ") pick the page, in stable card-reference order (board prefix, then card number — pages never repeat/skip unless membership changes between reads); response carries `cards_total`/`cards_offset` — page while cards_offset + cards.length < cards_total; either paging arg without `fields: [\"cards\"]` is a 400), `records` (every goal+rule+caveat, keyed by kind) or `records:goal` / `records:rule` / `records:caveat` (one kind, cheaper), `architecture` (`{sections: [{id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}]}`), `sessions` (every session connected to the plan). `session`/`sessionListenerAttached` and `available_field_groups` ride every response regardless. `sessionListenerAttached` is `false` for a few seconds right after `plan_connect` while the plugin's event bridge starts; still `false` after that while connected means the plan's card events are not reaching you — tell the operator. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `contentHash` back as `base_hash`.", {
     plan_id: z
         .number()
         .int()
@@ -696,9 +685,9 @@ server.tool("plan_create", "Create a new, empty plan via POST /api/plans (DX-253
 }, async (args) => jsonResult(await planCreate(client, args)));
 server.tool("plan_connect", 
 // DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
-"Connect THIS session to a plan via POST /api/plan-sessions/me/plan — the same binding the operator's Connect action writes. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and the reply says which plan it left: `{session, movedFrom: {id, name} | null}` (null = no plan, or already this one). It binds only your OWN session, resolved from the session id this server forwards. Afterwards every plan WRITE tool acts on this plan and takes no plan id. THE REPLY ALSO CARRIES `listener: {command, persistent: true, instruction}` — arm it IMMEDIATELY with the Monitor tool (`persistent: true`): every comment, answer, requires_human change and block/unblock on this plan's cards then arrives as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<problem statement>\": chose \"Pause E2E\" — note: \"…\"`. Never poll for these. The command holds a narrow stream ticket, not a credential; calling plan_connect again (same plan is fine) issues a new one and ends the old listener — how you re-arm after a restart or a give-up. If no ticket can be issued the call fails `listener_not_armed`, though the connect happened.", {
+"Connect THIS session to a plan via POST /api/plan-sessions/me/plan — the same binding the operator's Connect action writes. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and the reply says which plan it left: `{session, movedFrom: {id, name} | null}` (null = no plan, or already this one). It binds only your OWN session, resolved from the session id this server forwards. Afterwards every plan WRITE tool acts on this plan and takes no plan id. Every comment, answer, requires_human change and block/unblock on this plan's cards then reaches the session on its own, relayed by the danxbot plugin's plan event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<problem statement>\": chose \"Pause E2E\"`. Nothing to arm; never poll for these.", {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
-}, async (args) => jsonResult(await planConnect(client, args, { baseUrl: config.baseUrl, packageSpec: PACKAGE_SPEC })));
+}, async (args) => jsonResult(await planConnect(client, args)));
 server.tool("plan_add_record", "Add a goal, rule or caveat to your connected plan (POST /api/plans/mine/records). A GOAL is an outcome the work is measured against. A RULE is a constraint that must hold while it is worked. A CAVEAT is a lasting trade-off or limitation of the ARCHITECTURE — never progress, status or a session note (those are comments on the card). `body` is ONE plain statement of at most 250 characters; the evidence, history and detail go in `context` (markdown). An overlong body is refused with a 400 naming its length. The server allocates a permanent reference (`G-1`, `R-4`, `CAV-12`). Takes no plan id; `session_not_connected` → `plan_connect` first. Returns the record plus that kind's list.", {
     kind: z.enum(["goal", "rule", "caveat"]).describe("goal = outcome, rule = constraint, caveat = architecture trade-off."),
     body: z.string().min(1).describe("One plain statement, at most 250 characters. Details go in `context`."),
@@ -769,21 +758,21 @@ async function main() {
 // symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
 // spawns, not just a direct `node dist/index.js`.
 //
-// `listen` is the one subcommand: the session event listener `plan_connect`
-// tells the agent to arm as a Monitor. It never boots the MCP server and reads
-// none of the MCP env — its whole configuration is its two flags. Any OTHER
-// argument is refused rather than ignored, so a typo cannot silently start an
-// MCP server on stdio where a listener was meant to run.
+// `bridge` is the one subcommand: the session event stream client the danxbot
+// plugin's plan event bridge runs. It never boots the MCP server; its whole
+// configuration is its environment (dashboard URL, credential, session id) plus
+// `--resume-ids`. Any OTHER argument is refused rather than ignored, so a typo
+// cannot silently start an MCP server on stdio where the bridge was meant to run.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
     const [subcommand, ...rest] = process.argv.slice(2);
-    if (subcommand === LISTEN_SUBCOMMAND) {
-        runListenCommand(rest).then((code) => process.exit(code), (err) => {
-            console.error(`[danx-dashboard-mcp] listen fatal: ${err.message}`);
+    if (subcommand === BRIDGE_SUBCOMMAND) {
+        runBridgeCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] bridge fatal: ${err.message}`);
             process.exit(1);
         });
     }
     else if (subcommand !== undefined) {
-        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is "${LISTEN_SUBCOMMAND}")`);
+        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is "${BRIDGE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/listen.js

@@ -1,69 +1,47 @@
 /**
- * `danx-dashboard-mcp listen --stream <url> --ticket <ticket> --lease-ms <ms>` —
- * a working session's event listener.
+ * The session event STREAM READER — holds ONE listener ticket's connection to the
+ * dashboard's session event stream and emits one record per event.
  *
- * WHY IT EXISTS. A Claude Code session cannot be interrupted from outside, but
- * its Monitor tool runs a background command and turns every line that command
- * prints into a notification that wakes the session. This command is that
- * background process: it holds the dashboard's session event stream open and
- * prints ONE line per event on the plan the session is connected to — a comment,
- * an answer, a `requires_human` change, a block — so the operator's answer
- * reaches the agent within seconds, with no polling anywhere.
+ * WHO USES IT. Only `bridge.ts` (`danx-dashboard-mcp bridge`), which mints the
+ * ticket, runs this reader in-process, and re-mints when a ticket's lease runs out.
+ * The ticket therefore never leaves the bridge process: no command line, no
+ * environment variable.
  *
- * THE OUTPUT CONTRACT, BECAUSE EVERY LINE WAKES THE AGENT:
- *   - exactly one line per event, written the moment it arrives;
- *   - nothing for keep-alives, the connect marker, or a successful reconnect;
- *   - one line for an event it cannot read (never silence);
- *   - one final line, and exit, only when it gives up or the dashboard ends it.
+ * THE OUTPUT CONTRACT (`ListenOutput`), because every event record reaches an agent:
+ *   - `{type:"event", id, text}` — exactly one per event, the moment it arrives.
+ *     `text` is what the session reads; an event it cannot read still produces one
+ *     (`could not read event …`), never silence. `id` is `null` only for a frame
+ *     that carried no usable id.
+ *   - `{type:"stopped", reason, detail}` — once, last. `reason` is the dashboard's
+ *     own end reason (`superseded`, `replaced`, `revoked`), `refused` (the ticket
+ *     was not admitted), or `lease_expired` (no healthy connection for the lease).
+ *   - nothing for keep-alives, the connect marker, or a successful reconnect.
  *
- * RECONNECT. The stream drops whenever the dashboard restarts, and can also die
- * silently (sleep, NAT, proxy). A read-idle timeout of three missed keep-alives
- * turns silent death into a drop. Retries use capped exponential backoff and send
- * `Last-Event-ID`; the dashboard replays what was missed (with a small overlap)
- * and an id already printed is never printed twice. The backoff only resets once
- * a connection proves healthy — it delivered an event, or stayed up past one
- * keep-alive — so a dashboard that admits and immediately drops is not hammered.
- * The listener gives up once it has gone `--lease-ms` without a healthy
- * connection (past that the ticket cannot be admitted anyway), or at once when
- * the ticket is refused.
+ * RECONNECT AND RESUME. The stream drops whenever the dashboard restarts, and can
+ * also die silently (sleep, NAT, proxy). A read-idle timeout of three missed
+ * keep-alives turns silent death into a drop. Retries use capped exponential
+ * backoff and send `Last-Event-ID`; the dashboard replays what was missed, with a
+ * commit-order overlap that re-sends recently delivered ids, and an id already
+ * emitted is never emitted twice. `resumeIds` carries that memory across a ticket
+ * or process restart: the ids already delivered seed the duplicate guard, and the
+ * highest is the first `Last-Event-ID`. The backoff only resets once a connection
+ * proves healthy — it delivered an event, or stayed up past one keep-alive — so a
+ * dashboard that admits and immediately drops is not hammered.
  *
- * Everything server-specific — the stream URL and the lease — arrives as flags
- * from `plan_connect`, which read them off the dashboard's own ticket response.
  * Only the event shape is hand-copied from the dashboard's `IssueActivityEvent`
  * (`src/issues/db/issue-activity.ts`); this published package cannot import
  * danxbot source.
  */
 import { oneLine } from "./one-line.js";
-export const LISTEN_SUBCOMMAND = "listen";
 export const INITIAL_BACKOFF_MS = 1_000;
 export const MAX_BACKOFF_MS = 30_000;
 /** Three of the dashboard's 15 s keep-alives without a byte means the connection is dead. */
 export const READ_IDLE_TIMEOUT_MS = 45_000;
 /** A connection that stays up this long has proven the dashboard healthy. */
 export const HEALTHY_CONNECTION_MS = 20_000;
-/** How many printed event ids the duplicate guard remembers — well past the replay overlap. */
-const PRINTED_ID_MEMORY = 1_000;
+/** How many delivered event ids the duplicate guard remembers — well past the replay overlap. */
+export const DELIVERED_ID_MEMORY = 1_000;
 const LINE_PREFIX = "[danx-dashboard listen]";
-const REARM = "Call plan_connect again and arm the Monitor it returns to keep receiving this plan's events.";
-const USAGE = `usage: danx-dashboard-mcp ${LISTEN_SUBCOMMAND} --stream <stream-url> --ticket <ticket> --lease-ms <ms>`;
-/** Parse the three required flags; anything else is refused. */
-export function parseListenArgs(argv) {
-    const values = new Map();
-    for (let i = 0; i < argv.length; i += 2) {
-        const flag = argv[i];
-        const value = argv[i + 1];
-        if (!["--stream", "--ticket", "--lease-ms"].includes(flag) || value === undefined || value === "") {
-            throw new Error(USAGE);
-        }
-        values.set(flag, value);
-    }
-    const streamUrl = values.get("--stream");
-    const ticket = values.get("--ticket");
-    const leaseMs = Number(values.get("--lease-ms"));
-    if (!streamUrl || !ticket || !Number.isSafeInteger(leaseMs) || leaseMs <= 0)
-        throw new Error(USAGE);
-    return { streamUrl, ticket, leaseMs };
-}
 function quoted(value) {
     return `"${value.text}${value.truncated ? "…" : ""}"`;
 }
@@ -143,11 +121,11 @@ function describe(event) {
             return `${event.actor} unblocked the card`;
         default:
             // A kind newer than this listener still produces a line: an event the
-            // agent is never told about is exactly the failure this command prevents.
+            // agent is never told about is exactly the failure this reader prevents.
             return `${event.actor}: ${event.kind}`;
     }
 }
-/** The one notification line for an event. Always a single line; throws, naming the fault, on a malformed event. */
+/** The one readable line for an event. Always a single line; throws, naming the fault, on a malformed event. */
 export function formatActivityLine(event) {
     const invalid = invalidEventReason(event);
     if (invalid !== null)
@@ -156,7 +134,7 @@ export function formatActivityLine(event) {
 }
 /**
  * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
- * field-less blocks produce no message, which is what keeps them off stdout.
+ * field-less blocks produce no message, which is what keeps them out of the output.
  */
 export class SseParser {
     buffer = "";
@@ -198,21 +176,27 @@ function parseBlock(block) {
 /** Statuses that describe the moment, not the ticket — retry them. */
 const RETRYABLE_CLIENT_STATUSES = new Set([408, 429]);
 /**
- * Run until the dashboard ends the stream or the listener gives up. Returns the
- * exit code: 0 when a newer listener took over, 1 when revoked, refused, or
- * given up.
+ * Run until the dashboard ends the stream or the reader gives up, always ending
+ * with exactly one `stopped` record. Returns the exit code: 0 when a newer
+ * listener took over, 1 otherwise.
  */
 export async function runListener(options, deps) {
-    const printed = new Set();
+    const delivered = new Set();
     let lastEventId = null;
     let unhealthySince = null;
     let attempt = 0;
     const remember = (id) => {
-        printed.add(id);
-        if (printed.size > PRINTED_ID_MEMORY)
-            printed.delete(printed.values().next().value);
+        delivered.add(id);
+        if (delivered.size > DELIVERED_ID_MEMORY)
+            delivered.delete(delivered.values().next().value);
         lastEventId = lastEventId === null ? id : Math.max(lastEventId, id);
     };
+    for (const id of options.resumeIds.slice(-DELIVERED_ID_MEMORY))
+        remember(id);
+    const stop = (reason, detail, code) => {
+        deps.write({ type: "stopped", reason, detail });
+        return code;
+    };
     const handle = (message) => {
         if (message.event === "end") {
             const reason = JSON.parse(message.data).reason;
@@ -220,8 +204,11 @@ export async function runListener(options, deps) {
         }
         if (message.event !== "activity")
             return null;
-        const id = Number(message.id);
-        if (Number.isSafeInteger(id) && printed.has(id))
+        // `Number(null)` is 0, so a frame with no id must never be read as event 0: that id
+        // would become a `Last-Event-ID` the dashboard refuses, ending the listener.
+        const id = message.id === null ? Number.NaN : Number(message.id);
+        const knownId = Number.isSafeInteger(id) && id > 0;
+        if (knownId && delivered.has(id))
             return null;
         // DX-2735: an event that is not JSON, or JSON of the wrong shape, is reported
         // from an explicit check naming the fault — never from a TypeError thrown
@@ -236,16 +223,14 @@ export async function runListener(options, deps) {
         catch (err) {
             invalid = `not JSON: ${err.message}`;
         }
-        if (invalid === null) {
-            deps.write(formatActivityLine(parsed));
-        }
-        else {
-            deps.write(`${LINE_PREFIX} could not read event ${message.id ?? "(no id)"} (${invalid}): ` +
+        const text = invalid === null
+            ? formatActivityLine(parsed)
+            : `${LINE_PREFIX} could not read event ${message.id ?? "(no id)"} (${invalid}): ` +
                 // DX-2735: oneLine caps by code point, so a bad event carrying an emoji
                 // at the cut can never leave a lone surrogate in the line.
-                oneLine(message.data, 300));
-        }
-        if (Number.isSafeInteger(id))
+                oneLine(message.data, 300);
+        deps.write({ type: "event", id: knownId ? id : null, text });
+        if (knownId)
             remember(id);
         return null;
     };
@@ -263,8 +248,8 @@ export async function runListener(options, deps) {
         if (lastEventId !== null)
             headers["Last-Event-ID"] = String(lastEventId);
         const openedAt = deps.now();
-        let delivered = false;
-        const healthy = () => delivered || deps.now() - openedAt >= HEALTHY_CONNECTION_MS;
+        let gotEvent = false;
+        const healthy = () => gotEvent || deps.now() - openedAt >= HEALTHY_CONNECTION_MS;
         try {
             armIdle();
             const response = await deps.fetch(options.streamUrl, { headers, signal: controller.signal });
@@ -284,7 +269,7 @@ export async function runListener(options, deps) {
                     if (outcome !== null)
                         return outcome;
                     if (message.event === "activity")
-                        delivered = true;
+                        gotEvent = true;
                 }
             }
             return { kind: "dropped", healthy: healthy() };
@@ -301,16 +286,12 @@ export async function runListener(options, deps) {
         const outcome = await connectOnce();
         if (outcome.kind === "ended") {
             if (outcome.reason === "superseded" || outcome.reason === "replaced") {
-                deps.write(`${LINE_PREFIX} stopped: another listener for this session took over (${outcome.reason}). ` +
-                    `If you did not just call plan_connect, something else did — ${REARM}`);
-                return 0;
+                return stop(outcome.reason, "another listener for this session took over", 0);
             }
-            deps.write(`${LINE_PREFIX} stopped: the dashboard ended this listener (${outcome.reason}). ${REARM}`);
-            return 1;
+            return stop(outcome.reason, "the dashboard ended this listener", 1);
         }
         if (outcome.kind === "refused") {
-            deps.write(`${LINE_PREFIX} gave up: the dashboard refused the listener ticket (${outcome.detail}). ${REARM}`);
-            return 1;
+            return stop("refused", `the dashboard refused the listener ticket: ${outcome.detail}`, 1);
         }
         if (outcome.healthy) {
             unhealthySince = null;
@@ -319,31 +300,9 @@ export async function runListener(options, deps) {
         const now = deps.now();
         unhealthySince ??= now;
         if (now - unhealthySince >= options.leaseMs) {
-            deps.write(`${LINE_PREFIX} gave up: no healthy connection to ${options.streamUrl} for ` +
-                `${Math.round((now - unhealthySince) / 60_000)} minutes, past the ticket's lease. ${REARM}`);
-            return 1;
+            return stop("lease_expired", `no healthy connection to ${options.streamUrl} for ${Math.round((now - unhealthySince) / 60_000)} minutes, past the ticket's lease`, 1);
         }
         await deps.sleep(Math.min(MAX_BACKOFF_MS, INITIAL_BACKOFF_MS * 2 ** attempt));
         attempt += 1;
     }
 }
-/** The bin's `listen` subcommand, wired to the real process. */
-export async function runListenCommand(argv) {
-    let options;
-    try {
-        options = parseListenArgs(argv);
-    }
-    catch (err) {
-        process.stderr.write(`${err.message}\n`);
-        return 2;
-    }
-    return runListener(options, {
-        fetch,
-        write: (line) => {
-            process.stdout.write(`${line}\n`);
-        },
-        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-        now: Date.now,
-        readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
-    });
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.64",
+  "version": "0.1.66",
   "description": "Stdio MCP server wrapping danxbot's dashboard /api/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
   "license": "MIT",
   "type": "module",