@thehammer/danx-dashboard-mcp 0.1.75 → 0.1.76

package/README.md

@@ -9,7 +9,7 @@ Each tool is a thin envelope over one HTTP route — Zod-validated at the MCP bo
 | Var | Purpose |
 |---|---|
 | `DANXBOT_DASHBOARD_URL` | Dashboard base, e.g. `http://danxbot-dashboard:5555` (inside compose) or `http://localhost:5555` (host) |
-| `DANXBOT_DISPATCH_TOKEN` | Per-dispatch bearer — server validates via `requireUser`/dispatch-token checks |
+| `DANXBOT_DASHBOARD_TOKEN_FILE` **or** `DANXBOT_DISPATCH_TOKEN` | The credential, declared exactly one of two ways (DX-2862, `src/credential.ts`). A FILE holding the bearer (a leading `~` is the user's home) — how an interactive operator session declares one, since its `.mcp.json` is git-tracked and can never carry the token itself. Or the bearer VERBATIM — how a dispatch declares one, substituted from its overlay. A declared file is AUTHORITATIVE and its failure is FATAL: an inherited `DANXBOT_DISPATCH_TOKEN` is never consulted instead, because on an operator machine that value routinely names a different (local-dev) dashboard, which answers healthily and empty. The same resolver serves the `bridge` subcommand below, so a session's tools and its event stream can never sign in as two different identities |
 | `DANX_REPO_NAME` | Repo half of the qualified board id |
 | `DANXBOT_BOARD_NAME` | Board-slug half of the qualified board id (the dispatch injects `board.slug` here) |
 
@@ -56,11 +56,12 @@ Evaluated in that order (`complete` > `awaiting-session` > `building` > `plannin
 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
-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>,...]
+CLAUDE_CODE_SESSION_ID=<session> npx -y @thehammer/danx-dashboard-mcp@<version> bridge [--resume-ids <id>,<id>,...]
 ```
 
-- **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.
+- **Credential — the session's own, never the ambient one (DX-2862).** The session id is the only thing `bridge` takes from its environment; `--resume-ids` is the only argument and holds no secret. Everything else comes from the connection record this session's own danx-dashboard MCP server wrote on `plan_connect` (`src/session-connection.ts`): the dashboard URL, the credential's SOURCE, and its FINGERPRINT. `bridge` resolves that source through the same resolver the server used and refuses to run unless the result fingerprints identically — `credential_mismatch`. Before that fix it used whatever `DANXBOT_DISPATCH_TOKEN` the session's environment held, and on a machine where that differed from the server's credential the dashboard admitted the stream and dropped every event, with nothing logged anywhere.
+- **Reach check.** After minting, `bridge` proves the credential can read every board the connected plan's cards live on (`GET /api/plans/mine?fields=cards`, then `GET /api/issues/:id/problems` for one card per board — the routes that run the same board-allowlist + `read` check the stream itself applies). A board it cannot read stops it with `board_unreadable` rather than streaming on and dropping that board's events. Then, once, `{"type":"ready","boards":[…]}`.
+- **Ticket.** `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: "…"`, `… opened a problem: "…"`, `… 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.

package/dist/bridge.js

@@ -5,106 +5,193 @@
  * 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.
+ * each event (and each failure) 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.
+ *   1. Reads `CLAUDE_CODE_SESSION_ID` from its environment and, for that
+ *      session, the connection record the session's own MCP server wrote when
+ *      it connected the plan (`session-connection.ts`): the dashboard URL, the
+ *      credential's SOURCE, and the credential's FINGERPRINT.
+ *   2. Resolves that same source through the same resolver the server used
+ *      (`credential.ts`) and refuses to run unless the result fingerprints
+ *      identically — DX-2862, where a bridge authenticated with a DIFFERENT
+ *      credential from its session's tools streamed happily and relayed nothing.
+ *   3. Mints the session's listener ticket (`POST /api/plan-sessions/me/stream-ticket`).
+ *      The ticket stays in this process.
+ *   4. VERIFIES THE REACH IT JUST BOUGHT: the credential must be able to read
+ *      every board the connected plan's cards live on, because the stream admits
+ *      an event only when the ticket issuer's board allowlist covers that
+ *      event's board (`isVisibleToStream`, dashboard). A board it cannot read is
+ *      a board whose events would vanish without a word, so it is a terminal,
+ *      named outcome instead.
+ *   5. 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.
+ *   6. Writes JSON Lines to stdout: ONE `{type:"ready", boards}` once the stream
+ *      is live and verified, `{type:"event", id, text}` per event, and ONE final
+ *      `{type:"stopped", reason, detail, fix}` 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;
+ *   - `no_connection_record`  this session has no connection record to read;
+ *   - `credential_unavailable` its declared credential cannot be resolved here;
+ *   - `credential_mismatch`   what resolved is not the server's credential;
+ *   - `not_connected`         the mint answered 409 `session_not_connected`;
+ *   - `unauthorized`          the mint or a scope read 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;
+ *   - `board_unreadable`      the credential cannot read a board of this plan;
+ *   - `scope_check_failed`    the plan's boards could not be established;
  *   - `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
+ *   - `revoked`               the dashboard revoked the ticket or its issuer;
+ *   - `refused`               freshly minted tickets were refused twice in a row.
+ * Transient 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.
+ * NEITHER THE ENVIRONMENT NOR ARGV CARRIES THE CREDENTIAL ANY MORE. `--resume-ids`
+ * is the only argument and holds no secret; the credential is whatever this
+ * session's own MCP server declared, resolved here from that declaration.
  */
+import { homedir } from "node:os";
 import { oneLine } from "./one-line.js";
+import { credentialFingerprint, describeCredentialSource, readCredential, } from "./credential.js";
+import { readSessionConnection } from "./session-connection.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 PLAN_MINE_PATH = "/api/plans/mine";
+export const ISSUES_PATH = "/api/issues";
 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;
+/** How long one dashboard request may take before it counts as a transient failure. */
+export const REQUEST_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;
+/** One page of the connected plan's cards, for the board-reach check. The server's ceiling. */
+export const PLAN_CARDS_PAGE_SIZE = 1_000;
 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>...]]`;
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BRIDGE_SUBCOMMAND} ` +
+    `[--resume-ids <event-id>[,<event-id>...]]`;
+/**
+ * The remedy per terminal reason. ONE map, so the message a session is shown and
+ * the message a log carries can never drift, and a new reason without a remedy
+ * is a compile-visible omission rather than a silent blank.
+ */
+export const STOP_FIXES = {
+    no_connection_record: "call plan_connect again in this session — its danx-dashboard MCP server records the connection the bridge needs " +
+        "(a server older than the one that introduced the record writes none)",
+    credential_unavailable: "fix the credential this session's danx-dashboard MCP server declares, then call plan_connect again",
+    credential_mismatch: "restart this Claude Code session so its MCP server and its bridge pick up the same credential, then call plan_connect again",
+    not_connected: "call plan_connect to connect this session to a plan",
+    unauthorized: "give this session's danx-dashboard MCP server a dashboard credential that is accepted, then call plan_connect again",
+    mint_refused: "check that this session is connected to a plan on the dashboard its MCP server points at, then call plan_connect again",
+    mint_bad_response: "check that DANXBOT_DASHBOARD_URL for this session's MCP server points at a danxbot dashboard",
+    board_unreadable: "scope this session's dashboard credential to read that board, or connect a plan whose cards all live on boards it can read",
+    scope_check_failed: "check the dashboard is reachable and this session is connected to a plan, then call plan_connect again",
+    revoked: "call plan_connect again to mint a new listener ticket for this session",
+    refused: "call plan_connect again to mint a new listener ticket for this session",
+};
+export const DEFAULT_STOP_FIX = "call plan_connect again in this session to restart the bridge";
+export function fixForStop(reason) {
+    return STOP_FIXES[reason] ?? DEFAULT_STOP_FIX;
+}
 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. */
