@thehammer/danx-dashboard-mcp 0.1.87 → 0.1.88

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.
-- **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.
+- **Reach check.** After minting, `bridge` proves the credential can read every board the connected plan's cards live on (`GET /api/plans/mine?fields=cards`, then `GET /api/issues/:id/problems` for one card per board — the routes that run the same board-allowlist + `read` check the stream itself applies). A board it cannot read stops it with `board_unreadable` rather than streaming on and dropping that board's events. Then, once, `{"type":"ready","boards":[…]}`.
 - **Ticket.** `bridge` mints the session's listener ticket (`POST /api/plan-sessions/me/stream-ticket`, 10 s timeout) and keeps it in the process. A ticket authorizes reading that one session's event stream and nothing else, and is only issued while the session is connected to a plan. Minting a new one ends the previous listener.
 - **Output — JSON Lines.** One `{"type":"event","id":<id|null>,"text":"…"}` per event on the connected plan's cards, where `text` is `[DX-8 "Title" repo:board] newms87 answered "Which rollout order?": chose "Pause E2E" — note: "only this week"`, `… answered "…": "<free-form answer>"`, `… commented: "…"`, `… opened a problem: "…"`, `… blocked the card: "…"`, or `… unblocked the card`. An event it cannot read still produces one, with a `could not read event` text. Nothing for keep-alives, reconnects or re-mints. The session's own writes are never echoed back to it.
-- **Stopping.** Last, one `{"type":"stopped","reason":"…","detail":"…","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.
+- **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.
 - **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,59 +20,29 @@
  *      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. 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`.
+ *   4. VERIFIES THE REACH IT JUST BOUGHT: the credential must be able to read
+ *      every board the connected plan's cards live on, because the stream admits
+ *      an event only when the ticket issuer's board allowlist covers that
+ *      event's board (`isVisibleToStream`, dashboard). A board it cannot read is
+ *      a board whose events would vanish without a word, so it is a terminal,
+ *      named outcome instead.
  *   5. Streams through `runListener` (`listen.ts`), which reconnects within the
  *      ticket, and re-mints when that ticket's lease runs out or a fresh ticket
  *      is refused once.
