@thehammer/danx-dashboard-mcp 0.1.52 → 0.1.53

package/README.md

@@ -33,6 +33,20 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set replaces step rows atomically; clear soft-deletes them. A successful set also returns `solutions_reminder: {solution_count, instruction}` |
 | `issue_retro` | `PUT /api/issues/:id/retro` | Requires terminal card; replace semantics |
 
+## `listen` — a working session's event listener
+
+`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.
+
+```bash
+npx -y @thehammer/danx-dashboard-mcp@<version> listen --stream <dashboard>/api/plan-sessions/stream --ticket <ticket> --lease-ms <ms>
+```
+
+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: chose "Pause E2E" — note: "only this week"`, `… 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.
+
 ## Build + test
 
 ```bash

package/dist/handlers.js

@@ -721,6 +721,39 @@ export async function planGet(client, args = {}) {
         basePath: PLANS_BASE_PATH,
     });
 }
+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
@@ -729,14 +762,51 @@ export async function planGet(client, args = {}) {
  *
  * 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.
  */
-export async function planConnect(client, args) {
-    return client.request({
+export async function planConnect(client, args, listener) {
+    const connected = await 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. */
 export async function planAddRecord(client, args) {

package/dist/index.js

@@ -74,8 +74,10 @@
  * 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 { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -161,6 +163,16 @@ 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",
@@ -619,8 +631,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}}`. `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). 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 one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture document, the sessions working on it, and your own session state. One call, not five. 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. Returns `{plan, cards, boards, records: {goal: [], rule: [], caveat: []}, architecture: {content, contentHash, updatedAt, updatedBy}, sessions, session}`. ALWAYS `plan_get` immediately before `plan_set_architecture` and pass the returned `architecture.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 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 one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture document, the sessions working on it, and your own session state. One call, not five. 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. Returns `{plan, cards, boards, records: {goal: [], rule: [], caveat: []}, architecture: {content, contentHash, updatedAt, updatedBy}, sessions, session, sessionListenerAttached}` — `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. ALWAYS `plan_get` immediately before `plan_set_architecture` and pass the returned `architecture.contentHash` back as `base_hash`.", {
     plan_id: z
         .number()
         .int()
@@ -631,9 +643,9 @@ server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — it
 server.tool("plan_create", "Create a new, empty plan via POST /api/plans (DX-2531). GLOBAL — a plan is not board-scoped, and this call adds no cards, no records, and no architecture document; it does NOT connect any session to the new plan (call `plan_connect` separately, exactly as adding a card to a plan is its own separate step). Returns `{ok, status, body: {plan: {id, name, createdAt}}}`. Use the returned `plan.id` with `plan_connect` to start working on it, or with `plan_get({plan_id})` to browse it.", {
     name: z.string().min(1).describe("The plan's name — shown in the Plans list."),
 }, async (args) => jsonResult(await planCreate(client, args)));
-server.tool("plan_connect", "Connect THIS session to a plan via POST /api/plan-sessions/me/plan (DX-2683) — the same binding the operator's Connect action writes, through the same server-side path. A session is connected to AT MOST ONE plan (enforced by the schema, not by convention); connecting while already on another plan MOVES you, and the response says which plan you left: `{ok, status, body: {session, movedFrom: {id, name} | null}}`. `movedFrom: null` means you were on no plan, or already on this one. It can only ever bind your OWN session — `me` is resolved from the session id this server forwards, never from anything you pass. After this, every plan WRITE tool acts on this plan, and no plan id is accepted anywhere.", {
+server.tool("plan_connect", "Connect THIS session to a plan via POST /api/plan-sessions/me/plan (DX-2683) — the same binding the operator's Connect action writes, through the same server-side path. A session is connected to AT MOST ONE plan (enforced by the schema, not by convention); connecting while already on another plan MOVES you, and the response says which plan you left: `{ok, status, body: {session, movedFrom: {id, name} | null}}`. `movedFrom: null` means you were on no plan, or already on this one. It can only ever bind your OWN session — `me` is resolved from the session id this server forwards, never from anything you pass. After this, every plan WRITE tool acts on this plan, and no plan id is accepted anywhere. THE REPLY ALSO CARRIES `listener: {command, persistent: true, instruction}` — arm it IMMEDIATELY with the Monitor tool (`command` as given, `persistent: true`): from then on every comment, answer, requires_human change and block/unblock on this plan's cards arrives as a notification line like `[DX-8 \"Title\" repo:board] newms87 answered: chose \"Pause E2E\" — note: \"…\"`. Never poll for these. The command carries a narrow stream ticket, not a credential; calling plan_connect again (same plan is fine) issues a new one and ends the old listener, which is how you re-arm after a session restart or after the Monitor reports it gave up. If the ticket cannot be issued the call fails with `listener_not_armed` even though the connect itself happened.", {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
-}, async (args) => jsonResult(await planConnect(client, args)));
+}, async (args) => jsonResult(await planConnect(client, args, { baseUrl: config.baseUrl, packageSpec: PACKAGE_SPEC })));
 server.tool("plan_add_record", "Add a GOAL, RULE or CAVEAT to the plan this session is connected to, via POST /api/plans/mine/records (DX-2683). A goal is what the plan is FOR (the outcome the work is measured against — not a task). A rule is what must HOLD while it is worked. A caveat is what is known to be AWKWARD — the fact that will surprise the next person. Each gets a permanent short reference within the plan (`G-1`, `R-4`, `CAV-12`) allocated by the server, which is how a person cites it in a card or a commit. TAKES NO PLAN ID: the plan is resolved from your connected session, so you cannot write a plan you are not connected to. Not connected → `{error: \"session_not_connected\"}`; call `plan_connect` first. Returns the new record plus that kind's full list.", {
     kind: z
         .enum(["goal", "rule", "caveat"])
@@ -678,9 +690,28 @@ async function main() {
 // schemas can be introspected without spawning a dispatch. The check is
 // 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.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
-    main().catch((err) => {
-        console.error(`[danx-dashboard-mcp] fatal: ${err.message}`);
-        process.exit(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}`);
+            process.exit(1);
+        });
+    }
+    else if (subcommand !== undefined) {
+        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is "${LISTEN_SUBCOMMAND}")`);
+        process.exit(2);
+    }
+    else {
+        main().catch((err) => {
+            console.error(`[danx-dashboard-mcp] fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
 }

package/dist/listen.js

@@ -0,0 +1,278 @@
+/**
+ * `danx-dashboard-mcp listen --stream <url> --ticket <ticket> --lease-ms <ms>` —
+ * a working session's event listener.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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;
+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 ? "…" : ""}"`;
+}
+function describe(event) {
+    const d = event.detail;
+    switch (event.kind) {
+        case "comment_added":
+            return `${event.actor} commented: ${quoted(d.excerpt)}`;
+        case "solution_answered": {
+            const solution = d.solution;
+            if (solution === null)
+                return `${event.actor} answered: ${quoted(d.freeform)}`;
+            const note = solution.note === null ? "" : ` — note: ${quoted(solution.note)}`;
+            return `${event.actor} answered: chose "${solution.title}"${note}`;
+        }
+        case "requires_human_set":
+            return `${event.actor} set requires_human: ${quoted(d.reason)}`;
+        case "requires_human_cleared":
+            return `${event.actor} cleared requires_human`;
+        case "blocked":
+            return `${event.actor} blocked the card: ${quoted(d.reason)}`;
+        case "unblocked":
+            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.
+            return `${event.actor}: ${event.kind}`;
+    }
+}
+/** The one notification line for an event. Always a single line; throws on a malformed event. */
+export function formatActivityLine(event) {
+    return `[${event.cardId} "${event.cardTitle}" ${event.boardId}] ${describe(event)}`.replace(/\s+/g, " ");
+}
+/**
+ * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
+ * field-less blocks produce no message, which is what keeps them off stdout.
+ */
+export class SseParser {
+    buffer = "";
+    push(chunk) {
+        this.buffer += chunk.replace(/\r\n?/g, "\n");
+        const messages = [];
+        let boundary = this.buffer.indexOf("\n\n");
+        while (boundary !== -1) {
+            const message = parseBlock(this.buffer.slice(0, boundary));
+            this.buffer = this.buffer.slice(boundary + 2);
+            if (message !== null)
+                messages.push(message);
+            boundary = this.buffer.indexOf("\n\n");
+        }
+        return messages;
+    }
+}
+function parseBlock(block) {
+    let id = null;
+    let event = "message";
+    const data = [];
+    let sawField = false;
+    for (const line of block.split("\n")) {
+        if (line === "" || line.startsWith(":"))
+            continue;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        const value = colon === -1 ? "" : line.slice(colon + 1).replace(/^ /, "");
+        sawField = true;
+        if (field === "id")
+            id = value;
+        else if (field === "event")
+            event = value;
+        else if (field === "data")
+            data.push(value);
+    }
+    return sawField ? { id, event, data: data.join("\n") } : null;
+}
+/** 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.
+ */
+export async function runListener(options, deps) {
+    const printed = 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);
+        lastEventId = lastEventId === null ? id : Math.max(lastEventId, id);
+    };
+    const handle = (message) => {
+        if (message.event === "end") {
+            const reason = JSON.parse(message.data).reason;
+            return { kind: "ended", reason: typeof reason === "string" ? reason : "unknown" };
+        }
+        if (message.event !== "activity")
+            return null;
+        const id = Number(message.id);
+        if (Number.isSafeInteger(id) && printed.has(id))
+            return null;
+        try {
+            deps.write(formatActivityLine(JSON.parse(message.data)));
+        }
+        catch (err) {
+            // Never silence, and never a reconnect loop on the same bad event: say so
+            // in one line and move past it.
+            deps.write(`${LINE_PREFIX} could not read event ${message.id ?? "(no id)"} (${err.message}): ` +
+                `${message.data.slice(0, 300)}`.replace(/\s+/g, " "));
+        }
+        if (Number.isSafeInteger(id))
+            remember(id);
+        return null;
+    };
+    const connectOnce = async () => {
+        const controller = new AbortController();
+        let idle;
+        const armIdle = () => {
+            clearTimeout(idle);
+            idle = setTimeout(() => controller.abort(), deps.readIdleTimeoutMs);
+        };
+        const headers = {
+            Authorization: `Bearer ${options.ticket}`,
+            Accept: "text/event-stream",
+        };
+        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;
+        try {
+            armIdle();
+            const response = await deps.fetch(options.streamUrl, { headers, signal: controller.signal });
+            if (response.status >= 400 && response.status < 500 && !RETRYABLE_CLIENT_STATUSES.has(response.status)) {
+                return { kind: "refused", detail: `HTTP ${response.status} ${(await response.text()).slice(0, 300)}` };
+            }
+            if (!response.ok || response.body === null) {
+                await response.body?.cancel();
+                return { kind: "dropped", healthy: false };
+            }
+            const parser = new SseParser();
+            const decoder = new TextDecoder();
+            for await (const chunk of response.body) {
+                armIdle();
+                for (const message of parser.push(decoder.decode(chunk, { stream: true }))) {
+                    const outcome = handle(message);
+                    if (outcome !== null)
+                        return outcome;
+                    if (message.event === "activity")
+                        delivered = true;
+                }
+            }
+            return { kind: "dropped", healthy: healthy() };
+        }
+        catch {
+            return { kind: "dropped", healthy: healthy() };
+        }
+        finally {
+            clearTimeout(idle);
+            controller.abort();
+        }
+    };
+    for (;;) {
+        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;
+            }
+            deps.write(`${LINE_PREFIX} stopped: the dashboard ended this listener (${outcome.reason}). ${REARM}`);
+            return 1;
+        }
+        if (outcome.kind === "refused") {
+            deps.write(`${LINE_PREFIX} gave up: the dashboard refused the listener ticket (${outcome.detail}). ${REARM}`);
+            return 1;
+        }
+        if (outcome.healthy) {
+            unhealthySince = null;
+            attempt = 0;
+        }
+        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;
+        }
+        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.52",
+  "version": "0.1.53",
   "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",