+/** Parse the one optional flag and the one required environment value; 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)
+    if (!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 };
+    return { sessionId, resumeIds: resumeIds };
+}
+/** A start this process cannot make, named the way the session will be told about it. */
+export class BridgeStartError extends Error {
+    reason;
+    fix;
+    constructor(reason, detail, fix) {
+        super(detail);
+        this.name = "BridgeStartError";
+        this.reason = reason;
+        this.fix = fix;
+    }
+}
+/**
+ * The session's connection, as its own MCP server recorded it — and the proof
+ * that this process holds the SAME credential that server does. Never falls back
+ * to an ambient `DANXBOT_DISPATCH_TOKEN`: that fallback is precisely DX-2862.
+ */
+export function resolveBridgeOptions(args, env, options = {}) {
+    const home = options.home ?? homedir();
+    let record;
+    try {
+        record = readSessionConnection(args.sessionId, { home });
+    }
+    catch (err) {
+        throw new BridgeStartError("no_connection_record", err.message, fixForStop("no_connection_record"));
+    }
+    if (record === null) {
+        throw new BridgeStartError("no_connection_record", `session ${args.sessionId} has no dashboard connection record — no danx-dashboard MCP server has connected it to a plan`, fixForStop("no_connection_record"));
+    }
+    let token;
+    try {
+        token = readCredential(record.source, env);
+    }
+    catch (err) {
+        const credentialError = err;
+        throw new BridgeStartError("credential_unavailable", `the credential this session's danx-dashboard MCP server declared cannot be resolved here: ${credentialError.message}`, credentialError.fix ?? fixForStop("credential_unavailable"));
+    }
+    const fingerprint = credentialFingerprint(token);
+    if (fingerprint !== record.fingerprint) {
+        throw new BridgeStartError("credential_mismatch", `${describeCredentialSource(record.source)} now yields credential ${fingerprint}, but this session's ` +
+            `danx-dashboard MCP server is using ${record.fingerprint} — the bridge would authenticate as somebody else`, fixForStop("credential_mismatch"));
+    }
+    return {
+        dashboardUrl: record.dashboardUrl.replace(/\/+$/, ""),
+        token,
+        sessionId: args.sessionId,
+        resumeIds: args.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) {
+/**
+ * One authenticated request, with a timeout, classifying the failures that are
+ * about THIS MOMENT (network, timeout, 408/429, 5xx) as transient. Shared by the
+ * mint and the board-reach check so the two can never disagree about which
+ * failures are worth retrying.
+ */
+async function request(options, deps, what, url, init = { method: "GET" }) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), deps.mintTimeoutMs);
+    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
     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: "{}",
