@thehammer/danx-dashboard-mcp 0.1.80 → 0.1.82

package/README.md

@@ -60,10 +60,10 @@ CLAUDE_CODE_SESSION_ID=<session> npx -y @thehammer/danx-dashboard-mcp@<version>
 ```
 
 - **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":[…]}`.
+- **No client-side reach check (DX-2920).** `bridge` used to prove board reach itself, before ever opening the stream (`GET /api/plans/mine?fields=cards` + a per-board `GET /api/issues/:id/problems`). That check is DELETED — the dashboard (DX-2863) now enforces the identical requirement server-side, and a second client-side copy of the same check was a duplicate source of truth, not a safety net: it refuses a mint (`403 issuer_cannot_read_plan_boards`), refuses stream admission (the SAME 403), and ends a live stream (`event: end`, `{"reason":"scope_narrowed","boards":[…]}`) the instant it stops being true. `bridge` only MAPS those refusals now — see "Stopping" below — it never independently verifies anything before streaming. Once a ticket is minted, `bridge` emits, once, `{"type":"ready"}` — no `boards` field, since reach is no longer proven client-side.
 - **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":"…","fix":"…"}` and exit, only on a terminal outcome. `fix` is the remedy shown to the session (`STOP_FIXES` in `src/bridge.ts` — never a log-only hint), so a session that hits a stop it cannot otherwise see still knows what to do about it. Terminal reasons: `no_connection_record` / `credential_unavailable` / `credential_mismatch` (the start-time checks above), `not_connected`, `unauthorized` (401/403), `mint_refused` (any other non-transient refusal), `mint_bad_response`, `board_unreadable` / `scope_check_failed` (the reach check above), `superseded` / `replaced` (exit 0 — a newer or replacing connection already serves this session, so `fix` says no action is needed), `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.
+- **Stopping.** Last, one `{"type":"stopped","reason":"…","detail":"…","fix":"…"}` and exit, only on a terminal outcome. `fix` is the remedy shown to the session (`STOP_FIXES` in `src/bridge.ts` — never a log-only hint), so a session that hits a stop it cannot otherwise see still knows what to do about it. Terminal reasons: `no_connection_record` / `credential_unavailable` / `credential_mismatch` (the start-time checks above), `not_connected` (a `409 session_not_connected` at mint OR at stream admission, or a live `end("not_connected")` — all three mapped identically), `unauthorized` (401/403 for a reason OTHER than an unreadable board), `mint_refused` (any other non-transient mint refusal), `mint_bad_response`, `board_unreadable` (a `403 issuer_cannot_read_plan_boards` at mint OR at stream admission, naming the unreadable boards — DX-2920), `scope_narrowed` (a LIVE stream's `end("scope_narrowed", boards)` — the server's `end()` REQUIRES `boards` for this reason at the type level, `bridge` parses them off the wire and names them in `detail`/`fix`, never a generic message), `bad_end_payload` (a `scope_narrowed` end whose `boards` array was missing or malformed — a protocol error surfaced loudly, never silently downgraded to a boards-less `scope_narrowed`), `superseded` / `replaced` (exit 0 — a newer or replacing connection already serves this session, so `fix` says no action is needed), `revoked`, or `refused` (two freshly minted tickets refused in a row with no more specific classification). 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

@@ -20,29 +20,59 @@
  *      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.
