@thehammer/danx-dashboard-mcp 0.1.81 → 0.1.83

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/handlers.js

@@ -844,6 +844,7 @@ export const PLAN_FIELD_GROUPS = [
     "records:caveat",
     "architecture",
     "sessions",
+    "notes",
 ];
 /**
  * DX-2834 — the plan-status taxonomy, mirroring `PLAN_FIELD_GROUPS` just
@@ -1147,6 +1148,85 @@ export async function planDeleteRecord(client, args) {
         body: { content_hash: args.content_hash },
     });
 }
+/**
+ * Write a milestone note to a plan, via `POST /api/plans/:plan_id/notes`.
+ * TAKES AN EXPLICIT `plan_id`, unlike `plan_add_record`/`plan_add_architecture_section`
+ * — mirrors `plan_add_card`'s sibling `plan_remove_card`/`plan_rename`: a
+ * dispatched worker has no plan connection when it finishes a card, and a
+ * card can sit on several plans, so the writer names which one the note
+ * belongs to. A note is a MILESTONE, not a log — write one when a card (or a
+ * related group of cards) finishes, an important decision lands, or a
+ * goal/rule/caveat/architecture section changes meaningfully; routine step
+ * progress stays a card comment. Links resolve on read into what they point
+ * at (a card's title, a record's ref + body, a section's title) — an unknown
+ * card id, an unparseable or foreign record ref, or an unknown or foreign
+ * section id is refused 400 naming exactly which one. A card link does NOT
+ * require the card to be a member of this plan; a record/section link MUST
+ * belong to THIS plan. `author` is stamped server-side from your identity,
+ * never sent by you. Unknown plan → 404. Returns the new note plus the
+ * plan's latest notes page.
+ */
+export async function planAddNote(client, args) {
+    return client.request({
+        method: "POST",
+        path: `/${args.plan_id}/notes`,
+        basePath: PLANS_BASE_PATH,
+        body: {
+            title: args.title,
+            body: args.body,
+            ...(args.card_ids === undefined ? {} : { card_ids: args.card_ids }),
+            ...(args.record_refs === undefined ? {} : { record_refs: args.record_refs }),
+            ...(args.section_ids === undefined ? {} : { section_ids: args.section_ids }),
+        },
+    });
+}
+/**
+ * Edit a plan note, via `PATCH /api/plans/:plan_id/notes/:note_id`.
+ * `content_hash` MUST be the note's `contentHash` from your last read; on a
+ * mismatch nothing is written and you get `{error: "stale_plan_note",
+ * currentHash, currentTitle, currentBody, currentLinks}` — merge into those
+ * and retry with `content_hash: currentHash`, never blindly. `title`/`body`
+ * are each optional and keep their stored value when omitted. The LINK
+ * fields are all-or-nothing as a GROUP: omit all three to keep the stored
+ * link set untouched; send ANY one of them to REPLACE THE WHOLE SET (never a
+ * per-link add/remove — the set is the unit of change). The hash covers
+ * title, body AND the link set, so a stale read of any of the three is
+ * refused. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`.
+ * Unknown plan or note id → 404. Returns the edited note plus the plan's
+ * latest notes page.
+ */
+export async function planUpdateNote(client, args) {
+    return client.request({
+        method: "PATCH",
+        path: `/${args.plan_id}/notes/${args.note_id}`,
+        basePath: PLANS_BASE_PATH,
+        body: {
+            content_hash: args.content_hash,
+            ...(args.title === undefined ? {} : { title: args.title }),
+            ...(args.body === undefined ? {} : { body: args.body }),
+            ...(args.card_ids === undefined ? {} : { card_ids: args.card_ids }),
+            ...(args.record_refs === undefined ? {} : { record_refs: args.record_refs }),
+            ...(args.section_ids === undefined ? {} : { section_ids: args.section_ids }),
+        },
+    });
+}
+/**
+ * Soft-delete a plan note, via `DELETE /api/plans/:plan_id/notes/:note_id`.
+ * `content_hash` MUST be the note's `contentHash` from your last read; a
+ * stale hash deletes nothing and returns the same `{error:
+ * "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}`
+ * shape `plan_update_note` uses. TAKES AN EXPLICIT `plan_id`, same reason as
+ * `plan_add_note`. Unknown plan, unknown note, or an already-deleted note →
+ * 404. Returns the plan's remaining latest notes page.
+ */
+export async function planDeleteNote(client, args) {
+    return client.request({
+        method: "DELETE",
+        path: `/${args.plan_id}/notes/${args.note_id}`,
+        basePath: PLANS_BASE_PATH,
+        body: { content_hash: args.content_hash },
+    });
+}
 // ---------------- failure_category_list / _create / _update (DX-2792) ----------------
 /**
  * DX-2792 (Failure evaluation 3/4) — wraps `src/dashboard/failure-categories-routes.ts`,

package/dist/index.js

@@ -101,7 +101,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
-import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -793,6 +793,32 @@ server.tool("plan_delete_record", 'Soft-delete a goal/rule/caveat of your connec
     record_id: z.number().int().positive().describe("The record id to delete."),
     content_hash: z.string().describe("The record's `contentHash` from your last read. Required."),
 }, async (args) => jsonResult(await planDeleteRecord(client, args)));
+server.tool("plan_add_note", "Write a milestone note to a plan's timeline, via POST /api/plans/:plan_id/notes (DX-2915). A note is a MILESTONE, not a log — write one for a card (or related group of cards) finishing, an important decision, or a meaningful goal/rule/caveat/architecture-section change; routine step progress stays a card comment, never a note. Terse tone: `title` at most 60 characters, `body` (the wrap-up) at most 250 (both 400 if too long, naming the limit and actual length). Links resolve on read into what they point at (a card's title, a record's ref+body, a section's title): an unknown card, an unparseable or foreign record ref, or an unknown or foreign section id is refused 400 naming exactly which one. A card link does NOT require the card to be a member of this plan; a record/section link MUST belong to THIS plan. `author` is stamped from your identity server-side — there is no field for it. TAKES AN EXPLICIT `plan_id` (like `plan_remove_card`/`plan_rename`), so a dispatched worker with no plan connection can still write. Unknown plan → 404. Returns the new note plus the plan's latest notes page.", {
+    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
+    title: z.string().min(1).describe("At most 60 characters."),
+    body: z.string().min(1).describe("The wrap-up, at most 250 characters."),
+    card_ids: z.array(z.string().min(1)).optional().describe("Card ids this note concerns, e.g. `[\"DX-2894\"]`."),
+    record_refs: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Goal/rule/caveat references this note announces, e.g. `[\"G-1\", \"R-3\", \"CAV-2\"]`."),
+    section_ids: z.array(z.number().int().positive()).optional().describe("Architecture section ids this note announces."),
+}, async (args) => jsonResult(await planAddNote(client, args)));
+server.tool("plan_update_note", 'Edit a plan note, via PATCH /api/plans/:plan_id/notes/:note_id (DX-2915). `content_hash` MUST be the note\'s `contentHash` from your last read; a mismatch writes NOTHING and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — merge into those and retry with `content_hash: currentHash`, never blindly. `title`/`body` are each optional and keep their stored value when omitted. The link fields (`card_ids`/`record_refs`/`section_ids`) are all-or-nothing AS A GROUP: omit all three to leave the stored link set untouched; send ANY one of them to REPLACE THE WHOLE SET — there is no per-link add/remove. The hash covers title, body AND the link set. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`. Unknown plan or note id → 404. Returns the edited note plus the plan\'s latest notes page.', {
+    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
+    note_id: z.number().int().positive().describe("The note id to edit."),
+    content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
+    title: z.string().min(1).optional().describe("New title, at most 60 characters. Omit to keep the stored title."),
+    body: z.string().min(1).optional().describe("New wrap-up, at most 250 characters. Omit to keep the stored body."),
+    card_ids: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with record_refs/section_ids)."),
+    record_refs: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with card_ids/section_ids)."),
+    section_ids: z.array(z.number().int().positive()).optional().describe("REPLACES the whole link set when sent (with card_ids/record_refs)."),
+}, async (args) => jsonResult(await planUpdateNote(client, args)));
+server.tool("plan_delete_note", 'Soft-delete a plan note, via DELETE /api/plans/:plan_id/notes/:note_id (DX-2915). `content_hash` must be the note\'s `contentHash` from your last read; a stale hash deletes nothing and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — the same shape `plan_update_note` uses. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`. Unknown plan, unknown note, or an already-deleted note → 404. Returns the plan\'s remaining latest notes page.', {
+    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
+    note_id: z.number().int().positive().describe("The note id to delete."),
+    content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
+}, async (args) => jsonResult(await planDeleteNote(client, args)));
 server.tool("plan_add_card", "Add an existing card to the plan this session is connected to, via POST /api/plans/mine/cards (DX-2683). The card may live on ANY board — that is what a plan is for. Idempotent: re-adding a card already on the plan is a no-op, not an error, and a card may sit in several plans at once. This adds MEMBERSHIP only; it never edits the card. TAKES NO PLAN ID: the plan is resolved from your connected session. Not connected → `{error: \"session_not_connected\"}`. Unknown card → 404. Returns the plan's full member list.", {
     card_id: z.string().min(1).describe("An existing card id, e.g. `DX-2683`."),
 }, async (args) => jsonResult(await planAddCard(client, args)));

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/package.json

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