+            const headers = {
+                Authorization: `Bearer ${options.token}`,
+                Accept: "application/json",
+                [SESSION_ID_HEADER]: options.sessionId,
+            };
+            if (init.body !== undefined)
+                headers["Content-Type"] = "application/json";
+            const response = await deps.fetch(url, {
+                method: init.method,
+                headers,
+                body: init.body,
                 signal: controller.signal,
             });
             status = response.status;
@@ -114,12 +201,12 @@ export async function mintTicket(options, deps) {
             return {
                 kind: "transient",
                 detail: controller.signal.aborted
-                    ? `ticket mint timed out after ${deps.mintTimeoutMs} ms`
-                    : `ticket mint failed: ${err.message}`,
+                    ? `${what} timed out after ${deps.requestTimeoutMs} ms`
+                    : `${what} failed: ${err.message}`,
             };
         }
         if (status >= 500 || TRANSIENT_CLIENT_STATUSES.has(status)) {
-            return { kind: "transient", detail: `ticket mint HTTP ${status}` };
+            return { kind: "transient", detail: `${what} HTTP ${status}` };
         }
         let body = null;
         try {
@@ -128,43 +215,168 @@ export async function mintTicket(options, deps) {
         catch {
             body = null;
         }
+        return { kind: "answer", status, text, body };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** 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 outcome = await request(options, deps, "ticket mint", `${options.dashboardUrl}${STREAM_TICKET_PATH}`, {
+        method: "POST",
+        body: "{}",
+    });
+    if (outcome.kind === "transient")
+        return outcome;
+    const { status, text, body } = outcome;
+    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,
+    };
+}
+/** One card per board of the connected plan, read a page at a time. */
+function cardsPageOf(body) {
+    if (typeof body !== "object" || body === null)
+        return "the body is not a JSON object";
+    const b = body;
+    if (!Array.isArray(b.cards))
+        return "cards is not an array";
+    if (typeof b.cards_total !== "number" || !Number.isSafeInteger(b.cards_total))
+        return "cards_total is not an integer";
+    const cards = [];
+    for (const card of b.cards) {
+        if (typeof card !== "object" || card === null)
+            return "a card is not an object";
+        const c = card;
+        if (typeof c.id !== "string" || typeof c.boardId !== "string")
+            return "a card has no id / boardId";
+        cards.push({ id: c.id, boardId: c.boardId });
+    }
+    return { cards, total: b.cards_total };
+}
+/**
+ * Prove this credential can read every board the connected plan's cards live on.
+ *
+ * WHY THIS EXISTS AT ALL. The stream admits an event only when the ticket
+ * issuer's board allowlist covers the event's board and the issuer still holds
+ * `read` (`isVisibleToStream` / `resolveIssuerScope`, dashboard). A credential
+ * short of that streams exactly as happily as a correct one and simply never
+ * relays those boards' events — silence that looks identical to "nothing has
+ * happened yet".
+ *
+ * WHY THESE TWO ROUTES. `GET /api/plans/mine?fields=cards` is the only read that
+ * names the connected plan's cards, and `GET /api/issues/:id/problems` is a card
+ * read that runs the SAME board-allowlist + `read` check the stream does
+ * (`withV2Handler` + `resolveIssueBoardId`). Deliberately NOT `GET /api/issues`
+ * or `GET /api/issues/:id`: neither checks the caller's board allowlist at all,
+ * so a check built on them would pass precisely where the stream drops events.
+ */
+export async function verifyPlanBoardsReadable(options, deps) {
+    const firstCardPerBoard = new Map();
+    let offset = 0;
+    for (;;) {
+        const url = `${options.dashboardUrl}${PLAN_MINE_PATH}?fields=cards&cards_limit=${PLAN_CARDS_PAGE_SIZE}&cards_offset=${offset}`;
+        const outcome = await request(options, deps, "plan read", url);
+        if (outcome.kind === "transient")
+            return outcome;
+        const { status, text, body } = outcome;
         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)}` };
+            return { kind: "terminal", reason: "unauthorized", detail: `plan read HTTP ${status} ${oneLine(text, 300)}` };
         }
         if (status < 200 || status >= 300) {
-            return { kind: "terminal", reason: "mint_refused", detail: `ticket mint HTTP ${status} ${oneLine(text, 300)}` };
+            return { kind: "terminal", reason: "scope_check_failed", detail: `plan read 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 page = cardsPageOf(body);
+        if (typeof page === "string") {
+            return { kind: "terminal", reason: "scope_check_failed", detail: `plan read HTTP ${status}: ${page}` };
         }
