@thehammer/danx-dashboard-mcp 0.1.65 → 0.1.67

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",
@@ -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; 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: 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.65",
+  "version": "0.1.67",
   "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",