+ *   4. DX-2920 — board-coverage reach is a SERVER-ENFORCED property now, never a
+ *      client-side verify: the stream admits an event only when the ticket
+ *      issuer's board allowlist covers that event's board (`isVisibleToStream`,
+ *      dashboard), and the dashboard itself (DX-2863) refuses to hand out a
+ *      ticket, refuses to admit a connection, and ends a live stream the instant
+ *      that stops being true — `403 issuer_cannot_read_plan_boards` at MINT
+ *      (`mintTicket`) AND at stream ADMISSION (`classifyAdmissionRefusal`,
+ *      reading `listen.ts`'s structured `refusal`) are BOTH mapped to
+ *      `board_unreadable`, naming the boards; `409 session_not_connected` at
+ *      mint AND at admission are both mapped to `not_connected`; and
+ *      `end("scope_narrowed", boards)` / `end("not_connected")` cover the
+ *      same two failures once the stream is already live — `end`'s own
+ *      overloaded signature in `plan-session-stream.ts` REQUIRES `boards` for
+ *      `scope_narrowed` at the type level (round 3), and `listen.ts` parses
+ *      them off the wire the same way it parses `reason`, so this module can
+ *      name them in `scope_narrowed`'s detail/fix exactly like it already
+ *      does for `board_unreadable`. This module no longer runs its own
+ *      duplicate board-by-board check before streaming — see DX-2920 and the
+ *      deleted `verifyPlanBoardsReadable`.
  *   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.
+ *   6. Writes JSON Lines to stdout: ONE `{type:"ready"}` once a ticket has been
+ *      minted and streaming is about to start, `{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:
  *   - `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;
+ *   - `not_connected`         the mint, or the stream's admission / keep-alive,
+ *                              answered `session_not_connected` (409 at mint and
+ *                              at admission; `end("not_connected")` once live);
+ *   - `unauthorized`          the mint answered 401 / 403 for a reason OTHER
+ *                              than an unreadable board;
  *   - `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;
+ *   - `board_unreadable`      the mint OR the stream's admission was refused
+ *                              `403 issuer_cannot_read_plan_boards`, naming the
+ *                              boards this credential cannot read (DX-2920);
+ *   - `scope_narrowed`        a LIVE stream ended because the plan grew, or the
+ *                              credential's allowlist shrank past, a board this
+ *                              credential can no longer read — `boards` names
+ *                              them, parsed from the dashboard's own `end`
+ *                              payload by `listen.ts` the same way `reason`
+ *                              itself is parsed, and `detail`/`fix` are built
+ *                              dynamically from them (DX-2920 round 3 —
+ *                              `boardUnreadableDetail` / `scopeNarrowedFix`),
+ *                              never a static generic message;
+ *   - `bad_end_payload`       a `scope_narrowed` end whose `boards` array was
+ *                              missing or malformed — a PROTOCOL error, never
+ *                              silently downgraded to a boards-less
+ *                              `scope_narrowed` stop (DX-2920 round 3);
  *   - `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.
@@ -54,14 +84,13 @@
  * session's own MCP server declared, resolved here from that declaration.
  */
 import { homedir } from "node:os";
+import { errorCodeOf } from "./json-body.js";
 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 dashboard request may take before it counts as a transient failure. */
 export const REQUEST_TIMEOUT_MS = 10_000;
@@ -69,10 +98,7 @@ 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: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BRIDGE_SUBCOMMAND} ` +
     `[--resume-ids <event-id>[,<event-id>...]]`;
 /**
@@ -95,7 +121,11 @@ export const STOP_FIXES = {
     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",
+    // DX-2920 (round 3) — a `scope_narrowed` end whose `boards` array was
+    // missing or invalid (`listen.ts`'s parse-time check). Named separately
+    // from `scope_narrowed` itself, which always carries boards and never
+    // reaches this generic map at all.
+    bad_end_payload: "call plan_connect again to mint a new listener ticket for this session",
     // A newer ticket exists (superseded) or another connection is already using
     // this one (replaced) — THIS process is ending because the session is
     // already served elsewhere, not because anything is broken.
@@ -127,6 +157,11 @@ export function parseBridgeArgs(argv, env) {
 }
 /** A start this process cannot make, named the way the session will be told about it. */
 export class BridgeStartError extends Error {
+    // DX-2920 (round 4) — `ListenStopReason`, not `string`: a start-time failure
+    // is always one of `no_connection_record` / `credential_unavailable` /
+    // `credential_mismatch`, never `scope_narrowed` (there is no stream yet), so
+    // this can be the closed reason type the eventual `write({type:"stopped",
+    // reason: start.reason, ...})` needs it to be.
     reason;
     fix;
     constructor(reason, detail, fix) {
@@ -175,15 +210,43 @@ export function resolveBridgeOptions(args, env, options = {}) {
         resumeIds: args.resumeIds,
     };
 }
-function errorCodeOf(body) {
-    return typeof body === "object" && body !== null && typeof body.error === "string"
-        ? body.error
-        : null;
+/**
+ * DX-2920 — `body.boards` off a `403 issuer_cannot_read_plan_boards` refusal
+ * (`unreadableBoardsRefusal`, dashboard `plan-scope.ts`), or `[]` when the body
+ * doesn't carry a readable list (defensive — never trust the wire shape blindly).
+ */
+function boardsOf(body) {
+    if (typeof body !== "object" || body === null)
+        return [];
+    const boards = body.boards;
+    return Array.isArray(boards) ? boards.filter((b) => typeof b === "string") : [];
+}
+/**
+ * DX-2920 — the ONE `board_unreadable` detail-line builder, shared by the mint
+ * 403 classification and the stream admission's identical 403, so the two can
+ * never drift into two different ideas of how to phrase "these boards".
+ */
+function boardUnreadableDetail(boards, fallback) {
+    return boards.length > 0
+        ? `this session's dashboard credential cannot read board(s) ${boards.join(", ")} on the connected plan`
+        : fallback;
+}
+/**
+ * DX-2920 (round 3) — `scope_narrowed`'s fix, built dynamically from the
+ * boards `listen.ts` parsed off the dashboard's own `end` payload (AC 30661:
+ * "naming the missing boards and how to widen scope"), replacing the static
+ * generic `STOP_FIXES` entry round 2 shipped before the server actually sent
+ * a board list.
+ */
+function scopeNarrowedFix(boards) {
+    return boards.length > 0
+        ? `widen this session's dashboard credential to cover board(s) ${boards.join(", ")}, or connect a plan whose cards all live on boards it can read`
+        : "widen this session's dashboard credential to cover every board the connected plan's cards live on, or connect a plan whose cards all live on boards it can read";
 }
 /**
  * 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
+ * about THIS MOMENT (network, timeout, 408/429, 5xx) as transient. Shared by
+ * every request this module makes so they can never disagree about which
  * failures are worth retrying.
  */
 async function request(options, deps, what, url, init = { method: "GET" }) {
@@ -259,6 +322,19 @@ export async function mintTicket(options, deps) {
     if (status === 409 && errorCodeOf(body) === "session_not_connected") {
         return { kind: "terminal", reason: "not_connected", detail: "the session is not connected to a plan" };
     }
+    // DX-2920 (AC 30660) — this credential IS accepted; it just cannot read every
+    // board the connected plan covers (`unreadableBoardsRefusal`, dashboard
+    // `plan-scope.ts`). Calling that `unauthorized` told the session to fix its
+    // credential, which was the wrong remedy for a scope problem — this is
+    // `board_unreadable`, naming the boards, checked BEFORE the generic 401/403
+    // fallback below so it never falls into it.
+    if (status === 403 && errorCodeOf(body) === "issuer_cannot_read_plan_boards") {
+        return {
+            kind: "terminal",
+            reason: "board_unreadable",
+            detail: boardUnreadableDetail(boardsOf(body), `ticket mint HTTP 403: issuer_cannot_read_plan_boards ${oneLine(text, 300)}`),
+        };
+    }
     if (status === 401 || status === 403) {
         return { kind: "terminal", reason: "unauthorized", detail: `ticket mint HTTP ${status} ${oneLine(text, 300)}` };
     }
@@ -277,121 +353,60 @@ export async function mintTicket(options, deps) {
         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.
+ * DX-2920 — a stream admission refusal (`listen.ts`'s STRUCTURED `refused`
+ * outcome — `{status, errorCode, body}`, parsed once in `connectOnce`) whose
+ * shape matches one the mint route already gives its OWN name to. Two cases:
  *
- * 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".
+ *   - `409 session_not_connected` — the SAME shape the mint route uses for "no
+ *     plan connected" (`plan-session-stream.ts`, DX-2863 review finding M2). A
+ *     session with no plan connected is the identical terminal state whether
+ *     the dashboard says so at mint or at the stream's own admission check,
+ *     and the session should see ONE remedy either way.
+ *   - `403 issuer_cannot_read_plan_boards` — the SAME shape the mint route's
+ *     board-coverage refusal uses (AC 30660's fix 4 — a ticket minted before a
+ *     board became unreadable can still be refused ADMISSION for it later; that
+ *     refusal deserves the same `board_unreadable` naming as the mint-time one,
+ *     not a re-mint-and-retry loop that just hits the identical refusal again).
  *
- * 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.
+ * Classifies by STATUS + ERROR CODE, never by re-deriving them from the
+ * flattened `detail` string — the second-source-of-truth shape this card's fix
+ * round closed (the regex-based `isSessionNotConnectedRefusal` it replaced).
  */
-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: `plan read HTTP ${status} ${oneLine(text, 300)}` };
-        }
-        if (status < 200 || status >= 300) {
-            return { kind: "terminal", reason: "scope_check_failed", detail: `plan read HTTP ${status} ${oneLine(text, 300)}` };
-        }
-        const page = cardsPageOf(body);
-        if (typeof page === "string") {
-            return { kind: "terminal", reason: "scope_check_failed", detail: `plan read HTTP ${status}: ${page}` };
-        }
-        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;
+function classifyAdmissionRefusal(refusal) {
+    if (refusal === undefined)
+        return null;
+    if (refusal.status === 409 && refusal.errorCode === "session_not_connected") {
+        return { reason: "not_connected", detail: "the session is not connected to a plan" };
     }
-    for (const [boardId, cardId] of firstCardPerBoard) {
-        // `?board=` is not read by this route's auth check (it derives the board from
-        // `cardId`'s own `board_id` — `resolveIssueBoardId`) — kept only so the URL and
-        // the `board read of ${boardId}` label above it name the same board at a glance.
-        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)}`,
-            };
-        }
+    if (refusal.status === 403 && refusal.errorCode === "issuer_cannot_read_plan_boards") {
+        return {
+            reason: "board_unreadable",
+            detail: boardUnreadableDetail(boardsOf(refusal.body), "this session's dashboard credential cannot read a board on the connected plan"),
+        };
     }
-    return { kind: "ok", boards: [...firstCardPerBoard.keys()] };
+    return null;
 }
 /**
- * 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.
+ * 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, fix: fixForStop(reason) });
+    function stop(reason, detail, code, extra) {
+        if (reason === "scope_narrowed") {
+            if (extra?.boards === undefined) {
+                throw new Error('stop("scope_narrowed", ...) requires boards — unreachable through the exported overloads above');
+            }
+            deps.write({ type: "stopped", reason, detail, boards: extra.boards, fix: scopeNarrowedFix(extra.boards) });
+            return code;
+        }
+        deps.write({ type: "stopped", reason, detail, refusal: extra?.refusal, fix: extra?.fix ?? fixForStop(reason) });
         return code;
-    };
+    }
     let backoff = MINT_INITIAL_BACKOFF_MS;
     let refusedInRow = 0;
-    let verified = false;
+    let readyEmitted = false;
     for (;;) {
         const minted = await mintTicket(options, deps);
         if (minted.kind === "terminal")
@@ -401,19 +416,13 @@ 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 });
+        // DX-2920 — `ready` fires once, on the FIRST successful mint, now that
+        // board reach is proven by the dashboard's own mint refusal rather than a
+        // client-side check run here (see the module docblock + the deleted
+        // `verifyPlanBoardsReadable`). A re-mint (a lapsed lease) never repeats it.
+        if (!readyEmitted) {
+            readyEmitted = true;
+            deps.write({ type: "ready" });
         }
         backoff = MINT_INITIAL_BACKOFF_MS;
         const run = { stopped: null, emitted: false };
@@ -437,12 +446,28 @@ export async function runBridge(options, deps) {
         const stopped = run.stopped;
         if (stopped === null)
             throw new Error("the stream reader ended without a stop record");
-        if (TAKEOVER_REASONS.has(stopped.reason))
+        // DX-2920 (round 4) — direct equality, not `TAKEOVER_REASONS.has(...)`:
+        // `Set.has()` is a runtime check only, so it cannot narrow `stopped.reason`
+        // for the compiler — leaving it a `Set` lookup here would keep every
+        // downstream branch's exhaustive narrowing (which is what makes the final
+        // fallthrough's `stop(stopped.reason, ...)` call type-check against the
+        // closed `ListenStopReason` overload) from working.
+        if (stopped.reason === "superseded" || stopped.reason === "replaced")
             return stop(stopped.reason, stopped.detail, 0);
         if (stopped.reason === "lease_expired") {
             refusedInRow = 0;
             continue;
         }
+        if (stopped.reason === "refused") {
+            const classified = classifyAdmissionRefusal(stopped.refusal);
+            if (classified !== null) {
+                // DX-2920 — a NAMED admission refusal is terminal at once, exactly
+                // like its mint-time counterpart — never counted toward the generic
+                // refused-ticket retry budget below, which exists for an admission
+                // refusal with no more specific explanation than "not admitted".
+                return stop(classified.reason, classified.detail, 1);
+            }
+        }
         if (stopped.reason === "refused") {
             const provedHealthy = run.emitted || deps.now() - startedAt >= HEALTHY_CONNECTION_MS;
             refusedInRow = provedHealthy ? 1 : refusedInRow + 1;
@@ -451,6 +476,15 @@ export async function runBridge(options, deps) {
             }
             continue;
         }
+        if (stopped.reason === "scope_narrowed") {
+            // DX-2920 (round 4) — `stopped.boards` is REQUIRED at the type level now
+            // (`ListenStopped`'s `scope_narrowed` member), populated by `listen.ts`'s
+            // parse of the dashboard's own `end` payload (never a re-derivation from
+            // `detail`) — no `?? []`, no optional check, `stopped.boards` IS
+            // `string[]` once narrowed to this branch.
+            const boards = stopped.boards;
+            return stop("scope_narrowed", boardUnreadableDetail(boards, stopped.detail), 1, { boards });
+        }
         return stop(stopped.reason, stopped.detail, 1);
     }
 }

package/dist/index.js

@@ -94,6 +94,7 @@
  */
 import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
+import { PLAN_STATE_SUBCOMMAND, runPlanStateCommand } from "./plan-state.js";
 import { resolveDeclaredCredential } from "./credential.js";
 import { recordSessionConnectionAfterConnect } from "./session-connection.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -881,16 +882,25 @@ 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`.
 //
-// `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 only
-// input is `CLAUDE_CODE_SESSION_ID` (read from its environment) plus
-// `--resume-ids` — the dashboard URL, credential source, and credential itself
-// come from the session-connection record this server's own `plan_connect`
-// wrote (`session-connection.ts`), never from the bridge's own environment
-// (DX-2862: a bridge trusting its own ambient `DANXBOT_DISPATCH_TOKEN` is the
-// exact bug this repo fixed). 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.
+// `bridge` and `plan-state` are the two subcommands. `bridge` is the session
+// event stream client the danxbot plugin's plan event bridge runs. It never
+// boots the MCP server; its only input is `CLAUDE_CODE_SESSION_ID` (read from
+// its environment) plus `--resume-ids` — the dashboard URL, credential source,
+// and credential itself come from the session-connection record this server's
+// own `plan_connect` wrote (`session-connection.ts`), never from the bridge's
+// own environment (DX-2862: a bridge trusting its own ambient
+// `DANXBOT_DISPATCH_TOKEN` is the exact bug this repo fixed).
+//
+// `plan-state` (DX-2921) is the ONE-SHOT client of
+// `GET /api/plan-sessions/me/turn-state`, run by the DX-2888 plugin's
+// turn-start / turn-end hooks — see `plan-state.ts`'s own doc comment for the
+// full contract. It ALWAYS exits 0 (success or failure alike: the hook must
+// stay silent), so even an unexpected rejection here is caught and reported
+// the same `{ok:false, reason}` way rather than propagating a non-zero exit
+// or an uncaught stack trace into the hook.
+//
+// Any OTHER argument is refused rather than ignored, so a typo cannot
+// silently start an MCP server on stdio where a subcommand was meant to run.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
     const [subcommand, ...rest] = process.argv.slice(2);
     if (subcommand === BRIDGE_SUBCOMMAND) {
@@ -899,8 +909,16 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(1);
         });
     }
+    else if (subcommand === PLAN_STATE_SUBCOMMAND) {
+        runPlanStateCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] plan-state fatal: ${err.message}`);
+            process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
+            process.exit(0);
+        });
+    }
     else if (subcommand !== undefined) {
-        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is "${BRIDGE_SUBCOMMAND}")`);
+        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
+            `"${BRIDGE_SUBCOMMAND}" and "${PLAN_STATE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/json-body.js

@@ -0,0 +1,23 @@
+/**
+ * DX-2920 — the ONE place that reads a JSON body's top-level `.error` string.
+ *
+ * WHY THIS EXISTS. `bridge.ts` (classifying a mint refusal) and `listen.ts`
+ * (classifying a stream admission refusal) both need to answer "what error
+ * code did this JSON body carry", and before this card each answered it a
+ * different way: `bridge.ts` parsed the body directly, `listen.ts` never
+ * looked past a flattened, human-readable detail string at all — a caller
+ * that wanted to react to a SPECIFIC refusal (the admission-time 409 the
+ * mint route also uses) had to regex-scrape that flattened string back apart,
+ * a second, fragile source of truth for the same fact. This module is generic
+ * — it knows nothing about "session_not_connected" or "issuer_cannot_read_plan_boards",
+ * only that a JSON object may carry a top-level string field named `error` —
+ * so it can live in BOTH the domain-aware `bridge.ts` and the deliberately
+ * generic `listen.ts` (whose own docblock states it carries no domain
+ * knowledge of the dashboard's specific error shapes) without either one
+ * importing the other.
+ */
+export function errorCodeOf(body) {
+    return typeof body === "object" && body !== null && typeof body.error === "string"
+        ? body.error
+        : null;
+}

package/dist/listen.js

@@ -12,9 +12,27 @@
  *     `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).