-        const ticket = body;
-        return {
-            kind: "ticket",
-            ticket: ticket.ticket,
-            streamUrl: `${options.dashboardUrl}${ticket.streamPath}`,
-            leaseMs: ticket.leaseMs,
-        };
+        for (const card of page.cards) {
+            if (!firstCardPerBoard.has(card.boardId))
+                firstCardPerBoard.set(card.boardId, card.id);
+        }
+        offset += page.cards.length;
+        if (page.cards.length === 0 || offset >= page.total)
+            break;
     }
-    finally {
-        clearTimeout(timer);
+    for (const [boardId, cardId] of firstCardPerBoard) {
+        const url = `${options.dashboardUrl}${ISSUES_PATH}/${encodeURIComponent(cardId)}/problems?board=${encodeURIComponent(boardId)}`;
+        const outcome = await request(options, deps, `board read of ${boardId}`, url);
+        if (outcome.kind === "transient")
+            return outcome;
+        const { status, text } = outcome;
+        if (status === 403) {
+            return {
+                kind: "terminal",
+                reason: "board_unreadable",
+                detail: `this session's dashboard credential cannot read board ${boardId}, which the connected plan's card ` +
+                    `${cardId} lives on — the event stream drops that board's events silently (${oneLine(text, 200)})`,
+            };
+        }
+        if (status === 401) {
+            return { kind: "terminal", reason: "unauthorized", detail: `board read of ${boardId} HTTP 401 ${oneLine(text, 200)}` };
+        }
+        if (status === 404) {
+            // The card moved or was deleted between the two reads. Nothing is wrong
+            // with the credential — re-read the plan rather than accuse it.
+            return { kind: "transient", detail: `card ${cardId} vanished between the plan read and the board read` };
+        }
+        if (status < 200 || status >= 300) {
+            return {
+                kind: "terminal",
+                reason: "scope_check_failed",
+                detail: `board read of ${boardId} HTTP ${status} ${oneLine(text, 200)}`,
+            };
+        }
     }
+    return { kind: "ok", boards: [...firstCardPerBoard.keys()] };
 }
 /**
- * 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.
+ * Mint, verify, 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 });
+        deps.write({ type: "stopped", reason, detail, fix: fixForStop(reason) });
         return code;
     };
     let backoff = MINT_INITIAL_BACKOFF_MS;
     let refusedInRow = 0;
+    let verified = false;
     for (;;) {
         const minted = await mintTicket(options, deps);
         if (minted.kind === "terminal")
@@ -174,6 +386,20 @@ export async function runBridge(options, deps) {
             backoff = Math.min(MINT_MAX_BACKOFF_MS, backoff * 2);
             continue;
         }
+        // The reach check runs on the FIRST ticket only: it is a property of the
+        // credential and the plan, and a re-mint (a lapsed lease) changes neither.
+        if (!verified) {
+            const scope = await verifyPlanBoardsReadable(options, deps);
+            if (scope.kind === "terminal")
+                return stop(scope.reason, scope.detail, 1);
+            if (scope.kind === "transient") {
+                await deps.sleep(backoff);
+                backoff = Math.min(MINT_MAX_BACKOFF_MS, backoff * 2);
+                continue;
+            }
+            verified = true;
+            deps.write({ type: "ready", boards: scope.boards });
+        }
         backoff = MINT_INITIAL_BACKOFF_MS;
         const run = { stopped: null, emitted: false };
         const startedAt = deps.now();
@@ -214,23 +440,40 @@ export async function runBridge(options, deps) {
     }
 }
 /** The bin's `bridge` subcommand, wired to the real process. */
