@thehammer/danx-dashboard-mcp 0.1.88 → 0.1.90

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,78 @@
  * 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";
+import { capResumeIds, 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;
@@ -69,21 +163,27 @@ 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>...]]`;
 /**
  * The remedy per terminal reason THIS module knows about. ONE map, so the
  * message a session is shown and the message a log carries can never drift.
  * `satisfies` makes a reason missing its remedy a compile error here — but
- * `reason` can also arrive at runtime from the dashboard's own SSE end event
- * (`ListenStopped.reason` is an open string, not this union), so a build that
- * predates a newer dashboard reason still needs an honest, generic fallback
- * rather than an index miss: that is `DEFAULT_STOP_FIX`, reached only for a
- * reason genuinely outside this list, never for one of the reasons above.
+ * `KnownStopReason` above is only a SUBSET of `ListenStopReason` (DX-2920
+ * round 4 already made `ListenStopped.reason` a closed union, not a plain
+ * `string` — see `listen.ts`), and `ListenStopReason` itself has an `"unknown"`
+ * member for exactly a newer dashboard's wire reason this build predates
+ * (normalized there, never passed through raw). So a build older than the
+ * dashboard it talks to can still reach a real `ListenStopReason` value this
+ * map has no entry for. `fixForStop` below is deliberately typed to accept a
+ * plain `string`, wider than `ListenStopReason`, purely as defense in depth
+ * for a caller reached some other way (and what lets the forward-compat test
+ * below exercise the fallback with an arbitrary string) — every value that can
+ * actually reach it through `ListenStopped.reason` is already a real,
+ * compile-time-checked member of the closed union. `DEFAULT_STOP_FIX` is the
+ * honest, generic fallback for a reason genuinely outside this list, never a
+ * silent index miss.
  */
 export const STOP_FIXES = {
     no_connection_record: "call plan_connect again in this session — its danx-dashboard MCP server records the connection the bridge needs " +
@@ -95,7 +195,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 +231,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 +284,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 +396,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 +427,145 @@ 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) });
+    const delivered = capResumeIds(options.resumeIds);
+    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) });
         return code;
-    };
+    }
     let backoff = MINT_INITIAL_BACKOFF_MS;
     let refusedInRow = 0;
-    let verified = false;
+    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);
+    }
     for (;;) {
         const minted = await mintTicket(options, deps);
         if (minted.kind === "terminal")
@@ -401,24 +575,41 @@ 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 };
         const startedAt = deps.now();
-        await runListener({ streamUrl: minted.streamUrl, ticket: minted.ticket, leaseMs: minted.leaseMs, resumeIds: [...delivered] }, {
+        // DX-2829 — `runListener`'s own return value (0 for a benign takeover, 1
+        // otherwise) is intentionally discarded here, never reused as this
+        // function's exit code: `runBridge` computes ITS OWN exit code below from
+        // `stopped.reason` via the `stop()` helper above, because a bridge-level
+        // stop can happen for reasons `runListener` never sees at all (mint
+        // failures, the refused-ticket retry budget, `classifyAdmissionRefusal`'s
+        // reclassification) — `stop()` is the one place that has to decide the
+        // exit code for ALL of them, not just the stream-reader's own outcomes.
+        // Reusing `runListener`'s return value here would be redundant at best
+        // (the two happen to agree for `superseded`/`replaced`) and wrong at worst
+        // wherever a bridge-level reason diverges from the stream-level one it
+        // was built from.
+        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()] }, {
             ...deps,
             write: (output) => {
                 if (output.type === "stopped") {
@@ -426,23 +617,34 @@ export async function runBridge(options, deps) {
                     return;
                 }
                 run.emitted = true;
-                if (output.id !== null) {
-                    delivered.push(output.id);
-                    if (delivered.length > DELIVERED_ID_MEMORY)
-                        delivered.shift();
-                }
-                deps.write(output);
+                routeEvent(output);
             },
         });
         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 +653,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);
     }
 }