+ *   - `{type:"stopped", reason, detail, refusal?, boards?}` — once, last. `reason`
+ *     is the dashboard's own end reason (`superseded`, `replaced`, `revoked`,
+ *     `scope_narrowed`, `not_connected`), `refused` (the ticket was not
+ *     admitted), `bad_end_payload` (a `scope_narrowed` end whose `boards` array
+ *     was missing/invalid — a protocol error, never silently downgraded), or
+ *     `lease_expired` (no healthy connection for the lease). DX-2920 —
+ *     `refusal` is populated ONLY for `reason === "refused"`: `{status,
+ *     errorCode, body}`, the admission response parsed ONCE here, so a
+ *     consumer can recognize a SPECIFIC refusal (the dashboard's own
+ *     `409 session_not_connected`, the same shape the mint route uses) by
+ *     status + error code rather than re-deriving it from the flattened
+ *     `detail` string. `boards` is REQUIRED (round 4 — a discriminated union,
+ *     not an optional field: see `ListenStopped` / `ListenStopReason`) for
+ *     `reason === "scope_narrowed"` and absent for every other reason, parsed
+ *     from the dashboard's `end` payload the SAME way `reason` itself is
+ *     parsed — never re-derived from `detail`. A wire `reason` value this
+ *     build does not recognize (a newer dashboard's reason an older bridge
+ *     hasn't shipped yet) normalizes to `"unknown"` rather than passing the
+ *     raw string through, so the closed set stays closed — `fixForStop`'s
+ *     generic `DEFAULT_STOP_FIX` handles it exactly as it already handled a
+ *     verbatim unrecognized string.
  *   - nothing for keep-alives, the connect marker, or a successful reconnect.
  *
  * RECONNECT AND RESUME. The stream drops whenever the dashboard restarts, and can
@@ -32,6 +50,7 @@
  * (`src/issues/db/issue-activity.ts`); this published package cannot import
  * danxbot source.
  */
+import { errorCodeOf } from "./json-body.js";
 import { oneLine } from "./one-line.js";
 export const INITIAL_BACKOFF_MS = 1_000;
 export const MAX_BACKOFF_MS = 30_000;
@@ -181,6 +200,23 @@ function parseBlock(block) {
     }
     return sawField ? { id, event, data: data.join("\n") } : null;
 }