- *   6. Writes JSON Lines to stdout: ONE `{type:"ready"}` 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.
+ *   6. Writes JSON Lines to stdout: ONE `{type:"ready", boards}` once the stream
+ *      is live and verified, `{type:"event", id, text}` per event, and ONE final
+ *      `{type:"stopped", reason, detail, fix}` before exiting.
  *
  * TERMINAL OUTCOMES — each ends the process with its stop record, never a retry:
  *   - `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, 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;
+ *   - `not_connected`         the mint answered 409 `session_not_connected`;
+ *   - `unauthorized`          the mint or a scope read answered 401 / 403;
  *   - `mint_refused`          any other non-transient mint refusal (400, 404, …);
  *   - `mint_bad_response`     a 2xx mint whose body is not a ticket;
- *   - `board_unreadable`      the 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);
+ *   - `board_unreadable`      the credential cannot read a board of this plan;
+ *   - `scope_check_failed`    the plan's boards could not be established;
  *   - `superseded` / `replaced` (exit 0) — another listener now holds the session;
  *   - `revoked`               the dashboard revoked the ticket or its issuer;
  *   - `refused`               freshly minted tickets were refused twice in a row.
@@ -84,78 +54,14 @@
  * 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";
-/**
- * DX-2730 D4 — WHICH EVENTS WAKE THE SESSION, NOW THAT EVERY ONE OF THEM CAN.
- *
- * Every `ListenEvent` carries the origin its writer set (`operator` / `agent` /
- * `machine`, or `null` for the idle-nudge exemption and an event this listener
- * could not parse — see `ListenEvent.origin`'s docblock in `listen.ts`). This
- * module is the ONLY place that decides what happens next:
- *
- *   - `operator` (a real human) and `null` (nudge / unreadable) emit AT ONCE,
- *     exactly as every event did before this card — a session must never wait
- *     to hear from the person it is working with, and a fault or a nudge must
- *     never be hidden behind a delay either.
- *   - `agent` and `machine` are HELD. Every dispatched agent's own writes and
- *     every server-side guard/reviewer/recovery write share this treatment:
- *     gate reviews, triage notes, auto-blocks. Held events are combined into
- *     ONE digest record, flushed the moment either `DIGEST_INTERVAL_MS`
- *     elapses with no operator event, or an operator event arrives (flushed
- *     just ahead of it, never after — a session must never read the digest
- *     as if it postdates the operator's own message).
- *
- * NOTHING HELD IS EVER DROPPED, AND NOTHING HELD IS EVER DOUBLE-DELIVERED
- * EITHER — across a full process restart OR a same-process re-mint. An id is
- * added to `delivered` (this run's own resume cursor, seeded from
- * `options.resumeIds` and handed to the next mint/re-mint as `--resume-ids`)
- * ONLY at the moment it is actually written to stdout — never at the moment it
- * is merely held. So a process that dies mid-hold has, by construction, never
- * marked those ids delivered: the next process starts from the SAME cursor,
- * the dashboard's replay resends exactly the events this process never
- * finished relaying, and they are held and flushed again there. This is "the
- * existing resumeIds/delivered-id cursor" the card's AC names — no new
- * persistence was needed, only NOT marking a held event delivered until it is
- * actually flushed.
- *
- * THE SAME REPLAY CAN ALSO ARRIVE WITHIN ONE STILL-RUNNING PROCESS, on a
- * same-process re-mint (a real `lease_expired`, not merely a dropped
- * connection): a fresh `runListener()` call starts a FRESH internal duplicate
- * guard, seeded only from the `resumeIds` this call hands it — and a held id
- * was, by the paragraph above, never in `delivered`. Left unhandled this
- * would let the SAME held event be counted into TWO digests once flushed
- * twice. `heldIds()` closes this: every `runListener()` call is seeded with
- * `[...delivered, ...heldIds()]`, so the fresh listener's own guard
- * (`listen.ts`'s `delivered` Set) already knows about a held id and silently
- * drops a replay of it before it ever reaches `routeEvent` again —
- * `routeEvent`'s own id check on `held` is the second, cheaper layer behind
- * that, for defense in depth.
- *
- * A digest record rides the exact same `{type:"event", id, text}` shape a
- * single event does (`id` is the highest id it combines, or `null` if every
- * combined event carried none) — the plugin that relays bridge output
- * (`plan-event-bridge.mjs`, outside this repo) already forwards any such
- * record generically, so a digest needs no change on that side.
- *
- * A REAL TIMER, NOT `deps.sleep`. Unlike every other timing decision in this
- * module (mint backoff, reconnect backoff), the digest interval is not tied to
- * stream activity — it must fire even while the stream sits idle between
- * events — so it is a plain `setTimeout`, mockable with fake timers in tests,
- * rather than routed through the deliberately stream-driven `deps.sleep`.
- */
-export const DIGEST_INTERVAL_MS = 10 * 60_000;
-const DIGEST_PREFIX = "[danx-dashboard bridge]";
-/** ONE combined record for every event held since the last flush. */
-function formatDigest(entries) {
-    const header = `${DIGEST_PREFIX} digest — ${entries.length} agent/machine event${entries.length === 1 ? "" : "s"} since the last update:`;
-    return [header, ...entries.map((e) => e.text)].join("\n");
-}
 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;
@@ -163,7 +69,10 @@ 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>...]]`;
 /**
@@ -186,11 +95,7 @@ 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",
-    // 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",
+    scope_check_failed: "check the dashboard is reachable and this session is connected to a plan, then call plan_connect again",
     // 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.
@@ -222,11 +127,6 @@ 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) {
@@ -275,43 +175,15 @@ export function resolveBridgeOptions(args, env, options = {}) {
         resumeIds: args.resumeIds,
     };
 }
-/**
- * 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";
+function errorCodeOf(body) {
+    return typeof body === "object" && body !== null && typeof body.error === "string"
+        ? body.error
+        : null;
 }
 /**
  * One authenticated request, with a timeout, classifying the failures that are
- * about THIS MOMENT (network, timeout, 408/429, 5xx) as transient. Shared by
- * every request this module makes so they can never disagree about which
+ * about THIS MOMENT (network, timeout, 408/429, 5xx) as transient. Shared by the
+ * mint and the board-reach check so the two can never disagree about which
  * failures are worth retrying.
  */
 async function request(options, deps, what, url, init = { method: "GET" }) {
@@ -387,19 +259,6 @@ 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)}` };
     }
@@ -418,145 +277,121 @@ 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 };
+}
 /**
- * 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:
+ * Prove this credential can read every board the connected plan's cards live on.
  *
- *   - `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 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".
  *
