@thehammer/danx-dashboard-mcp 0.1.86 → 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,13 +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";
 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;
@@ -98,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>...]]`;
 /**
@@ -121,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.
@@ -157,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) {
@@ -210,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" }) {
@@ -322,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)}` };
     }
@@ -353,60 +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) {
-        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;
+    let verified = false;
     for (;;) {
         const minted = await mintTicket(options, deps);
         if (minted.kind === "terminal")
@@ -416,13 +401,19 @@ 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 };
@@ -446,28 +437,12 @@ export async function runBridge(options, deps) {
         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;
@@ -476,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);
     }
 }

package/dist/handlers.js

@@ -392,11 +392,7 @@ export async function issueComment(client, args) {
         return client.request({
             method: "POST",
             path: `/${idEnc}/comments`,
-            body: {
-                text,
-                ...(args.metadata !== undefined ? { metadata: args.metadata } : {}),
-                ...(args.problem_id !== undefined ? { problem_id: args.problem_id } : {}),
-            },
+            body: { text, ...(args.metadata !== undefined ? { metadata: args.metadata } : {}) },
             board,
         });
     }
@@ -848,7 +844,6 @@ export const PLAN_FIELD_GROUPS = [
     "records:caveat",
     "architecture",
     "sessions",
-    "notes",
 ];
 /**
  * DX-2834 — the plan-status taxonomy, mirroring `PLAN_FIELD_GROUPS` just
@@ -1152,85 +1147,6 @@ 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

@@ -94,14 +94,13 @@
  */
 import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
-import { PLAN_STATE_SUBCOMMAND, runPlanStateCommand } from "./plan-state.js";
 import { resolveDeclaredCredential } from "./credential.js";
 import { recordSessionConnectionAfterConnect } from "./session-connection.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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, 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 { 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 { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -504,13 +503,12 @@ server.tool("issue_triage", "Record a triage confidence score via POST /api/issu
     ...boardField,
 }, async (args) => jsonResult(await issueTriage(client, args)));
 // ---------------- issue_comment ----------------