+/**
+ * DX-2920 (round 4) — the dashboard's own `StreamEndReason` values this
+ * client recognizes on the wire, EXCLUDING `scope_narrowed` (parsed by its own
+ * dedicated branch in `handle()` below, since it alone carries `boards`).
+ * Hand-copied from `StreamEndReason` in `src/issues/plan-session-listeners.ts`
+ * — this published package cannot import danxbot source. A wire `reason` this
+ * set does not contain (a newer dashboard's reason this build predates)
+ * normalizes to `"unknown"` rather than passing the raw string through, which
+ * is what lets `Outcome`'s `reason` field below be a closed union instead of
+ * `string` — see `ListenStopReason`'s docblock for why that closure is what
+ * makes the `scope_narrowed`-requires-`boards` invariant an actual compile
+ * error rather than a comment's promise.
+ */
+const KNOWN_WIRE_END_REASONS = new Set(["superseded", "replaced", "revoked", "not_connected"]);
+function isKnownWireEndReason(reason) {
+    return KNOWN_WIRE_END_REASONS.has(reason);
+}
 /** Statuses that describe the moment, not the ticket — retry them. */
 const RETRYABLE_CLIENT_STATUSES = new Set([408, 429]);
 /**
@@ -201,14 +237,55 @@ export async function runListener(options, deps) {
     };
     for (const id of options.resumeIds.slice(-DELIVERED_ID_MEMORY))
         remember(id);
-    const stop = (reason, detail, code) => {
-        deps.write({ type: "stopped", reason, detail });
+    function stop(reason, detail, code, extra) {
+        if (reason === "scope_narrowed") {
+            if (extra?.boards === undefined) {
+                throw new Error('stop("scope_narrowed", ...) requires boards — unreachable through the exported overloads above');
+            }
+            deps.write({ type: "stopped", reason, detail, boards: extra.boards });
+            return code;
+        }
+        deps.write({ type: "stopped", reason, detail, refusal: extra?.refusal });
         return code;
-    };
+    }
     const handle = (message) => {
         if (message.event === "end") {
-            const reason = JSON.parse(message.data).reason;
-            return { kind: "ended", reason: typeof reason === "string" ? reason : "unknown" };
+            // DX-2920 (round 3) — a JSON.parse failure here falls through to the
+            // pre-existing "unknown" reason below via `isRecord(null)`, unchanged
+            // from before this round. Only a `scope_narrowed` reason additionally
+            // REQUIRES a valid `boards` string array (matching the server's `end`
+            // overload, which cannot emit `scope_narrowed` without one) — a
+            // `scope_narrowed` frame that fails that check is a PROTOCOL error
+            // (a server too old to have sent boards, or a corrupted frame), never
+            // silently downgraded to the generic "the dashboard ended this
+            // listener" message the caller cannot act on.
+            let parsed;
+            try {
+                parsed = JSON.parse(message.data);
+            }
+            catch {
+                parsed = null;
+            }
+            const reasonRaw = isRecord(parsed) ? parsed.reason : undefined;
+            const reason = typeof reasonRaw === "string" ? reasonRaw : "unknown";
+            if (reason === "scope_narrowed") {
+                const boardsRaw = isRecord(parsed) ? parsed.boards : undefined;
+                const boards = Array.isArray(boardsRaw) && boardsRaw.length > 0 && boardsRaw.every((b) => typeof b === "string")
+                    ? boardsRaw
+                    : null;
+                if (boards === null) {
+                    return { kind: "ended", reason: "bad_end_payload" };
+                }
+                return { kind: "ended", reason, boards };
+            }
+            // DX-2920 (round 4) — a wire reason this build does not recognize (a
+            // newer dashboard's reason an older bridge hasn't shipped yet)
+            // normalizes to "unknown" rather than passing the raw string through:
+            // `Outcome`'s "ended" reason is now a closed set (`EndedReason`), and an
+            // open passthrough here would be exactly the hole that lets a
+            // missing-`boards` "scope_narrowed" construction slip past the compiler
+            // elsewhere — see `ListenStopReason`'s docblock.
+            return { kind: "ended", reason: isKnownWireEndReason(reason) ? reason : "unknown" };
         }
         if (message.event !== "activity")
             return null;
@@ -262,7 +339,25 @@ export async function runListener(options, deps) {
             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} ${oneLine(await response.text(), 300)}` };
+                const text = await response.text();
+                // DX-2920 — parsed ONCE, here, into a structured outcome a consumer can
+                // classify by status + error code (`bridge.ts` does, matching a specific
+                // admission refusal such as the dashboard's own `409 session_not_connected`)
+                // rather than re-deriving it from the flattened `detail` string below.
+                let body = null;
+                try {
+                    body = text === "" ? null : JSON.parse(text);
+                }
+                catch {
+                    body = null;
+                }
+                return {
+                    kind: "refused",
+                    status: response.status,
+                    errorCode: errorCodeOf(body),
+                    body,
+                    detail: `HTTP ${response.status} ${oneLine(text, 300)}`,
+                };
             }
             if (!response.ok || response.body === null) {
                 await response.body?.cancel();
@@ -296,10 +391,23 @@ export async function runListener(options, deps) {
             if (outcome.reason === "superseded" || outcome.reason === "replaced") {
                 return stop(outcome.reason, "another listener for this session took over", 0);
             }
+            if (outcome.reason === "bad_end_payload") {
+                return stop("bad_end_payload", "the dashboard's scope_narrowed end event carried no valid boards array — this is a protocol error, not an ordinary end", 1);
+            }
+            // DX-2920 (round 4) — split explicitly rather than the old conditional
+            // `outcome.boards === undefined ? undefined : {boards}` pass-through:
+            // `Outcome`'s "ended" kind is now itself discriminated on `reason`, so
+            // `outcome.boards` is GUARANTEED present here (no `?? []`, no optional
+            // check needed) once narrowed to `"scope_narrowed"`.
+            if (outcome.reason === "scope_narrowed") {
+                return stop("scope_narrowed", "the dashboard ended this listener", 1, { boards: outcome.boards });
+            }
             return stop(outcome.reason, "the dashboard ended this listener", 1);
         }
         if (outcome.kind === "refused") {
-            return stop("refused", `the dashboard refused the listener ticket: ${outcome.detail}`, 1);
+            return stop("refused", `the dashboard refused the listener ticket: ${outcome.detail}`, 1, {
+                refusal: { status: outcome.status, errorCode: outcome.errorCode, body: outcome.body },
+            });
         }
         if (outcome.healthy) {
             unhealthySince = null;

package/dist/plan-state.js

@@ -0,0 +1,194 @@
+/**
+ * `danx-dashboard-mcp plan-state` — the ONE-SHOT client of
+ * `GET /api/plan-sessions/me/turn-state` (DX-2921).
+ *
+ * WHO RUNS IT. The danxbot Claude Code plugin's DX-2888 turn-start /
+ * turn-end hooks, via the plugin's existing `bridgeCommand()` npx path — the
+ * SAME package pin, no separate install, no deep import of this package's
+ * `dist/` internals (that was DX-2921's whole reason to exist: the DX-2888
+ * architecture review found the first build of this logic vendored a private
+ * copy of the MCP package and hardcoded the dashboard HTTP contract inside
+ * the PLUGIN). The plugin decides what to DO with the answer (inject plan
+ * numbers at turn start, refuse to let a turn end while the session could
+ * legally start work and has nothing running); this module only fetches it.
+ *
+ * THE CONTRACT (agreed with the DX-2888 plugin side, issue comment 4245 on
+ * DX-2921 — binding, because the plugin is already built against it):
+ *   - print EXACTLY ONE JSON line on stdout, and ALWAYS exit 0 — success or
+ *     failure alike, because the hook must stay silent rather than spam the
+ *     session's own turn with a stack trace;
+ *   - a session that is not connected to a plan prints
+ *     `{"ok":false,"reason":"session_not_connected"}` — that EXACT literal,
+ *     because the plugin keys its no-log-spam rule on it (it is also the
+ *     dashboard's own 409 error code for this case — see
+ *     `requireConnectedPlanId`, `plan-session-context.ts`);
+ *   - on success, every count is a finite number, `plan` carries `id` +
+ *     `name`, and every `startable` / `held` entry carries a string `id` +
+ *     `title` — the plugin rejects anything else as `bad_response`, so this
+ *     module validates the server's response BEFORE printing it, rather than
+ *     trusting a 200 status to mean a well-shaped body;
+ *   - human-readable diagnostics go to stderr only, never stdout.
+ *
+ * THE CREDENTIAL — the SAME resolver `bridge` uses (DX-2862 / DX-2921 AC),
+ * via `resolveBridgeOptions` (`bridge.ts`): the dashboard URL, credential
+ * source and credential all come from the connection record this session's
+ * OWN danx-dashboard MCP server wrote on its last successful `plan_connect`
+ * (`session-connection.ts`), never from this process's own ambient env. That
+ * is deliberate here for the identical reason it is deliberate for `bridge`:
+ * a hook process trusting whatever `DANXBOT_DISPATCH_TOKEN` happens to be in
+ * its environment is precisely the DX-2862 bug (a hook's ambient credential
+ * silently pointed at a different dashboard from the one the session's tools
+ * actually use).
+ *
+ * A HARD TIMEOUT (AC 30672) — `PLAN_STATE_REQUEST_TIMEOUT_MS`. This call
+ * blocks a turn boundary the plugin is holding open, so it must never hang:
+ * a slow or wedged dashboard is `{ok:false, reason:"timeout"}`, not a stuck
+ * hook.
+ */
+import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
+export const PLAN_STATE_SUBCOMMAND = "plan-state";
+export const TURN_STATE_PATH = "/api/plan-sessions/me/turn-state";
+/** How long this one-shot call may take before it counts as a timeout. */
+export const PLAN_STATE_REQUEST_TIMEOUT_MS = 5_000;
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${PLAN_STATE_SUBCOMMAND}`;
+function errorCodeOf(body) {
+    return typeof body === "object" && body !== null && typeof body.error === "string"
+        ? body.error
+        : null;
+}
+function isFiniteNumber(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+function isCardRef(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.id === "string" &&
+        typeof v.title === "string");
+}
+/**
+ * The strict shape check the contract pins (comment 4245): finite counts, a
+ * `plan` with `id` + `name`, and a string `id` + `title` on every
+ * `startable` / `held` entry. `null` on anything short of that — a 200 whose
+ * body does not match is `bad_response`, exactly like a non-2xx.
+ */
+export function parseTurnStateBody(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const b = body;
+    const plan = b.plan;
+    if (typeof plan !== "object" || plan === null)
+        return null;
+    const p = plan;
+    if (!isFiniteNumber(p.id) || typeof p.name !== "string")
+        return null;
+    const counts = b.counts;
+    if (typeof counts !== "object" || counts === null)
+        return null;
+    const c = counts;
+    if (!isFiniteNumber(c.open) || !isFiniteNumber(c.inProgress) || !isFiniteNumber(c.needsYou))
+        return null;
+    if (!Array.isArray(b.startable) || !b.startable.every(isCardRef))
+        return null;
+    if (!Array.isArray(b.held) || !b.held.every(isCardRef))
+        return null;
+    return {
+        plan: { id: p.id, name: p.name },
+        counts: { open: c.open, inProgress: c.inProgress, needsYou: c.needsYou },
+        startable: b.startable,
+        held: b.held,
+    };
+}
+/**
+ * One authenticated GET, with a hard timeout, classified into the output
+ * shape this subcommand always prints — never a throw, never a non-2xx
+ * bubbling past this function.
+ */
+export async function fetchTurnState(options, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
+    let status;
+    let text;
+    try {
+        try {
+            const response = await deps.fetch(`${options.dashboardUrl}${TURN_STATE_PATH}`, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                    Accept: "application/json",
+                    [SESSION_ID_HEADER]: options.sessionId,
+                },
+                signal: controller.signal,
+            });
+            status = response.status;
+            text = await response.text();
+        }
+        catch (err) {
+            return { ok: false, reason: controller.signal.aborted ? "timeout" : "request_failed" };
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let body = null;
+    try {
+        body = text === "" ? null : JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: "bad_response" };
+    }
+    // The exact literal the plugin's no-log-spam rule keys on (AC 30672 /
+    // comment 4245) — the dashboard's own 409 error code for an unconnected
+    // session, passed through verbatim rather than renamed.
+    if (status === 409 && errorCodeOf(body) === "session_not_connected") {
+        return { ok: false, reason: "session_not_connected" };
+    }
+    if (status === 401 || status === 403) {
+        return { ok: false, reason: "unauthorized" };
+    }
+    if (status < 200 || status >= 300) {
+        return { ok: false, reason: "http_error" };
+    }
+    const parsed = parseTurnStateBody(body);
+    if (parsed === null) {
+        return { ok: false, reason: "bad_response" };
+    }
+    return { ok: true, ...parsed };
+}
+/** The bin's `plan-state` subcommand, wired to the real process. Always resolves to exit code 0. */
+export async function runPlanStateCommand(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`);
+    };
+    if (argv.length !== 0) {
+        // A malformed invocation is still a "the hook must stay silent" failure,
+        // not a crash — same ok:false/exit-0 contract as every other failure
+        // path here, with the usage line reserved for a human reading stderr.
+        write({ ok: false, reason: "usage" });
+        process.stderr.write(`${USAGE}\n`);
+        return 0;
+    }
+    const sessionId = env.CLAUDE_CODE_SESSION_ID;
+    if (!sessionId) {
+        write({ ok: false, reason: "no_session_id" });
+        process.stderr.write(`${USAGE}\n`);
+        return 0;
+    }
+    let options;
+    try {
+        options = resolveBridgeOptions({ sessionId, resumeIds: [] }, env, resolveFrom);
+    }
+    catch (err) {
+        const start = err;
+        write({ ok: false, reason: start.reason });
+        process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
+        return 0;
+    }
+    const output = await fetchTurnState(options, {
+        fetch: (input, init) => fetch(input, init),
+        requestTimeoutMs: PLAN_STATE_REQUEST_TIMEOUT_MS,
+    });
+    write(output);
+    return 0;
+}

package/package.json

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