- * 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).
+ * 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.
  */
-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" };
+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;
     }
-    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"),
-        };
+    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)}`,
+            };
+        }
     }
-    return null;
+    return { kind: "ok", boards: [...firstCardPerBoard.keys()] };
 }
 /**
- * Mint, stream, re-mint — until a terminal outcome, which it writes as the one
- * `stopped` record. Returns 0 when another listener took over, 1 otherwise.
+ * Mint, verify, stream, re-mint — until a terminal outcome, which it writes as
+ * the one `stopped` record. Returns 0 when another listener took over, 1 otherwise.
  */
 export async function runBridge(options, deps) {
     const delivered = options.resumeIds.slice(-DELIVERED_ID_MEMORY);
-    function stop(reason, detail, code, extra) {
-        // DX-2730 D4 — every terminal return goes through here, so this is the ONE
-        // place that cancels a pending digest timer. CANCELLED, never flushed: for
-        // `superseded`/`replaced` a newer process is already streaming this same
-        // session and will receive (and hold, and eventually flush) these same
-        // held events itself via the dashboard's replay — flushing here too would
-        // double-deliver the digest. For every other terminal reason, whatever is
-        // still held was never marked delivered (see `emitNow`), so a future
-        // process picks it up the same way — a live, un-fired `setTimeout` would
-        // otherwise also keep this process's event loop alive for up to
-        // `DIGEST_INTERVAL_MS` after it should have exited.
-        if (digestTimer !== null) {
-            clearTimeout(digestTimer);
-            digestTimer = null;
-        }
-        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) });
+    const stop = (reason, detail, code) => {
+        deps.write({ type: "stopped", reason, detail, fix: fixForStop(reason) });
         return code;
-    }
+    };
     let backoff = MINT_INITIAL_BACKOFF_MS;
     let refusedInRow = 0;
-    let readyEmitted = false;
-    // DX-2730 D4 — digest state, declared OUTSIDE the mint/reconnect loop below
-    // so a re-mint (a lapsed lease, still the SAME process) never loses a
-    // pending hold — see the module docblock for the restart case, which the
-    // resume cursor handles instead.
-    let held = [];
-    let digestTimer = null;
-    function markDelivered(id) {
-        if (id === null)
-            return;
-        delivered.push(id);
-        if (delivered.length > DELIVERED_ID_MEMORY)
-            delivered.shift();
-    }
-    /** Write an event downstream at once, and mark its id delivered — never before now. */
-    function emitNow(output) {
-        markDelivered(output.id);
-        deps.write(output);
-    }
-    /** Combine every held event into ONE record and emit it, if there is anything to combine. */
-    function flushDigest() {
-        if (digestTimer !== null) {
-            clearTimeout(digestTimer);
-            digestTimer = null;
-        }
-        if (held.length === 0)
-            return;
-        const entries = held;
-        held = [];
-        const ids = entries.map((e) => e.id).filter((id) => id !== null);
-        emitNow({ type: "event", id: ids.length === 0 ? null : Math.max(...ids), text: formatDigest(entries), origin: null });
-    }
-    /** Every id currently held, unflushed — also fed back into the next `runListener` call's
-     *  `resumeIds` below, so a re-mint's fresh listener knows these were already seen and its
-     *  OWN duplicate guard (`listen.ts`'s `delivered` Set) silently drops a replay of one,
-     *  rather than it reaching here a second time. */
-    function heldIds() {
-        return held.map((e) => e.id).filter((id) => id !== null);
-    }
-    /**
-     * DX-2730 D4 — the ONE place that decides immediate vs. held-for-digest.
-     * `operator` and `null` (nudge / unreadable — see `ListenEvent.origin`'s
-     * docblock) flush any pending digest first (never let a digest arrive AFTER
-     * the operator event that should have superseded it) and then emit at once.
-     * `agent` / `machine` are appended to the hold, arming the interval timer
-     * only for the FIRST held event since the last flush — a later addition
-     * must never push the deadline out, or the "at most every 10 minutes"
-     * guarantee would erode into "10 minutes after the last event," which could
-     * never fire while events keep arriving.
-     *
-     * DEDUPED BY ID (defense in depth): a held event's id is not added to
-     * `delivered` until it is actually flushed (see `emitNow`), which is what
-     * lets a crashed-and-restarted PROCESS recover it via the dashboard's own
-     * replay. The same replay can also legitimately re-arrive WITHIN one still-
-     * running process — a re-mint after a real `lease_expired` starts a fresh
-     * `runListener` whose own duplicate guard is seeded from `resumeIds` alone,
-     * and a still-held id was never in `delivered` to seed it with. `resumeIds`
-     * below closes that for the ordinary case by handing the fresh listener
-     * every held id too; this check is the second, cheaper layer for anything
-     * that reaches here anyway — never trust a single guard to hold alone.
-     */
-    function routeEvent(output) {
-        if (output.origin === "agent" || output.origin === "machine") {
-            if (output.id !== null && heldIds().includes(output.id))
-                return;
-            held.push(output);
-            digestTimer ??= setTimeout(flushDigest, DIGEST_INTERVAL_MS);
-            return;
-        }
-        flushDigest();
-        emitNow(output);
-    }
+    let verified = false;
     for (;;) {
         const minted = await mintTicket(options, deps);
         if (minted.kind === "terminal")
@@ -566,29 +401,24 @@ export async function runBridge(options, deps) {
             backoff = Math.min(MINT_MAX_BACKOFF_MS, backoff * 2);
             continue;
         }
-        // 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" });
+        // The reach check runs on the FIRST ticket only: it is a property of the
+        // credential and the plan, and a re-mint (a lapsed lease) changes neither.
+        if (!verified) {
+            const scope = await verifyPlanBoardsReadable(options, deps);
+            if (scope.kind === "terminal")
+                return stop(scope.reason, scope.detail, 1);
+            if (scope.kind === "transient") {
+                await deps.sleep(backoff);
+                backoff = Math.min(MINT_MAX_BACKOFF_MS, backoff * 2);
+                continue;
+            }
+            verified = true;
+            deps.write({ type: "ready", boards: scope.boards });
         }
         backoff = MINT_INITIAL_BACKOFF_MS;
         const run = { stopped: null, emitted: false };
         const startedAt = deps.now();
-        await runListener(
-        // DX-2730 D4 — `heldIds()` rides along with `delivered`: a held-but-
-        // not-yet-flushed event was never added to `delivered` (see `emitNow`),
-        // so without this a fresh listener after a re-mint would not recognize
-        // a replay of it as already-seen and would hold (and eventually
-        // digest) it a second time. See `routeEvent`'s docblock. (If this
-        // combined list ever exceeded `DELIVERED_ID_MEMORY`, `runListener`'s own
-        // `slice(-DELIVERED_ID_MEMORY)` would evict the OLDEST entries first —
-        // i.e. `delivered`'s ids before `heldIds()`'s, which is the right order:
-        // a held id is always the more recent of the two and the one a near-
-        // term replay is actually likely to touch.)
-        { streamUrl: minted.streamUrl, ticket: minted.ticket, leaseMs: minted.leaseMs, resumeIds: [...delivered, ...heldIds()] }, {
+        await runListener({ streamUrl: minted.streamUrl, ticket: minted.ticket, leaseMs: minted.leaseMs, resumeIds: [...delivered] }, {
             ...deps,
             write: (output) => {
                 if (output.type === "stopped") {
@@ -596,34 +426,23 @@ export async function runBridge(options, deps) {
                     return;
                 }
                 run.emitted = true;
-                routeEvent(output);
+                if (output.id !== null) {
+                    delivered.push(output.id);
+                    if (delivered.length > DELIVERED_ID_MEMORY)
+                        delivered.shift();
+                }
+                deps.write(output);
             },
         });
         const stopped = run.stopped;
         if (stopped === null)
             throw new Error("the stream reader ended without a stop record");
-        // 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")
+        if (TAKEOVER_REASONS.has(stopped.reason))
             return stop(stopped.reason, stopped.detail, 0);
         if (stopped.reason === "lease_expired") {
             refusedInRow = 0;
             continue;
         }
-        if (stopped.reason === "refused") {
-            const 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;
@@ -632,15 +451,6 @@ 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);
     }
 }