-export async function runBridgeCommand(argv, env = process.env) {
-    let options;
+export async function runBridgeCommand(argv, env = process.env, 
+/** Test seam: the home the session's connection record is read from. */
+resolveFrom = {}) {
+    const write = (output) => {
+        process.stdout.write(`${JSON.stringify(output)}\n`);
+    };
+    let args;
     try {
-        options = parseBridgeArgs(argv, env);
+        args = parseBridgeArgs(argv, env);
     }
     catch (err) {
         process.stderr.write(`${err.message}\n`);
         return 2;
     }
+    let options;
+    try {
+        options = resolveBridgeOptions(args, env, resolveFrom);
+    }
+    catch (err) {
+        const start = err;
+        // A start that never happened still reports itself the way every other
+        // terminal outcome does — one stop record the plugin relays into the
+        // session — AND on stderr, for the case where there is no session to relay
+        // into (a hand run).
+        write({ type: "stopped", reason: start.reason, detail: start.message, fix: start.fix });
+        process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
+        return 1;
+    }
     return runBridge(options, {
         fetch: (input, init) => fetch(input, init),
-        write: (output) => {
-            process.stdout.write(`${JSON.stringify(output)}\n`);
-        },
+        write,
         sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
         now: Date.now,
         readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
-        mintTimeoutMs: MINT_TIMEOUT_MS,
+        requestTimeoutMs: REQUEST_TIMEOUT_MS,
     });
 }

package/dist/credential.js

@@ -0,0 +1,125 @@
+/**
+ * DX-2862 — the ONE resolver for this package's dashboard credential.
+ *
+ * WHY IT IS ONE FUNCTION AND NOT TWO. Two processes speak to the dashboard for
+ * the same Claude Code session: the MCP SERVER (the session's card + plan tools)
+ * and `danx-dashboard-mcp bridge` (the session's event stream, run by the
+ * danxbot plugin's plan event bridge). Before this module they resolved their
+ * credential independently — the server through danxbot's operator launcher,
+ * which read a token file, and the bridge from whatever `DANXBOT_DISPATCH_TOKEN`
+ * happened to be in the session's environment. On a machine where those two
+ * differ (DX-2862: `ffe9f8a882f0…` in the environment, `6f9bc6e94b83…` in
+ * `~/.config/danxbot/dashboard-token-gpt`) the session's tools worked, the
+ * bridge's stream was admitted, and every operator comment was dropped with no
+ * error anywhere. So resolution lives HERE, both callers go through it, and the
+ * bridge additionally PROVES it holds the server's credential by comparing
+ * fingerprints (`session-connection.ts`).
+ *
+ * THE DECLARATION. A server's env declares where its credential comes from:
+ *
+ *   - `DANXBOT_DASHBOARD_TOKEN_FILE` — a path (a leading `~` is this user's
+ *     home). The file's trimmed contents are the credential. This is how an
+ *     interactive operator session declares one, because its `.mcp.json` is
+ *     git-tracked and can never carry the bearer itself.
+ *   - `DANXBOT_DISPATCH_TOKEN` — the credential verbatim. This is how a
+ *     DISPATCH declares one: the worker substitutes it into the materialized
+ *     `.mcp.json` from the dispatch overlay.
+ *
+ * A DECLARED FILE IS AUTHORITATIVE, AND ITS FAILURE IS FATAL. When the file
+ * variable is set, `DANXBOT_DISPATCH_TOKEN` is never consulted — not even when
+ * the file is missing or empty. That is the DX-2483 rule, moved here from the
+ * launcher it used to live in: an operator machine routinely carries an
+ * inherited `DANXBOT_DISPATCH_TOKEN` naming the LOCAL dev dashboard, which
+ * answers healthily and empty for a board it does not carry, so preferring it
+ * after a failed file read would turn a loud, fixable error into exactly the
+ * silent wrong-dashboard answer this whole module exists to prevent.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+export const CREDENTIAL_FILE_ENV = "DANXBOT_DASHBOARD_TOKEN_FILE";
+export const CREDENTIAL_TOKEN_ENV = "DANXBOT_DISPATCH_TOKEN";
+/**
+ * A credential that cannot be resolved. Carries the remedy beside the reason,
+ * because both of this module's callers report failures to a human who is not
+ * reading a log: the server exits with it on stderr, and the bridge posts it
+ * into the session's inbox.
+ */
+export class CredentialError extends Error {
+    fix;
+    constructor(detail, fix) {
+        super(detail);
+        this.name = "CredentialError";
+        this.fix = fix;
+    }
+}
+const DECLARE_ONE = `declare the credential in this MCP server's env: ${CREDENTIAL_FILE_ENV}=<path to a file holding the ` +
+    `dashboard bearer> (an operator session), or ${CREDENTIAL_TOKEN_ENV}=<the bearer> (a dispatch)`;
+/** `~` / `~/x` / `~\x` mean this user's home; every other path is returned as given. */
+export function expandHome(path, home = homedir()) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/") || path.startsWith("~\\"))
+        return join(home, path.slice(2));
+    return path;
+}
+function readEnv(env, name) {
+    const value = env[name];
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+/**
+ * WHICH source this environment declares. Throws `CredentialError` when it
+ * declares none — never a guess, and never an anonymous client.
+ */
+export function declaredCredentialSource(env, home = homedir()) {
+    const file = readEnv(env, CREDENTIAL_FILE_ENV);
+    if (file !== null) {
+        const expanded = expandHome(file, home);
+        return { kind: "file", path: isAbsolute(expanded) ? expanded : resolve(expanded) };
+    }
+    if (readEnv(env, CREDENTIAL_TOKEN_ENV) !== null)
+        return { kind: "env", name: CREDENTIAL_TOKEN_ENV };
+    throw new CredentialError(`no dashboard credential is declared (neither ${CREDENTIAL_FILE_ENV} nor ${CREDENTIAL_TOKEN_ENV} is set)`, DECLARE_ONE);
+}
+/** One line naming a source, for a message a human reads. Holds no secret. */
+export function describeCredentialSource(source) {
+    return source.kind === "file" ? `the token file ${source.path}` : `the environment variable ${source.name}`;
+}
+/** The credential a source yields. Every failure is fatal and named. */
+export function readCredential(source, env) {
+    if (source.kind === "env") {
+        const token = readEnv(env, source.name);
+        if (token === null) {
+            throw new CredentialError(`${describeCredentialSource(source)} is unset or empty in this process`, `set ${source.name} for this process, or declare ${CREDENTIAL_FILE_ENV} instead`);
+        }
+        return token;
+    }
+    let contents;
+    try {
+        contents = readFileSync(source.path, "utf-8");
+    }
+    catch (err) {
+        throw new CredentialError(`cannot read ${describeCredentialSource(source)}: ${err.message}`, `create that file holding this dashboard's bearer token, or point ${CREDENTIAL_FILE_ENV} at one that exists`);
+    }
+    const token = contents.trim();
+    if (token === "") {
+        throw new CredentialError(`${describeCredentialSource(source)} is empty`, `write this dashboard's bearer token into that file`);
+    }
+    return token;
+}
+/**
+ * A credential's IDENTITY, for comparing two processes' credentials without
+ * either of them handling the other's. The first 12 hex of SHA-256 — 48 bits,
+ * enough that two distinct 48-character tokens colliding is not a thing that
+ * happens, and nothing an attacker can invert.
+ */
+export function credentialFingerprint(token) {
+    return createHash("sha256").update(token).digest("hex").slice(0, 12);
+}
+/** Declare, read, fingerprint — what the MCP server does at boot. */
+export function resolveDeclaredCredential(env, home = homedir()) {
+    const source = declaredCredentialSource(env, home);
+    const token = readCredential(source, env);
+    return { source, token, fingerprint: credentialFingerprint(token) };
+}

package/dist/index.js

@@ -69,7 +69,15 @@
  *
  * Env at boot (validated fail-loud — missing → process.exit(1)):
  *   DANXBOT_DASHBOARD_URL   dashboard base (e.g. http://danxbot-dashboard:5555)
- *   DANXBOT_DISPATCH_TOKEN  per-dispatch bearer
+ *   the CREDENTIAL, declared exactly one of two ways and resolved by the ONE
+ *   resolver this package's event bridge also uses (`credential.ts`, DX-2862):
+ *     DANXBOT_DASHBOARD_TOKEN_FILE  a file holding the bearer (an operator
+ *                           session, whose `.mcp.json` is git-tracked and so
+ *                           can never carry one); authoritative when set, and
+ *                           its failure is fatal — an inherited
+ *                           DANXBOT_DISPATCH_TOKEN is never consulted instead
+ *     DANXBOT_DISPATCH_TOKEN  the bearer verbatim (a dispatch, substituted into
+ *                           the materialized `.mcp.json` from its overlay)
  *   DANX_REPO_NAME          repo half of the qualified board id
  *   DANXBOT_BOARD_NAME      board-slug half of the qualified board id
  *                           (the dispatch injects `board.slug` here);
@@ -86,6 +94,8 @@
  */
 import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
+import { resolveDeclaredCredential } from "./credential.js";
+import { recordSessionConnectionAfterConnect } from "./session-connection.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -119,6 +129,13 @@ function readEnvOptional(name) {
 // while a real run still fails loud on missing env via `boot()`.
 let config;
 let client;
+/**
+ * DX-2862 — what this server would tell the session's plan event bridge about
+ * how to reach the dashboard AS THIS SERVER: the URL, where the credential came
+ * from, and the credential's fingerprint. Never the credential itself. Written
+ * to the session's connection record on a successful `plan_connect`.
+ */
+let connection;
 /**
  * Compose the dispatch's qualified board id (`<repo>:<slug>`) from the two env
  * halves the worker injects and build the HTTP client. DANXBOT_BOARD_NAME
@@ -127,9 +144,10 @@ let client;
  * Both halves are fail-loud required (Core Principle 1 — no fallback).
  */
 function boot() {
+    const credential = resolveCredentialOrDie();
     config = {
         baseUrl: readEnvOrDie("DANXBOT_DASHBOARD_URL"),
-        token: readEnvOrDie("DANXBOT_DISPATCH_TOKEN"),
+        token: credential.token,
         board: `${readEnvOrDie("DANX_REPO_NAME")}:${readEnvOrDie("DANXBOT_BOARD_NAME")}`,
         // DX-1398 — OPTIONAL cross-process trace context. Present → stamped on every
         // outbound call so the agent's card writes chain under the launch; absent
@@ -138,8 +156,29 @@ function boot() {
         // DX-2683 — the working session, when there is one. See below.
         session: readSessionConfig(),
     };
+    connection = {
+        dashboardUrl: config.baseUrl.replace(/\/+$/, ""),
+        source: credential.source,
+        fingerprint: credential.fingerprint,
+    };
     client = new DashboardHttpClient(config);
 }
+/**
+ * DX-2862 — the credential, through the ONE resolver the `bridge` subcommand
+ * also uses, so a session's tools and its event stream can never sign in as two
+ * different identities. A credential that cannot be resolved exits non-zero
+ * naming the remedy, never a degraded or anonymous server.
+ */
+function resolveCredentialOrDie() {
+    try {
+        return resolveDeclaredCredential(process.env);
+    }
+    catch (err) {
+        const credentialError = err;
+        console.error(`[danx-dashboard-mcp] ${credentialError.message}\n  Fix: ${credentialError.fix}`);
+        process.exit(1);
+    }
+}
 /**
  * DX-2683 — WHO THIS SESSION IS, read from the environment Claude Code
  * already provides.
@@ -708,7 +747,23 @@ server.tool("plan_connect",
         .min(1)
         .optional()
         .describe("THIS session's own Claude session title — from `get_session({session_id:\"self\"}).title`, passed verbatim, never invented or derived from the repo/cwd. Stored on your session's row: a title different from what is already stored UPDATES it; omit to leave the stored title untouched. Not this plan's name. At most 200 characters — an overlong title is refused with a 400 naming its length."),
-}, async (args) => jsonResult(await planConnect(client, args)));
+}, 
+// DX-2862 — the connect is also the moment this session's event bridge learns
+// WHICH dashboard credential owns its stream: of the dashboard MCP servers a
+// session may have configured, the one that connected the plan is the one
+// whose credential the stream must be minted with.
+async (args) => {
+    const result = await planConnect(client, args);
+    return jsonResult({
+        ...result,
+        ...recordSessionConnectionAfterConnect(result, {
+            sessionId: config.session?.id,
+            dashboardUrl: connection.dashboardUrl,
+            source: connection.source,
+            fingerprint: connection.fingerprint,
+        }),
+    });
+});
 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`."),

package/dist/session-connection.js

@@ -0,0 +1,176 @@
+/**
+ * DX-2862 — the record that hands ONE Claude Code session's dashboard
+ * connection from its MCP server to its event bridge.
+ *
+ * THE PROBLEM THIS SOLVES. `danx-dashboard-mcp bridge` runs from a plugin hook,
+ * in the SESSION's environment — not in the MCP server's, which is the only
+ * place the server's `.mcp.json` env block exists. So the bridge cannot see
+ * what the server was configured with, and before this it simply used its own
+ * ambient `DANXBOT_DISPATCH_TOKEN`. When that was a different credential from
+ * the server's, every event was dropped silently (the card's incident).
+ *
+ * WHAT IS WRITTEN, AND WHAT IS NOT. On a successful `plan_connect` the server
+ * writes the dashboard URL, the credential SOURCE (a file path, or the name of
+ * an env var — never a credential) and the credential's FINGERPRINT. The bridge
+ * reads that record, resolves the SAME source through the same resolver
+ * (`credential.ts`), and refuses to run unless what it resolved fingerprints
+ * identically. A rotated file or a session environment that disagrees with the
+ * server's therefore fails loud instead of streaming somebody else's events —
+ * or, as in DX-2862, none at all.
+ *
+ * WHY `plan_connect` AND NOTHING ELSE WRITES IT. A session can have several
+ * dashboard MCP servers configured (gpt-manager has a deployed one and a local
+ * one). The server that CONNECTED the session to a plan is, by construction,
+ * the one whose credential owns that session's stream — so the connect is the
+ * only moment at which the right server is identifiable. Writing at boot would
+ * be a race between servers over the same file.
+ *
+ * The record is per session, tiny, and pruned after `STALE_RECORD_MS` — the
+ * dashboard keeps only a week of events, so an older session cannot resume
+ * anything anyway.
+ */
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** One canonical shape (CLAUDE.md Core Principle 1) — a record of any other version is refused, never adapted. */
+export const SESSION_CONNECTION_SCHEMA_VERSION = 1;
+export const STALE_RECORD_MS = 7 * 24 * 60 * 60 * 1000;
+export function sessionConnectionDir(home = homedir()) {
+    return join(home, ".config", "danxbot", "plan-sessions");
+}
+/** A session id is a path segment here, so an odd one is refused rather than turned into a path. */
+export function sessionConnectionPath(sessionId, home = homedir()) {
+    if (typeof sessionId !== "string" || !/^[A-Za-z0-9_-]+$/.test(sessionId)) {
+        throw new Error(`session id is missing or has unexpected characters: ${JSON.stringify(sessionId)}`);
+    }
+    return join(sessionConnectionDir(home), `${sessionId}.json`);
+}
+/** Remove records nothing has touched for `STALE_RECORD_MS`. */
+export function pruneStaleConnections(dir, now) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return; // nothing written yet
+    }
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const file = join(dir, name);
+        try {
+            if (now - statSync(file).mtimeMs > STALE_RECORD_MS)
+                rmSync(file, { force: true });
+        }
+        catch {
+            /* removed by another process */
+        }
+    }
+}
+/**
+ * Record this session's connection. Write-then-rename, so a bridge reading
+ * concurrently sees the old record or the new one, never a torn one.
+ */
+export function writeSessionConnection(record, options = {}) {
+    const home = options.home ?? homedir();
+    const now = options.now ?? Date.now();
+    const file = sessionConnectionPath(record.sessionId, home);
+    const dir = sessionConnectionDir(home);
+    mkdirSync(dir, { recursive: true });
+    pruneStaleConnections(dir, now);
+    const full = {
+        schemaVersion: SESSION_CONNECTION_SCHEMA_VERSION,
+        ...record,
+        connectedAt: new Date(now).toISOString(),
+    };
+    const tmp = `${file}.${process.pid}.${now}.tmp`;
+    writeFileSync(tmp, JSON.stringify(full), { mode: 0o600 });
+    renameSync(tmp, file);
+    return full;
+}
+/**
+ * This session's record, or `null` when there is none (the session has never
+ * connected a plan from a server new enough to record one). A record that IS
+ * there but unreadable or of another shape throws — a connection we cannot
+ * understand is not the same thing as no connection, and quietly treating it as
+ * one is how a session goes deaf without a word.
+ */
+export function readSessionConnection(sessionId, options = {}) {
+    const file = sessionConnectionPath(sessionId, options.home ?? homedir());
+    let raw;
+    try {
+        raw = readFileSync(file, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw new Error(`cannot read the session connection record ${file}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`the session connection record ${file} is not JSON: ${err.message}`);
+    }
+    const invalid = invalidRecordReason(parsed);
+    if (invalid !== null)
+        throw new Error(`the session connection record ${file} is unusable: ${invalid}`);
+    return parsed;
+}
+/**
+ * Record the connection a successful `plan_connect` just made, and say so in
+ * that tool's own answer when it could not be recorded.
+ *
+ * FAIL LOUD, IN THE ONE PLACE THE AGENT IS LOOKING. A connect whose record is
+ * missing produces a session that is connected and a bridge that refuses to
+ * start — so the failure belongs in the connect's answer, not only in a file
+ * nobody reads. It does NOT fail the connect itself: the session IS connected,
+ * and reporting otherwise would be a second lie on top of the first.
+ */
+export function recordSessionConnectionAfterConnect(result, inputs, write = writeSessionConnection) {
+    if (!result.ok)
+        return {};
+    if (inputs.sessionId === undefined || inputs.sessionId === "") {
+        return {
+            event_bridge_error: "connected, but this server has no CLAUDE_CODE_SESSION_ID, so the plan event bridge has no connection to read — " +
+                "dashboard events will NOT reach this session",
+        };
+    }
+    try {
+        write({
+            sessionId: inputs.sessionId,
+            dashboardUrl: inputs.dashboardUrl,
+            source: inputs.source,
+            fingerprint: inputs.fingerprint,
+        });
+        return {};
+    }
+    catch (err) {
+        return {
+            event_bridge_error: `connected, but recording the connection for the plan event bridge failed (${err.message}) — ` +
+                "dashboard events will NOT reach this session until it succeeds",
+        };
+    }
+}
+/** Why a parsed record cannot be used, or `null` when it can. */
+export function invalidRecordReason(value) {
+    if (typeof value !== "object" || value === null)
+        return "it is not an object";
+    const r = value;
+    if (r.schemaVersion !== SESSION_CONNECTION_SCHEMA_VERSION) {
+        return `schemaVersion is ${JSON.stringify(r.schemaVersion)}, not ${SESSION_CONNECTION_SCHEMA_VERSION}`;
+    }
+    for (const field of ["sessionId", "dashboardUrl", "fingerprint", "connectedAt"]) {
+        if (typeof r[field] !== "string" || r[field] === "")
+            return `${field} is not a non-empty string`;
+    }
+    const source = r.source;
+    if (typeof source !== "object" || source === null)
+        return "source is not an object";
+    if (source.kind === "file")
+        return typeof source.path === "string" && source.path !== "" ? null : "source.path is not a path";
+    if (source.kind === "env")
+        return typeof source.name === "string" && source.name !== "" ? null : "source.name is not a variable name";
+    return `source.kind is ${JSON.stringify(source.kind)}, which this version does not know`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.75",
+  "version": "0.1.76",
   "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",