@thehammer/danx-dashboard-mcp 0.1.271 → 0.1.274

package/dist/bridge.js

@@ -1,1125 +0,0 @@
-/**
- * `danx-dashboard-mcp bridge [--resume-ids <event-id>[,<event-id>...]]` — the ONE
- * client of a working session's dashboard event stream.
- *
- * WHO RUNS IT. The danxbot Claude Code plugin's plan event bridge
- * (`danxbot/scripts/plan-event-bridge.mjs` in claude-plugins) spawns it once per
- * session and owns only process lifecycle, the delivered-id cursor, and posting
- * each event (and each failure) into the session's inbox. Everything about the
- * dashboard's HTTP contract lives HERE, next to the MCP server that already
- * speaks it, and is tested here.
- *
- * WHAT IT DOES.
- *   1. Reads `CLAUDE_CODE_SESSION_ID` from its environment and, for that
- *      session, the connection record the session's own MCP server wrote when
- *      it connected the plan (`session-connection.ts`): the dashboard URL, the
- *      credential's SOURCE, and the credential's FINGERPRINT.
- *   2. Resolves that same source through the same resolver the server used
- *      (`credential.ts`) and refuses to run unless the result fingerprints
- *      identically — DX-2862, where a bridge authenticated with a DIFFERENT
- *      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-3468 — board-coverage narrowing (`403 issuer_cannot_read_plan_boards`
- *      at mint or admission, mapped to `board_unreadable`; a live stream
- *      ending `scope_narrowed`) was removed as dead code: DX-3409 made every
- *      credential team-bound, so a plan session's issuer and every board its
- *      connected plan covers are always in the same team (see the dashboard's
- *      `plan-scope.ts` module banner). `409 session_not_connected` at mint
- *      AND at admission are both mapped to `not_connected`, and
- *      `end("not_connected")` covers the same failure once the stream is
- *      already live. 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, cardCount, degraded, inventoryError}`
- *      once a ticket has been minted and streaming is about to start —
- *      DX-2970's `fetchPlanInventory`, a single BEST-EFFORT (never a gate)
- *      read of the connected plan's real board/card counts, purely so a
- *      consumer can tell "healthy, connected plan has cards" apart from
- *      "degraded — the connected plan has no cards, or its inventory
- *      couldn't be read" instead of both reading as an absent/empty field —
- *      then `{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);
- *   - `plan_archived`         DX-3809 — the plan was archived or deleted while the
- *                              stream was live (`end("plan_archived")`);
- *   - `unauthorized`          the mint 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;
- *   - `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.
- * Transient failures (network, timeout, 408, 429, 5xx) back off and retry: the
- * process lives exactly as long as its session, and the plugin ends it.
- *
- * NEITHER THE ENVIRONMENT NOR ARGV CARRIES THE CREDENTIAL ANY MORE. `--resume-ids`
- * is the only argument and holds no secret; the credential is whatever this
- * session's own MCP server declared, resolved here from that declaration.
- */
-import { randomUUID } from "node:crypto";
-import { homedir } from "node:os";
-import { errorCodeOf } from "./json-body.js";
-import { keyRevocationOf, keyRevokedHalt } from "./key-revoked-halt.js";
-import { oneLine } from "./one-line.js";
-import { credentialFingerprint, describeCredentialSource, readCredential, } from "./credential.js";
-import { readSessionConnection, sessionConnectionPath } from "./session-connection.js";
-import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, READ_IDLE_TIMEOUT_MS, runListener, } from "./listen.js";
-import { isClaimState } from "@thehammer/danx-session-telemetry";
-import { OperatorSessionStats, transcriptPathFromEnv, } from "./session-stats.js";
-import { TranscriptTitleReader } from "./session-title.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";
-/**
- * DX-3912 — the longest heartbeat `reason` the bridge sends: one under the dashboard's own
- * limit (`HEARTBEAT_REASON_MAX_CHARS` = 200, `src/issues/db/plan-session-heartbeat.ts`),
- * because `oneLine` appends a "…" to a truncated string and a longer reason refuses the whole
- * heartbeat. `bridge.test.ts` asserts the cap.
- */
-const HEARTBEAT_REASON_MAX_CODE_POINTS = 199;
-export const STREAM_TICKET_PATH = "/api/plan-sessions/me/stream-ticket";
-// DX-2970 — the bare (no `fields=`) cheap-scalars read, used ONLY to report the
-// connected plan's real `boards`/`cardCount` on the `ready` record (see
-// `fetchPlanInventory`). This is NOT a revival of DX-2920's deleted
-// `verifyPlanBoardsReadable` gate — it never refuses a mint, never blocks
-// streaming, and is best-effort (one attempt, no retry/backoff).
-export const PLAN_MINE_PATH = "/api/plans/mine";
-export const SESSION_ID_HEADER = "x-danx-session-id";
-// DX-3028 (AC1) — `POST /api/plan-sessions/me/heartbeat` (DX-2952's server
-// route, `plan-sessions-routes.ts#handleHeartbeat`). Every 15s this process
-// reports its truthful streaming state; see `sendHeartbeat` below.
-export const HEARTBEAT_PATH = "/api/plan-sessions/me/heartbeat";
-/** How long one dashboard request may take before it counts as a transient failure. */
-export const REQUEST_TIMEOUT_MS = 10_000;
-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;
-/** DX-3028 (AC1) — the dashboard's own heartbeat cadence; see the card's AC1. */
-export const HEARTBEAT_INTERVAL_MS = 15_000;
-/** DX-3028 (AC2) — the server-fixable degraded reasons' own periodic retry cadence. */
-export const DEGRADED_RETRY_INTERVAL_MS = 5 * 60_000;
-/**
- * DX-3099 — how many consecutive 15s heartbeat POSTs may fail to LAND
- * (network error, timeout, 5xx, 408/429 — never an ordinary 401/403 answer,
- * which proves the pipe itself still works) while this process still
- * believes it is `"streaming"`, before that counts as evidence the current
- * stream connection is dead without having errored — the exact "alive but
- * not reporting" signature the investigation found: the SSE connection can
- * read as established at the OS level and never trip `listen.ts`'s own
- * read-idle timeout, while every outbound heartbeat silently never lands
- * (the send call's own result used to be discarded entirely — see the
- * card). `3 * HEARTBEAT_INTERVAL_MS` = 45s, deliberately UNDER
- * `SESSION_LIVENESS_WINDOW_MS` (60s, `plan-session-heartbeat.ts`) so this
- * process self-heals before, or right around, the moment the dashboard
- * would itself start reporting the session `unattached` — never a shorter
- * freshness window (that constant is untouched) and never a blind
- * "restart more eagerly" (no external watchdog, no timer-driven kill): this
- * fires only on repeated, OBSERVED delivery failure, self-diagnosed by the
- * SAME process that is already streaming. Card: DX-3099 (AC3 forbids both
- * of the obvious wrong fixes this constant is not).
- */
-export const HEARTBEAT_SILENT_FAILURE_THRESHOLD = 3;
-const TRANSIENT_CLIENT_STATUSES = new Set([408, 429]);
-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
- * `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 " +
-        "(a server older than the one that introduced the record writes none)",
-    credential_unavailable: "call plan_connect again to request access: this session's key file is missing or unreadable",
-    credential_mismatch: "restart this Claude Code session so its MCP server and its bridge pick up the same credential, then call plan_connect again",
-    not_connected: "call plan_connect to connect this session to a plan",
-    plan_archived: "the plan was archived or deleted, so this session was disconnected; ask the operator to restore it, then call plan_connect again",
-    unauthorized: "the dashboard no longer accepts this session's key (it lapsed after a day unused): call plan_connect again to request access",
-    key_revoked: "stop all work now, commit your work in progress and end this session: the person who owns this session's access revoked it; " +
-        "do not call plan_connect or request access again",
-    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",
-    // 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.
-    superseded: "no action needed — a newer ticket was minted for this session, and a fresh bridge is already using it",
-    replaced: "no action needed — another connection is already using this session's ticket; call plan_connect again only if that was unexpected",
-    revoked: "call plan_connect again to mint a new listener ticket for this session",
-    refused: "call plan_connect again to mint a new listener ticket for this session",
-    // DX-3028 — this session id belongs to a worker dispatch, not an operator
-    // plan session; there is no listener ticket a worker session can ever use.
-    session_is_worker: "this session id belongs to a worker dispatch; start a new session",
-};
-export const DEFAULT_STOP_FIX = "call plan_connect again in this session to restart the bridge";
-export function fixForStop(reason) {
-    return STOP_FIXES[reason] ?? DEFAULT_STOP_FIX;
-}
-function positiveInteger(raw) {
-    const n = Number(raw);
-    return Number.isSafeInteger(n) && n > 0 && String(n) === raw ? n : null;
-}
-/** Parse the one optional flag and the one required environment value; anything else is refused. */
-export function parseBridgeArgs(argv, env) {
-    const withResume = argv.length === 2 && argv[0] === "--resume-ids" && argv[1] !== "";
-    if (argv.length !== 0 && !withResume)
-        throw new Error(USAGE);
-    const sessionId = env.CLAUDE_CODE_SESSION_ID;
-    if (!sessionId)
-        throw new Error(USAGE);
-    const resumeIds = withResume ? argv[1].split(",").map(positiveInteger) : [];
-    if (resumeIds.some((id) => id === null))
-        throw new Error(USAGE);
-    const parsed = { sessionId, resumeIds: resumeIds };
-    const transcriptPath = transcriptPathFromEnv(env);
-    if (transcriptPath !== null)
-        parsed.transcriptPath = transcriptPath;
-    return parsed;
-}
-/** 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` (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;
-    /** DX-3028 — see `BridgeOptions.instanceId`. Always populated: minted before any of the three start-time checks run. */
-    instanceId;
-    /** DX-3028 — see `BridgeOptions.watchedPaths`. Empty for `no_connection_record` (there is nothing to watch yet). */
-    paths;
-    constructor(reason, detail, fix, instanceId, paths) {
-        super(detail);
-        this.name = "BridgeStartError";
-        this.reason = reason;
-        this.fix = fix;
-        this.instanceId = instanceId;
-        this.paths = paths;
-    }
-}
-/**
- * The session's connection, as its own MCP server recorded it — and the proof
- * that this process holds the SAME credential that server does. Never falls back
- * to an ambient env credential: that fallback is precisely DX-2862.
- */
-const INSTANCE_ID_ENV = "DANX_BRIDGE_INSTANCE_ID";
-/**
- * DX-3028 — this process's own instance id: read from `DANX_BRIDGE_INSTANCE_ID`
- * (minted by the plugin's `start()` before it spawns the run process, and
- * carried down to this subcommand's env unchanged), or freshly minted for a
- * manual/hand run that has no plugin supplying one. Every stop record and
- * every heartbeat names this same id for the life of the process.
- */
-function resolveInstanceId(env) {
-    const declared = env[INSTANCE_ID_ENV];
-    return typeof declared === "string" && declared.trim() !== "" ? declared.trim() : randomUUID();
-}
-/**
- * DX-3028 — the on-disk paths this bridge's authentication depends on, for
- * `BridgeOptions.watchedPaths` (see its docblock). A `session-key`
- * credential adds its own path; an `env`-sourced one has no file
- * (`credential.ts` ~47-48, ~90-95).
- */
-function watchedPathsFor(record, home) {
-    const paths = [sessionConnectionPath(record.sessionId, home)];
-    if (record.source.kind === "session-key")
-        paths.push(record.source.path);
-    return paths;
-}
-export function resolveBridgeOptions(args, env, options = {}) {
-    const home = options.home ?? homedir();
-    const instanceId = resolveInstanceId(env);
-    let record;
-    try {
-        record = readSessionConnection(args.sessionId, { home });
-    }
-    catch (err) {
-        throw new BridgeStartError("no_connection_record", err.message, fixForStop("no_connection_record"), instanceId, []);
-    }
-    if (record === null) {
-        throw new BridgeStartError("no_connection_record", `session ${args.sessionId} has no dashboard connection record — no danx-dashboard MCP server has connected it to a plan`, fixForStop("no_connection_record"), instanceId, []);
-    }
-    // DX-3028 — computed as soon as a connection record exists, even if the
-    // credential itself later fails to resolve: `credential_unavailable`'s own
-    // stop record still needs `paths` (the connection record path, at least)
-    // so the plugin has something to watch for a retry.
-    const watchedPaths = watchedPathsFor(record, home);
-    let token;
-    try {
-        token = readCredential(record.source, env);
-    }
-    catch (err) {
-        const credentialError = err;
-        throw new BridgeStartError("credential_unavailable", `the credential this session's danx-dashboard MCP server declared cannot be resolved here: ${credentialError.message}`, 
-        // CredentialError.fix is a required string, never absent — no fallback needed.
-        credentialError.fix, instanceId, watchedPaths);
-    }
-    const fingerprint = credentialFingerprint(token);
-    if (fingerprint !== record.fingerprint) {
-        throw new BridgeStartError("credential_mismatch", `${describeCredentialSource(record.source)} now yields credential ${fingerprint}, but this session's ` +
-            `danx-dashboard MCP server is using ${record.fingerprint} — the bridge would authenticate as somebody else`, fixForStop("credential_mismatch"), instanceId, watchedPaths);
-    }
-    return {
-        dashboardUrl: record.dashboardUrl.replace(/\/+$/, ""),
-        token,
-        sessionId: args.sessionId,
-        resumeIds: args.resumeIds,
-        instanceId,
-        watchedPaths,
-        ...(args.transcriptPath !== undefined ? { transcriptPath: args.transcriptPath } : {}),
-    };
-}
-/**
- * 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
- * failures are worth retrying.
- */
-async function request(options, deps, what, url, init = { method: "GET" }) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
-    try {
-        let status;
-        let text;
-        try {
-            const headers = {
-                Authorization: `Bearer ${options.token}`,
-                Accept: "application/json",
-                [SESSION_ID_HEADER]: options.sessionId,
-            };
-            if (init.body !== undefined)
-                headers["Content-Type"] = "application/json";
-            const response = await deps.fetch(url, {
-                method: init.method,
-                headers,
-                body: init.body,
-                signal: controller.signal,
-            });
-            status = response.status;
-            text = await response.text();
-        }
-        catch (err) {
-            return {
-                kind: "transient",
-                detail: controller.signal.aborted
-                    ? `${what} timed out after ${deps.requestTimeoutMs} ms`
-                    : `${what} failed: ${err.message}`,
-            };
-        }
-        if (status >= 500 || TRANSIENT_CLIENT_STATUSES.has(status)) {
-            return { kind: "transient", detail: `${what} HTTP ${status}` };
-        }
-        let body = null;
-        try {
-            body = text === "" ? null : JSON.parse(text);
-        }
-        catch {
-            body = null;
-        }
-        return { kind: "answer", status, text, body };
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-/** What is wrong with a 2xx mint body, or `null` when it is a ticket. Never echoes the body. */
-function badTicketReason(body) {
-    if (typeof body !== "object" || body === null)
-        return "the body is not a JSON object";
-    const b = body;
-    if (typeof b.ticket !== "string" || b.ticket === "")
-        return "ticket is not a non-empty string";
-    if (typeof b.streamPath !== "string" || !b.streamPath.startsWith("/"))
-        return "streamPath is not a path";
-    if (typeof b.leaseMs !== "number" || !Number.isSafeInteger(b.leaseMs) || b.leaseMs <= 0) {
-        return "leaseMs is not a positive integer";
-    }
-    return null;
-}
-/** Mint this session's listener ticket, classifying every way that can end. */
-export async function mintTicket(options, deps) {
-    const outcome = await request(options, deps, "ticket mint", `${options.dashboardUrl}${STREAM_TICKET_PATH}`, {
-        method: "POST",
-        body: "{}",
-    });
-    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" };
-    }
-    // DX-3028 (AC2) — matched BEFORE the generic mint_refused fallback below,
-    // which every other 409 falls into: this session id belongs to a worker
-    // dispatch (`SessionIsWorkerError`, the same shape the heartbeat route
-    // already gives it, DX-2952).
-    if (status === 409 && errorCodeOf(body) === "session_is_worker") {
-        return { kind: "terminal", reason: "session_is_worker", detail: "this session id belongs to a worker dispatch, not an operator plan session" };
-    }
-    // DX-4418 - a key a person revoked is not a lapsed one: the detail IS the stop halt (who revoked it, what to do), so the record
-    // the plugin relays to the session says it in full.
-    const revocation = keyRevocationOf({ ok: false, status, body });
-    if (revocation !== null) {
-        return { kind: "terminal", reason: "key_revoked", detail: keyRevokedHalt(revocation, false) };
-    }
-    if (status === 401 || status === 403) {
-        return { kind: "terminal", reason: "unauthorized", detail: `ticket mint HTTP ${status} ${oneLine(text, 300)}` };
-    }
-    if (status < 200 || status >= 300) {
-        return { kind: "terminal", reason: "mint_refused", detail: `ticket mint HTTP ${status} ${oneLine(text, 300)}` };
-    }
-    const bad = badTicketReason(body);
-    if (bad !== null) {
-        return { kind: "terminal", reason: "mint_bad_response", detail: `ticket mint HTTP ${status}: ${bad}` };
-    }
-    const ticket = body;
-    return {
-        kind: "ticket",
-        ticket: ticket.ticket,
-        streamUrl: `${options.dashboardUrl}${ticket.streamPath}`,
-        leaseMs: ticket.leaseMs,
-    };
-}
-/**
- * What is wrong with a 2xx bare `/api/plans/mine` body, or `null` when it carries a usable inventory.
- *
- * DX-3912 — the field names here are the plan resource's WIRE names (`boards`, `card_count`,
- * snake_case since DX-3428), the same ones `src/resources/plan/plan-resource.ts` emits; the
- * contract test `src/issues/__tests__/plan-inventory-bridge-contract.test.ts` runs this parser
- * on the server's own response, so a rename there fails that test instead of silently
- * degrading every bridge. A missing field lists the keys the body DID carry, so a rename is
- * named in the first message anyone reads.
- */
-function badInventoryReason(body) {
-    if (!isRecord(body))
-        return "the body is not a JSON object";
-    if (!("boards" in body))
-        return `boards is missing (response keys: ${Object.keys(body).join(", ")})`;
-    if (!Array.isArray(body.boards) || body.boards.some((x) => typeof x !== "string")) {
-        return "boards is not an array of strings";
-    }
-    if (!("card_count" in body))
-        return `card_count is missing (response keys: ${Object.keys(body).join(", ")})`;
-    const count = body.card_count;
-    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) {
-        return `card_count is not a non-negative integer (got ${typeof count === "number" ? count : typeof count})`;
-    }
-    return null;
-}
-/**
- * DX-2970 — a single BEST-EFFORT read of the connected plan's real
- * `boards`/`cardCount`, purely for accurate `ready`-record reporting. NEVER a
- * gate: unlike DX-2920's deleted `verifyPlanBoardsReadable`, a failure here
- * (network, timeout, non-2xx, unusable body) is NOT retried and NEVER blocks
- * or delays streaming — `runBridge` reports `degraded: true` with `boards`/
- * `cardCount` both `null` and proceeds exactly as it would have before this
- * read existed. The bare (no `fields=`) call is deliberately the cheapest
- * read the route offers — the plan's own "cheap scalars," always present on
- * every `GET /api/plans/mine` response regardless of `fields`.
- */
-export async function fetchPlanInventory(options, deps) {
-    const outcome = await request(options, deps, "plan inventory read", `${options.dashboardUrl}${PLAN_MINE_PATH}`);
-    if (outcome.kind === "transient")
-        return { kind: "unavailable", detail: outcome.detail };
-    const { status, text, body } = outcome;
-    if (status < 200 || status >= 300) {
-        return { kind: "unavailable", detail: `plan inventory read HTTP ${status} ${oneLine(text, 300)}` };
-    }
-    const bad = badInventoryReason(body);
-    if (bad !== null) {
-        return { kind: "unavailable", detail: `plan inventory read HTTP ${status}: ${bad}` };
-    }
-    const b = body;
-    return { kind: "ok", boards: b.boards, cardCount: b.card_count };
-}
-/**
- * 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: `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.
- *
- * 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).
- */
-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" };
-    }
-    return null;
-}
-// DX-3028 (code-review + architecture-review finding) — typed against
-// `ListenStopReason` (see that type's own docblock), NOT bare `Set<string>`:
-// a typo'd member here used to have zero compile-time signal, silently
-// falling into the generic `degrade-server-fixable` default below — exactly
-// the kind of drift this safety-critical classification can least afford.
-// `satisfies readonly ListenStopReason[]` on each array is what makes a typo
-// a build error.
-const EXIT_NEVER_RESTART_LIST = [
-    "no_connection_record",
-    "not_connected",
-    "plan_archived",
-    "superseded",
-    "replaced",
-    "session_is_worker",
-    // DX-4418 - a person revoked the key: the session stops for good, nothing retries.
-    "key_revoked",
-];
-const EXIT_NEVER_RESTART = new Set(EXIT_NEVER_RESTART_LIST);
-const DEGRADE_NO_HEARTBEAT_LIST = ["credential_unavailable", "credential_mismatch"];
-const DEGRADE_NO_HEARTBEAT = new Set(DEGRADE_NO_HEARTBEAT_LIST);
-export function degradePolicyFor(reason) {
-    if (EXIT_NEVER_RESTART.has(reason))
-        return "exit";
-    if (DEGRADE_NO_HEARTBEAT.has(reason))
-        return "degrade-no-heartbeat";
-    return "degrade-server-fixable";
-}
-/**
- * One heartbeat POST. Never throws on a failure of the request itself and NEVER stops the bridge on one
- * (the one throw is a contract breach: a `key_revoked` answer that does not say who revoked the key, DX-4418; `heartbeatTick`'s
- * `.catch` keeps it from taking the bridge down) (card AC1 — "a failed heartbeat never stops the bridge"): `request()`
- * itself already classifies every network/timeout/5xx failure as
- * `{kind:"transient"}` rather than throwing, and a 401/403 (a revoked
- * credential) simply comes back as an ordinary non-2xx answer this function
- * discards — there is nothing meaningful to retry a heartbeat POST for, and
- * the NEXT tick will just try again. A heartbeat refused with 401/403 cannot
- * report itself, so `computeListenerHealth`'s staleness fallback
- * (`heartbeatIsFresh`) is what eventually reflects it: the row's
- * `last_heartbeat_at` stops advancing, and once it falls outside
- * `SESSION_LIVENESS_WINDOW_MS` the badge reads `unattached`, NOT
- * `credential_mismatch` — `credential_mismatch` is computed only from a
- * heartbeat that DID land with `state:"streaming"` and a live ticket whose
- * issuer hash differs from the caller's; it has no way to represent "the
- * heartbeat call itself was rejected". This gap is real and is recorded on
- * the card rather than silently papered over.
- */
-async function sendHeartbeat(options, deps, connection, stats, 
-// DX-4461 - the session's current Claude title, read from its transcript (`session-title.ts`).
-title) {
-    const body = { state: connection.state };
-    if (connection.reason !== undefined)
-        body.reason = connection.reason;
-    if (connection.inventory !== undefined)
-        body.inventory = connection.inventory;
-    const outcome = await request(options, deps, "heartbeat", `${options.dashboardUrl}${HEARTBEAT_PATH}`, {
-        method: "POST",
-        body: JSON.stringify({ connection: body, ...(stats !== undefined ? { stats } : {}), ...(title !== undefined ? { title } : {}) }),
-    });
-    // DX-3099 — this is now the ONE place a heartbeat's own outcome is
-    // inspected. `request()` still never throws, and a 401/403 is still an
-    // ordinary answer this function does not retry for (the credential is
-    // whatever it is; there is nothing to redo about THIS request) — only a
-    // "transient" outcome (network error, timeout, 5xx, 408/429) means the
-    // request never landed at all, which is exactly the signal the silent-
-    // failure counter in `runBridge` below needs. Still never throws.
-    if (outcome.kind !== "answer")
-        return { landed: false, status: null, stats: null, revocation: null, title: null };
-    // DX-2954 — the answer's `stats` (the operator dispatch's stored or
-    // just-written totals and cursors) feed the session's stats collector.
-    const ok = outcome.status >= 200 && outcome.status < 300;
-    // A heartbeat whose carried stats were NOT applied (`statsError`) still
-    // landed; its `stats` are the stored values, so the collector must re-queue
-    // rather than treat them as the answer to its write.
-    const applied = ok && isRecord(outcome.body) && outcome.body.statsError === undefined;
-    const statsBody = applied && isRecord(outcome.body) && isRecord(outcome.body.stats) ? outcome.body.stats : null;
-    // DX-3962: an answer from a server that predates attribution stores cursors with no `claims`. Treated exactly like
-    // an answer with no stats (the older-server path): the collector never starts, the heartbeat still lands, and
-    // nothing is recorded until the server is deployed. Handing it on would crash the collector at attach.
-    const answered = statsBody !== null &&
-        isRecord(statsBody.sourceCursors) &&
-        isRecord(statsBody.totals) &&
-        Object.values(statsBody.sourceCursors).every((cursor) => isRecord(cursor) && isClaimState(cursor.claims))
-        ? statsBody
-        : null;
-    // DX-4418 - the dashboard refuses the beat of a session whose key a person revoked, and says so.
-    // DX-4461 - the dashboard's stored title for this session; an answer without one is an older dashboard's.
-    const storedTitle = ok && isRecord(outcome.body) && typeof outcome.body.title === "string" ? outcome.body.title : null;
-    return {
-        landed: true,
-        status: outcome.status,
-        stats: answered,
-        revocation: keyRevocationOf({ ok: false, status: outcome.status, body: outcome.body }),
-        title: storedTitle,
-    };
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/**
- * 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 = capResumeIds(options.resumeIds);
-    // DX-3028 (AC1) — this process's own truthful state, reported every
-    // HEARTBEAT_INTERVAL_MS regardless of what the mint/stream loop is doing.
-    // `onState` (threaded into `runListener` below) is the ONLY thing that ever
-    // sets "streaming"; everything else (mint backoff, degraded idling) is
-    // "reconnecting" or "stopped". `heartbeatSuppressed` covers the two
-    // start-time-unauthenticatable degrade reasons (card AC2): the process has
-    // no credential it can report WITH, so it sends nothing at all rather than
-    // an unauthenticated POST that would just be refused.
-    let connectionState = "reconnecting";
-    let stoppedReason = null;
-    let heartbeatSuppressed = false;
-    // DX-3912 — `null` is "the inventory read succeeded"; a string is why it did not.
-    let lastInventoryError = null;
-    // DX-3099 — consecutive heartbeat POSTs that failed to LAND while this
-    // process still believed `connectionState === "streaming"`. Reset to 0 the
-    // moment a heartbeat lands, or the moment state leaves "streaming" for any
-    // other reason (a fresh connect cycle earns a clean slate — see the `for
-    // (;;)` loop below). `forceReconnect` is the CURRENT connectOnce attempt's
-    // own abort, supplied fresh by `listen.ts` on every attempt via
-    // `onConnectionAttempt` below; calling it after that attempt has already
-    // ended is a harmless no-op.
-    let heartbeatFailureStreak = 0;
-    // DX-4418 - the stop notice for a revoked key goes out once; every later beat is refused the same way.
-    let revocationAnnounced = false;
-    let forceReconnect = null;
-    // DX-2954 — the session's stats ride this same heartbeat. Created ONCE per
-    // process, so an in-process re-mint never touches its state.
-    const sessionStats = new OperatorSessionStats(options.transcriptPath ?? null, deps.makeStatsWatcher);
-    const connectionNow = () => connectionState === "streaming"
-        ? lastInventoryError === null
-            ? { state: "streaming", inventory: "ok" }
-            : { state: "streaming", inventory: "unavailable", reason: oneLine(lastInventoryError, HEARTBEAT_REASON_MAX_CODE_POINTS) }
-        : connectionState === "stopped"
-            ? { state: "stopped", reason: stoppedReason ?? undefined }
-            : { state: "reconnecting" };
-    // DX-4461 - a rename reaches the dashboard without the agent: the title in the session's transcript rides the heartbeat
-    // when it differs from the one the dashboard last answered with. Only the LATEST landed answer counts: one without a
-    // title (an older dashboard, including one rolled back to mid-session, or a refusal) stops the title until an answer
-    // carries one again, since an older dashboard refuses the `title` key and a refused heartbeat is a dead listener.
-    const titleReader = options.transcriptPath !== undefined ? new TranscriptTitleReader(options.transcriptPath) : null;
-    let dashboardTitle;
-    let lastTitleError = null;
-    const titleToReport = () => {
-        if (titleReader === null || dashboardTitle === undefined)
-            return undefined;
-        // The title is cosmetic and the heartbeat is liveness: a transcript the title cannot be read from costs the title
-        // (said once per distinct failure), never the beat.
-        try {
-            const title = titleReader.read();
-            lastTitleError = null;
-            return title !== null && title !== dashboardTitle ? title : undefined;
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            if (message !== lastTitleError)
-                process.stderr.write(`session title: ${message}\n`);
-            lastTitleError = message;
-            return undefined;
-        }
-    };
-    const heartbeatTick = () => {
-        if (heartbeatSuppressed)
-            return;
-        const title = titleToReport();
-        void sessionStats.tick(async (stats) => {
-            const answer = await sendHeartbeat(options, deps, connectionNow(), stats, title);
-            if (answer.landed)
-                dashboardTitle = answer.title ?? undefined;
-            // DX-4418 - a person revoked this session's key: tell the session to stop, at once and only once, as an ordinary event
-            // line (the same delivery the silent-failure notice below uses). Its next dashboard call says the same.
-            if (answer.revocation !== null && !revocationAnnounced) {
-                revocationAnnounced = true;
-                routeEvent({ type: "event", id: null, text: keyRevokedHalt(answer.revocation, false), origin: null });
-            }
-            return answer;
-        }).then((landed) => {
-            // DX-3099 — only counts while THIS process still believes it is
-            // streaming: that is the exact desync the card found (the client
-            // believes it is fine; the dashboard has nothing recent for it). A
-            // failure while reconnecting/degraded is not new information — the
-            // existing mint-backoff / degrade-retry machinery already owns
-            // recovery there.
-            if (connectionState !== "streaming" || landed) {
-                heartbeatFailureStreak = 0;
-                return;
-            }
-            heartbeatFailureStreak += 1;
-            if (heartbeatFailureStreak < HEARTBEAT_SILENT_FAILURE_THRESHOLD)
-                return;
-            heartbeatFailureStreak = 0;
-            // AC4 — the session finds out, rather than continuing to believe it is
-            // connected: an ordinary event line, delivered immediately (`origin:
-            // null` skips D4's agent/machine hold — see `routeEvent`'s docblock),
-            // which the plugin already relays into the session's inbox unchanged
-            // (see this module's own docblock).
-            routeEvent({
-                type: "event",
-                id: null,
-                text: oneLine(`${DIGEST_PREFIX} this session's listener stopped reaching the dashboard for ` +
-                    `${Math.round((HEARTBEAT_SILENT_FAILURE_THRESHOLD * HEARTBEAT_INTERVAL_MS) / 1000)}s while it still ` +
-                    `believed it was streaming — forcing a fresh connection now.`),
-                origin: null,
-            });
-            // AC2 — force the CURRENT connectOnce attempt to end now, rather than
-            // wait on listen.ts's own read-idle timeout (which this exact failure
-            // mode can outlive indefinitely — see the card: the connection reads
-            // as established and never stops producing keep-alive bytes on the
-            // read side, only the outbound heartbeat silently never lands). The
-            // new attempt reconnects with the SAME ticket; the dashboard's own
-            // "ONE OPEN STREAM PER TICKET" rule (`attachListener`,
-            // `plan-session-listeners.ts`) then tells the OLD, now-superseded
-            // registry entry to end (`"replaced"`) — which is what actually
-            // releases the exclusive claim, as a natural side effect of THIS SAME
-            // PROCESS reconnecting, never an external watchdog and never a second
-            // process racing the first.
-            forceReconnect?.();
-        }).catch((err) => {
-            // DX-3962: a stats failure must never take the bridge down. `heartbeatTick` is fired without being awaited, so
-            // a throw here would be an unhandled rejection that kills the process and with it the session's plan events.
-            process.stderr.write(`operator session stats: heartbeat tick failed: ${err instanceof Error ? err.message : String(err)}\n`);
-        });
-    };
-    const heartbeat = deps.scheduleInterval(heartbeatTick, HEARTBEAT_INTERVAL_MS);
-    async function settle(reason, detail, code, extra) {
-        // DX-2730 D4 — every settle 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 reason, whatever is still
-        // held was never marked delivered (see `emitNow`), so a future process
-        // (or this same one, after a degrade retry) picks it up the same way — a
-        // live, un-fired `setTimeout` would otherwise also keep this process's
-        // event loop alive on top of the heartbeat interval, for no reason.
-        if (digestTimer !== null) {
-            clearTimeout(digestTimer);
-            digestTimer = null;
-        }
-        const policy = degradePolicyFor(reason);
-        const degraded = policy !== "exit";
-        const fix = extra?.fix ?? fixForStop(reason);
-        deps.write({ type: "stopped", reason, detail, refusal: extra?.refusal, fix, instanceId: options.instanceId, paths: options.watchedPaths, degraded });
-        if (policy === "exit") {
-            heartbeat.stop();
-            sessionStats.stop();
-            return { kind: "exit", code };
-        }
-        stoppedReason = reason;
-        connectionState = "stopped";
-        if (policy === "degrade-no-heartbeat") {
-            // DX-3028 (AC2) — "Three of these cannot report anything": this process
-            // has no credential it can authenticate a heartbeat WITH, so it sends
-            // none (`heartbeatSuppressed`) and has no basis to retry the mint
-            // itself either — it idles until the plugin, watching `watchedPaths`
-            // for a change, kills and restarts it fresh (a new process re-reads
-            // the credential from scratch). Never resolves on its own.
-            heartbeatSuppressed = true;
-            await new Promise(() => {
-                /* deliberately never settles — see the comment above */
-            });
-        }
-        // degrade-server-fixable: keep heartbeating `stopped`, and retry the
-        // mint/stream on our own after DEGRADED_RETRY_INTERVAL_MS, on top of the
-        // plugin's own watched-path restart (harmless overlap — whichever fires
-        // first wins; a restarted process just re-enters this same loop clean).
-        heartbeatSuppressed = false;
-        await deps.sleep(DEGRADED_RETRY_INTERVAL_MS);
-        return { kind: "retry" };
-    }
-    let backoff = MINT_INITIAL_BACKOFF_MS;
-    let refusedInRow = 0;
-    let readyEmitted = false;
-    // DX-2730 D4 — digest state, declared OUTSIDE the mint/reconnect loop below
-    // so a re-mint (a lapsed lease, still the SAME process) never loses a
-    // pending hold — see the module docblock for the restart case, which the
-    // resume cursor handles instead.
-    let held = [];
-    let digestTimer = null;
-    function markDelivered(id) {
-        if (id === null)
-            return;
-        delivered.push(id);
-        if (delivered.length > DELIVERED_ID_MEMORY)
-            delivered.shift();
-    }
-    /** Write an event downstream at once, and mark its id delivered — never before now. */
-    function emitNow(output) {
-        markDelivered(output.id);
-        deps.write(output);
-    }
-    /** Combine every held event into ONE record and emit it, if there is anything to combine. */
-    function flushDigest() {
-        if (digestTimer !== null) {
-            clearTimeout(digestTimer);
-            digestTimer = null;
-        }
-        if (held.length === 0)
-            return;
-        const entries = held;
-        held = [];
-        const ids = entries.map((e) => e.id).filter((id) => id !== null);
-        emitNow({ type: "event", id: ids.length === 0 ? null : Math.max(...ids), text: formatDigest(entries), origin: null });
-    }
-    /** Every id currently held, unflushed — also fed back into the next `runListener` call's
-     *  `resumeIds` below, so a re-mint's fresh listener knows these were already seen and its
-     *  OWN duplicate guard (`listen.ts`'s `delivered` Set) silently drops a replay of one,
-     *  rather than it reaching here a second time. */
-    function heldIds() {
-        return held.map((e) => e.id).filter((id) => id !== null);
-    }
-    /**
-     * DX-2730 D4 — the ONE place that decides immediate vs. held-for-digest.
-     * `operator` and `null` (nudge / unreadable — see `ListenEvent.origin`'s
-     * docblock) flush any pending digest first (never let a digest arrive AFTER
-     * the operator event that should have superseded it) and then emit at once.
-     * `agent` / `machine` are appended to the hold, arming the interval timer
-     * only for the FIRST held event since the last flush — a later addition
-     * must never push the deadline out, or the "at most every 10 minutes"
-     * guarantee would erode into "10 minutes after the last event," which could
-     * never fire while events keep arriving.
-     *
-     * DEDUPED BY ID (defense in depth): a held event's id is not added to
-     * `delivered` until it is actually flushed (see `emitNow`), which is what
-     * lets a crashed-and-restarted PROCESS recover it via the dashboard's own
-     * replay. The same replay can also legitimately re-arrive WITHIN one still-
-     * running process — a re-mint after a real `lease_expired` starts a fresh
-     * `runListener` whose own duplicate guard is seeded from `resumeIds` alone,
-     * and a still-held id was never in `delivered` to seed it with. `resumeIds`
-     * below closes that for the ordinary case by handing the fresh listener
-     * every held id too; this check is the second, cheaper layer for anything
-     * that reaches here anyway — never trust a single guard to hold alone.
-     */
-    function routeEvent(output) {
-        if (output.origin === "agent" || output.origin === "machine") {
-            if (output.id !== null && heldIds().includes(output.id))
-                return;
-            held.push(output);
-            digestTimer ??= setTimeout(flushDigest, DIGEST_INTERVAL_MS);
-            return;
-        }
-        flushDigest();
-        emitNow(output);
-    }
-    for (;;) {
-        connectionState = "reconnecting";
-        // DX-3099 — a fresh cycle earns a clean slate: any abort captured from a
-        // now-abandoned prior attempt is dropped (calling it would be a harmless
-        // no-op anyway) and the failure streak starts over at 0.
-        forceReconnect = null;
-        heartbeatFailureStreak = 0;
-        const minted = await mintTicket(options, deps);
-        if (minted.kind === "terminal") {
-            const outcome = await settle(minted.reason, minted.detail, 1);
-            if (outcome.kind === "exit")
-                return outcome.code;
-            refusedInRow = 0;
-            continue;
-        }
-        if (minted.kind === "transient") {
-            await deps.sleep(backoff);
-            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.
-        // DX-2970 — the inventory read (`fetchPlanInventory`) runs on this SAME
-        // first-mint-only path, for the same reason: it is a property of the
-        // credential and the plan, and a re-mint changes neither. Best-effort —
-        // never gates the `for(;;)` loop, never retried, never delays streaming.
-        if (!readyEmitted) {
-            readyEmitted = true;
-            const inventory = await fetchPlanInventory(options, deps);
-            // DX-3028 (AC1, code-review + architecture-review finding) — this is
-            // the ONE place `lastInventoryError` is ever written; the 15s heartbeat
-            // reads it on every "streaming" tick (see `heartbeatTick` above). Must
-            // agree with the SAME `ready` record's own `degraded` decision below —
-            // a heartbeat reporting `inventory:"ok"` while the `ready` record just
-            // told the operator `degraded:true` would be exactly the untruthful
-            // state AC1 exists to prevent.
-            lastInventoryError = inventory.kind === "ok" ? null : inventory.detail;
-            if (inventory.kind === "ok") {
-                deps.write({
-                    type: "ready",
-                    boards: inventory.boards,
-                    cardCount: inventory.cardCount,
-                    degraded: inventory.boards.length === 0 || inventory.cardCount === 0,
-                    inventoryError: null,
-                });
-            }
-            else {
-                deps.write({ type: "ready", boards: null, cardCount: null, degraded: true, inventoryError: inventory.detail });
-            }
-        }
-        backoff = MINT_INITIAL_BACKOFF_MS;
-        const run = { stopped: null, emitted: false };
-        const startedAt = deps.now();
-        // 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") {
-                    run.stopped = output;
-                    return;
-                }
-                run.emitted = true;
-                routeEvent(output);
-            },
-            // DX-3028 (AC1) — the only place `connectionState` ever becomes
-            // "streaming": `listen.ts`'s `connectOnce` calls this the moment the
-            // SSE connection is actually open, and the outer `for(;;)` above
-            // already resets it to "reconnecting" before every mint attempt.
-            onState: (state) => {
-                connectionState = state;
-            },
-            // DX-3099 — captures the CURRENT connectOnce attempt's own abort, so
-            // the heartbeat-failure self-heal above always targets exactly the
-            // in-flight connection, never a stale one from an earlier attempt.
-            onConnectionAttempt: (abort) => {
-                forceReconnect = abort;
-            },
-        });
-        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 `settle(stopped.reason, ...)` call type-check against the
-        // closed `ListenStopReason` overload) from working.
-        if (stopped.reason === "superseded" || stopped.reason === "replaced") {
-            const outcome = await settle(stopped.reason, stopped.detail, 0);
-            if (outcome.kind === "exit")
-                return outcome.code;
-            refusedInRow = 0;
-            continue;
-        }
-        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".
-                const outcome = await settle(classified.reason, classified.detail, 1);
-                if (outcome.kind === "exit")
-                    return outcome.code;
-                refusedInRow = 0;
-                continue;
-            }
-        }
-        if (stopped.reason === "refused") {
-            const provedHealthy = run.emitted || deps.now() - startedAt >= HEALTHY_CONNECTION_MS;
-            refusedInRow = provedHealthy ? 1 : refusedInRow + 1;
-            if (refusedInRow >= MAX_REFUSED_TICKETS_IN_A_ROW) {
-                const outcome = await settle("refused", `${stopped.detail} (a freshly minted ticket was refused ${refusedInRow} times in a row)`, 1);
-                if (outcome.kind === "exit")
-                    return outcome.code;
-                refusedInRow = 0;
-            }
-            continue;
-        }
-        {
-            const outcome = await settle(stopped.reason, stopped.detail, 1);
-            if (outcome.kind === "exit")
-                return outcome.code;
-            refusedInRow = 0;
-            continue;
-        }
-    }
-}
-/**
- * DX-3028 — the ONE real `scheduleInterval` implementation, shared by
- * `runBridge`'s deps AND `runBridgeCommand`'s own start-time
- * `degrade-no-heartbeat` keep-alive (see the comment at that call site for
- * why the latter needs one too). A single real `setInterval`/`clearInterval`
- * pair, so the two call sites can never drift into two different ideas of
- * what "the real process's interval" means.
- */
-function realScheduleInterval(tick, ms) {
-    const timer = setInterval(tick, ms);
-    return { stop: () => clearInterval(timer) };
-}
-/** The bin's `bridge` subcommand, wired to the real process. */
-export async function runBridgeCommand(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`);
-    };
-    let args;
-    try {
-        args = parseBridgeArgs(argv, env);
-    }
-    catch (err) {
-        process.stderr.write(`${err.message}\n`);
-        return 2;
-    }
-    let options;
-    try {
-        options = resolveBridgeOptions(args, env, resolveFrom);
-    }
-    catch (err) {
-        const start = err;
-        // DX-3028 (AC2) — a start-time failure still reports itself the way every
-        // other stop does — one stop record the plugin relays into the session
-        // (now carrying `paths`/`instanceId`/`degraded`) — AND on stderr, for the
-        // case where there is no session to relay into (a hand run).
-        const policy = degradePolicyFor(start.reason);
-        const degraded = policy !== "exit";
-        write({ type: "stopped", reason: start.reason, detail: start.message, fix: start.fix, instanceId: start.instanceId, paths: start.paths, degraded });
-        process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
-        if (!degraded)
-            return 1;
-        // DX-3028 (AC2, architecture-review finding) — `credential_unavailable` /
-        // `credential_mismatch`: this process has no credential it can
-        // authenticate a heartbeat with (see `settle`'s identical
-        // `degrade-no-heartbeat` branch), so it sends none — but it MUST still
-        // genuinely idle until the plugin kills and restarts it fresh on a
-        // watched-path change, exactly like the runtime `settle()` path does.
-        // The runtime path stays alive because ITS heartbeat `setInterval` (in
-        // `runBridge`, started before its mint loop) is already registered with
-        // libuv by the time it degrades; THIS path is reached before `runBridge`
-        // (and its interval) ever exists, so a bare `return new Promise(() => {})`
-        // here registers no handle at all — Node has nothing left pending once
-        // the call stack unwinds and the process exits almost immediately,
-        // defeating the "idles forever" contract `BridgeOptions.watchedPaths`
-        // exists to serve (DX-2953's watchdog only ever gets a chance to act on
-        // a process that is actually still running). `realScheduleInterval()`
-        // gives it the same kind of keep-alive handle the runtime path gets for
-        // free, ticking a no-op (there is nothing truthful to heartbeat here).
-        realScheduleInterval(() => { }, HEARTBEAT_INTERVAL_MS);
-        // `return`ed directly (never `await`ed then fallen through) so
-        // TypeScript's definite-assignment check for `options` below sees this
-        // branch as never reaching that line, which is also true at runtime —
-        // this promise never settles.
-        return new Promise(() => {
-            /* deliberately never settles */
-        });
-    }
-    return runBridge(options, {
-        fetch: (input, init) => fetch(input, init),
-        write,
-        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-        now: Date.now,
-        readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
-        requestTimeoutMs: REQUEST_TIMEOUT_MS,
-        scheduleInterval: realScheduleInterval,
-    });
-}