-server.tool("issue_comment", "Comment CRUD via /api/issues/:id/comments[/:cid]. action=add → POST {text, metadata?, problem_id?} (server stamps author from bearer + auto-incrementing ordinal); action=edit → PATCH /:cid {text}; action=delete → DELETE /:cid (soft-delete, audit trail preserved — comments are NEVER hard-deleted). Client-supplied author is IGNORED (server-stamped to prevent impersonation). `metadata` (DX-2157, action=add only) is an OPTIONAL opaque JSON object a calling app attaches to the comment — e.g. a generated `{sql, explanation}` packet its own UI renders specially. danxbot stores + returns it verbatim and enforces NO shape on its contents; omit for a plain markdown-only comment (unaffected either way). `problem_id` (DX-2906, action=add only) OPTIONALLY threads the comment as a follow-up question under one of this SAME card's problems (from `issue_problem` list/add) WITHOUT answering it — commenting never changes open_problem_count, blocked, or records a decision; use issue_problem's answer route for that. An unknown id, another card's id, or a removed problem's id all 404 naming the problem id — an ANSWERED (but not removed) problem still accepts a follow-up comment, since the thread continues after a decision.", {
+server.tool("issue_comment", "Comment CRUD via /api/issues/:id/comments[/:cid]. action=add → POST {text, metadata?} (server stamps author from bearer + auto-incrementing ordinal); action=edit → PATCH /:cid {text}; action=delete → DELETE /:cid (soft-delete, audit trail preserved — comments are NEVER hard-deleted). Client-supplied author is IGNORED (server-stamped to prevent impersonation). `metadata` (DX-2157, action=add only) is an OPTIONAL opaque JSON object a calling app attaches to the comment — e.g. a generated `{sql, explanation}` packet its own UI renders specially. danxbot stores + returns it verbatim and enforces NO shape on its contents; omit for a plain markdown-only comment (unaffected either way).", {
     id: z.string().min(1),
     action: z.enum(["add", "edit", "delete"]),
     comment_id: z.number().int().positive().optional(),
     text: z.string().min(1).optional(),
     metadata: z.record(z.unknown()).optional(),
-    problem_id: z.number().int().positive().optional().describe("action=add only — thread this comment as a follow-up under a LIVE problem of this same card, without answering it"),
     ...boardField,
 }, async (args) => jsonResult(await issueComment(client, args)));
 // ---------------- issue_checklist ----------------
@@ -794,32 +792,6 @@ 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)));
@@ -909,25 +881,16 @@ async function main() {
 // symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
 // spawns, not just a direct `node dist/index.js`.
 //
-// `bridge` and `plan-state` are the two subcommands. `bridge` is the session
-// event stream client the danxbot plugin's plan event bridge runs. It never
-// boots the MCP server; its only input is `CLAUDE_CODE_SESSION_ID` (read from
-// its environment) plus `--resume-ids` — the dashboard URL, credential source,
-// and credential itself come from the session-connection record this server's
-// own `plan_connect` wrote (`session-connection.ts`), never from the bridge's
-// own environment (DX-2862: a bridge trusting its own ambient
-// `DANXBOT_DISPATCH_TOKEN` is the exact bug this repo fixed).
-//
-// `plan-state` (DX-2921) is the ONE-SHOT client of
-// `GET /api/plan-sessions/me/turn-state`, run by the DX-2888 plugin's
-// turn-start / turn-end hooks — see `plan-state.ts`'s own doc comment for the
-// full contract. It ALWAYS exits 0 (success or failure alike: the hook must
-// stay silent), so even an unexpected rejection here is caught and reported
-// the same `{ok:false, reason}` way rather than propagating a non-zero exit
-// or an uncaught stack trace into the hook.
-//
-// Any OTHER argument is refused rather than ignored, so a typo cannot
-// silently start an MCP server on stdio where a subcommand was meant to run.
+// `bridge` is the one subcommand: the session event stream client the danxbot
+// plugin's plan event bridge runs. It never boots the MCP server; its only
+// input is `CLAUDE_CODE_SESSION_ID` (read from its environment) plus
+// `--resume-ids` — the dashboard URL, credential source, and credential itself
+// come from the session-connection record this server's own `plan_connect`
+// wrote (`session-connection.ts`), never from the bridge's own environment
+// (DX-2862: a bridge trusting its own ambient `DANXBOT_DISPATCH_TOKEN` is the
+// exact bug this repo fixed). Any OTHER argument is refused rather than
+// ignored, so a typo cannot silently start an MCP server on stdio where the
+// bridge was meant to run.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
     const [subcommand, ...rest] = process.argv.slice(2);
     if (subcommand === BRIDGE_SUBCOMMAND) {
@@ -936,16 +899,8 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(1);
         });
     }
-    else if (subcommand === PLAN_STATE_SUBCOMMAND) {
-        runPlanStateCommand(rest).then((code) => process.exit(code), (err) => {
-            console.error(`[danx-dashboard-mcp] plan-state fatal: ${err.message}`);
-            process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
-            process.exit(0);
-        });
-    }
     else if (subcommand !== undefined) {
-        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BRIDGE_SUBCOMMAND}" and "${PLAN_STATE_SUBCOMMAND}")`);
+        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is "${BRIDGE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/listen.js

@@ -11,31 +11,10 @@
  *   - `{type:"event", id, text}` — exactly one per event, the moment it arrives.
  *     `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 — which includes DX-2885's `nudge` frame
- *     (`formatNudgeLine`): it is advisory, re-derived fresh every tick by the
- *     dashboard's own keep-alive tick, and never replayed, so it rides this
- *     same shape with `id: null` rather than growing a THIRD output variant.
- *   - `{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.
+ *     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).
  *   - nothing for keep-alives, the connect marker, or a successful reconnect.
  *
  * RECONNECT AND RESUME. The stream drops whenever the dashboard restarts, and can
@@ -53,7 +32,6 @@
  * (`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;
@@ -95,18 +73,8 @@ export function invalidEventReason(value) {
     if (!isRecord(d))
         return "detail is not an object";
     switch (value.kind) {
-        case "comment_added": {
-            if (!isCappedText(d.excerpt))
-                return "detail.excerpt is not capped text";
-            // DX-2906 — `problem` is OPTIONAL (only present when the comment named
-            // one); absent is valid, but a present-and-malformed one is not.
-            if (d.problem === undefined)
-                return null;
-            const problem = d.problem;
-            return isRecord(problem) && typeof problem.id === "number" && isCappedText(problem.statement)
-                ? null
-                : "detail.problem is not {id, statement}";
-        }
+        case "comment_added":
+            return isCappedText(d.excerpt) ? null : "detail.excerpt is not capped text";
         case "solution_answered": {
             const problem = d.problem;
             if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
@@ -125,32 +93,6 @@ export function invalidEventReason(value) {
             }
             return null;
         }
-        // DX-2935 — the operator retracted a problem's answer with no new one yet.
-        case "problem_unanswered": {
-            const problem = d.problem;
-            if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
-                return "detail.problem is not {id, statement}";
-            }
-            return typeof d.decision_id === "number" ? null : "detail.decision_id is not a number";
-        }
-        // DX-2935 — the operator retracted a problem's answer AND recorded a new
-        // one, in one transaction — same either/or solution/freeform shape
-        // `solution_answered` carries, plus which decision was retracted.
-        case "problem_answer_changed": {
-            const problem = d.problem;
-            if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
-                return "detail.problem is not {id, statement}";
-            }
-            if (typeof d.retracted_decision_id !== "number")
-                return "detail.retracted_decision_id is not a number";
-            if (typeof d.decision_id !== "number")
-                return "detail.decision_id is not a number";
-            if (d.solution === null)
-                return isCappedText(d.freeform) ? null : "detail.freeform is not capped text";
-            if (!isRecord(d.solution) || typeof d.solution.title !== "string")
-                return "detail.solution is not {title, note}";
-            return d.solution.note === null || isCappedText(d.solution.note) ? null : "detail.solution.note is not capped text";
-        }
         case "blocked":
             return isCappedText(d.reason) ? null : "detail.reason is not capped text";
         default:
@@ -161,16 +103,8 @@ export function invalidEventReason(value) {
 function describe(event) {
     const d = event.detail;
     switch (event.kind) {
-        case "comment_added": {
-            // DX-2906 — a comment naming a problem (a follow-up question, without
-            // answering it) relays distinctly from a plain comment, so an agent
-            // listening to the stream can tell which of its open problems just
-            // got a reply.
-            const problem = d.problem;
-            if (problem === undefined)
-                return `${event.actor} commented: ${quoted(d.excerpt)}`;
-            return `${event.actor} commented on problem ${quoted(problem.statement)}: ${quoted(d.excerpt)}`;
-        }
+        case "comment_added":
+            return `${event.actor} commented: ${quoted(d.excerpt)}`;
         case "solution_answered": {
             // DX-2735: every answer answers ONE problem on a card that may carry several,
             // so the line names the problem — otherwise the agent cannot tell which of its
@@ -189,22 +123,6 @@ function describe(event) {
             const problem = d.problem;
             return `${event.actor} opened a problem: ${quoted(problem.statement)}`;
         }
-        case "problem_unanswered": {
-            // DX-2935 — MUST read as "a previous answer was withdrawn", never as a
-            // brand-new problem: a connected session that already acted on the
-            // retracted answer has to stop, not treat this as fresh work to start.
-            const problem = d.problem;
-            return `${event.actor} retracted the answer to ${quoted(problem.statement)}`;
-        }
-        case "problem_answer_changed": {
-            // DX-2935 — ONE line for the whole retract-and-reanswer (never two
-            // separate events), naming the statement so a listener with several
-            // open questions knows which one just moved.
-            const problem = d.problem;
-            const solution = d.solution;
-            const now = solution === null ? quoted(d.freeform) : `"${solution.title}"`;
-            return `${event.actor} changed the answer to ${quoted(problem.statement)}: now ${now}`;
-        }
         case "blocked":
             return `${event.actor} blocked the card: ${quoted(d.reason)}`;
         case "unblocked":
@@ -222,46 +140,6 @@ export function formatActivityLine(event) {
         throw new Error(`malformed activity event: ${invalid}`);
     return oneLine(`[${event.cardId} "${event.cardTitle}" ${event.boardId}] ${describe(event)}`);
 }
-function isNudgeCardRef(value) {
-    return isRecord(value) && typeof value.id === "string" && typeof value.title === "string";
-}
-function isNudgeCardRefArray(value) {
-    return Array.isArray(value) && value.every(isNudgeCardRef);
-}
-/** Why a nudge cannot be read, or `null` when it can — same checked-before-describing shape as `invalidEventReason`. */
-export function invalidNudgeReason(value) {
-    if (!isRecord(value))
-        return "the nudge is not an object";
-    if (typeof value.idleMinutes !== "number" || !Number.isFinite(value.idleMinutes)) {
-        return "idleMinutes is not a number";
-    }
-    if (!isNudgeCardRefArray(value.startable))
-        return "startable is not a {id,title}[] array";
-    if (!isNudgeCardRefArray(value.held))
-        return "held is not a {id,title}[] array";
-    return null;
-}
-function cardList(cards) {
-    return cards.map((c) => `${c.id} "${c.title}"`).join(", ");
-}
-/**
- * The one readable line for a nudge (DX-2885). Always names the actual
- * waiting cards — never a generic "keep going" — because that is the whole
- * point of the feature: a session that only sees "you're idle" learns
- * nothing a bare timer couldn't have told it. Always a single line; throws,
- * naming the fault, on a malformed nudge.
- */
-export function formatNudgeLine(event) {
-    const invalid = invalidNudgeReason(event);
-    if (invalid !== null)
-        throw new Error(`malformed nudge event: ${invalid}`);
-    const parts = [];
-    if (event.startable.length > 0)
-        parts.push(`startable: ${cardList(event.startable)}`);
-    if (event.held.length > 0)
-        parts.push(`held: ${cardList(event.held)}`);
-    return oneLine(`${LINE_PREFIX} this session has been idle ${event.idleMinutes}m with work waiting — ${parts.join("; ")}`);
-}
 /**
  * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
  * field-less blocks produce no message, which is what keeps them out of the output.
@@ -303,23 +181,6 @@ 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]);
 /**
@@ -340,85 +201,14 @@ export async function runListener(options, deps) {
     };
     for (const id of options.resumeIds.slice(-DELIVERED_ID_MEMORY))
         remember(id);
-    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 });
+    const stop = (reason, detail, code) => {
+        deps.write({ type: "stopped", reason, detail });
         return code;
-    }
+    };
     const handle = (message) => {
         if (message.event === "end") {
-            // 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 === "nudge") {
-            // DX-2885 — a nudge carries no usable id (it is advisory, re-derived
-            // fresh every tick, never replayed — see `plan-session-stream.ts`'s
-            // module doc), so it rides the SAME `{type:"event", id:null, text}`
-            // shape an ordinary activity line uses (`id` is `null` only for a frame
-            // that carried no usable id — a nudge is exactly that case). That is
-            // what lets `bridge.ts` and the plugin's relay
-            // (`danxbot/scripts/plan-event-bridge.mjs`, outside this repo) forward
-            // it with NO changes at all: both already forward any `{type:"event",
-            // id, text}` line generically, keyed only on `type`.
-            //
-            // DX-2885 — this frame must stay exempt from DX-2730 D4's digest-
-            // batching when that lands (see DX-2730 AC 29939, and the matching note
-            // at the dashboard's own emit site): it must keep delivering
-            // immediately, never held for a later digest flush.
-            let parsed;
-            let invalid;
-            try {
-                parsed = JSON.parse(message.data);
-                invalid = invalidNudgeReason(parsed);
-            }
-            catch (err) {
-                invalid = `not JSON: ${err.message}`;
-            }
-            const text = invalid === null
-                ? formatNudgeLine(parsed)
-                : `${LINE_PREFIX} could not read nudge (${invalid}): ${oneLine(message.data, 300)}`;
-            deps.write({ type: "event", id: null, text });
-            return null;
+            const reason = JSON.parse(message.data).reason;
+            return { kind: "ended", reason: typeof reason === "string" ? reason : "unknown" };
         }
         if (message.event !== "activity")
             return null;
@@ -472,25 +262,7 @@ 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)) {
-                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)}`,
-                };
+                return { kind: "refused", detail: `HTTP ${response.status} ${oneLine(await response.text(), 300)}` };
             }
             if (!response.ok || response.body === null) {
                 await response.body?.cancel();
@@ -524,23 +296,10 @@ 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, {
-                refusal: { status: outcome.status, errorCode: outcome.errorCode, body: outcome.body },
-            });
+            return stop("refused", `the dashboard refused the listener ticket: ${outcome.detail}`, 1);
         }
         if (outcome.healthy) {
             unhealthySince = null;

package/package.json

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

package/dist/json-body.js

@@ -1,23 +0,0 @@
-/**
- * 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/plan-state.js

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