@thehammer/danx-dashboard-mcp 0.1.271 → 0.1.274

package/dist/plan-events-relay.js

@@ -0,0 +1,425 @@
+/**
+ * DX-4233 - the IN-PROCESS relay of a session's plan events: what the `plan_events_wait` tool serves.
+ *
+ * WHO CALLS IT. The danxbot plugin's relay loop, inside the Claude Code session, calls `plan_events_wait` over and over on
+ * this session's own danx-dashboard MCP server and hands every record it gets to the session. This class is everything on the
+ * server side of that call: it opens the session's dashboard event stream (the mint / stream / heartbeat contract of
+ * `session-stream.ts`), buffers records for the caller and reports the session's listener health. There is no process to start,
+ * watch or kill: the stream lives exactly as long as the MCP server, which lives exactly as long as its session.
+ *
+ * THE WAIT CONTRACT (`wait`). One rule, one reset, and a cursor that is opaque to the caller.
+ *   1. ONE RULE, BY ARRIVAL. Every record (a dashboard event, a digest, a notice, a pacing or resume message) is given the next
+ *      number of a sequence that only ever increases: its `seq`. Each answered record carries a CURSOR, an opaque string the
+ *      caller stores once it has DELIVERED that record and sends back on its next call. A call answers every buffered record
+ *      whose seq is above the cursor's (at once when there is one, else when one arrives, else empty at the timeout) and
+ *      DROPS every record at or below it, at the call (`acknowledged`, the one predicate). An answer is never a drain: a record
+ *      stays buffered until a LATER call's cursor passes it, so a call whose caller went away (a plugin reload) loses nothing.
+ *      The dashboard numbers its events when it INSERTS them but publishes them when it COMMITS, so an event can arrive after
+ *      a higher-numbered one; arrival order is the only order the relay can promise, which is why the dashboard's id is never
+ *      what is compared.
+ *   2. THE CURSOR. `<seq>:<id>,<id>,...`: the record's seq, then the dashboard event ids delivered up to and including it, in
+ *      arrival order and bounded to the last `CURSOR_IDS_MAX` (`formatCursor`, `parseCursor`: the seq and every id are base-10
+ *      whole numbers with no leading zero, the ids are distinct and positive; anything else is refused loudly). The ids are what
+ *      makes a restart exact. After a restart of the MCP server (a resumed session) a fresh relay is presented its caller's
+ *      cursor: its sequence continues from that seq, and the stream resumes after the highest of those ids with the listener's
+ *      duplicate guard seeded with all of them. The dashboard replays every event created within its 30 s commit-order overlap
+ *      (`REPLAY_COMMIT_ORDER_OVERLAP_MS`) before the last one seen and relies on that guard, so an already delivered event in
+ *      the overlap is dropped and one never delivered is delivered.
+ *      THE ACCEPTED GAP: an insert that commits more than that 30 s overlap after the event it follows is missed by a RESTART
+ *      resume (the dashboard's own limit); a running relay never misses one. And a burst of more than `CURSOR_IDS_MAX` events
+ *      inside the overlap can replay the oldest of them once (a duplicate, never a loss).
+ *   3. ONE PLAN. A call names the plan the session is on (`planId`). A plan different from the last call's drops the
+ *      PLAN-scoped records buffered or held for the plan it left, so a move starts clean. SESSION-scoped records (pacing, resume
+ *      and the relay's own failure and revoked-key notices: they say nothing about a plan, and the dashboard never replays
+ *      them) are kept, here and across the 40 s suspend below. The ids of a dropped record leave the cursors of the records that
+ *      stay: delivering a kept record must not claim an event that was dropped undelivered. The stream stays on a move: it
+ *      belongs to the SESSION, and the dashboard delivers an event only while the session is on the event's plan.
+ *
+ * One wait is pending at a time: a newer call supersedes the older, which answers empty at once. A call whose request is
+ * aborted drops its waiter. A terminal outcome answers `{stopped}` with the remedy (`stop-fixes.ts`); the call after it tries
+ * again from scratch.
+ *
+ * WHO IS HEALTHY. The relay heartbeats every `HEARTBEAT_INTERVAL_MS` while a call is pending or one was made within
+ * `HEARTBEAT_ACTIVITY_WINDOW_MS`. After that window the stream is closed and the heartbeat stops, so the dashboard reads the
+ * session not healthy when nothing is reading its events (a dead or unloaded plugin module). The window is 40 s: a pending
+ * call counts, so it only has to outlast the caller's turnaround and failure backoff (the plugin waits 20 s and backs off at
+ * most 10 s), and it must stay under the dashboard's liveness window (`SESSION_LIVENESS_WINDOW_MS`, 60 s) minus one beat. The
+ * sequence and the highest event id survive the gap, so a cursor stays valid across it.
+ *
+ * NOTHING OUTLIVES THE SESSION. The heartbeat interval, the backoff sleep and the digest hold are unref'd, the stream and the
+ * mint / inventory requests are aborted by `close()`, and `close()` also clears a pending call's wait timer (the one ref'd timer,
+ * held only until the call answers). The server calls `close()` when its transport closes and when its stdin ends (`shutdown.ts`).
+ */
+import { DigestHold } from "./digest-hold.js";
+import { HeartbeatReporter } from "./heartbeat-reporter.js";
+import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, INITIAL_BACKOFF_MS, MAX_BACKOFF_MS, runListener, } from "./listen.js";
+import { classifyAdmissionRefusal, fetchPlanInventory, HEARTBEAT_INTERVAL_MS, heartbeatConnection, MAX_REFUSED_TICKETS_IN_A_ROW, mintTicket, } from "./session-stream.js";
+import { fixForStop } from "./stop-fixes.js";
+/** The shortest and longest wait one call may ask for; a short ceiling keeps an orphaned waiter's life short. */
+export const WAIT_MIN_MS = 1_000;
+export const WAIT_MAX_MS = 30_000;
+/** How long after a call (or the end of one) the relay keeps heartbeating and streaming; see the module docblock. */
+export const HEARTBEAT_ACTIVITY_WINDOW_MS = 40_000;
+/**
+ * How many delivered dashboard event ids a cursor carries. The dashboard replays the events created within its 30 s overlap
+ * before the last one seen: 64 covers a busy plan's burst in that window many times over while keeping every record's cursor
+ * a few hundred characters. (The listener's own memory, `DELIVERED_ID_MEMORY`, is far larger and is not what a cursor carries.)
+ */
+export const CURSOR_IDS_MAX = 64;
+const WHOLE = "(?:0|[1-9][0-9]*)";
+const CURSOR_PATTERN = new RegExp(`^(${WHOLE}):((?:[1-9][0-9]*)(?:,[1-9][0-9]*)*)?$`);
+export const formatCursor = (cursor) => `${cursor.seq}:${cursor.ids.join(",")}`;
+/** Reads a cursor this relay issued. Anything else is refused loudly: a guess would hide a lost or repeated record. */
+export function parseCursor(raw) {
+    const match = CURSOR_PATTERN.exec(raw);
+    const seq = match === null ? NaN : Number(match[1]);
+    const ids = match === null || match[2] === undefined ? [] : match[2].split(",").map(Number);
+    const valid = Number.isSafeInteger(seq) && ids.length <= CURSOR_IDS_MAX && ids.every(Number.isSafeInteger) && new Set(ids).size === ids.length;
+    if (!valid) {
+        throw new Error(`plan_events_wait: cursor ${JSON.stringify(raw)} is not one this server issued (expected "<seq>:<id>,<id>,...": a whole number, a colon, then up to ${CURSOR_IDS_MAX} distinct positive event ids)`);
+    }
+    return { seq, ids };
+}
+const boundedIds = (ids) => [...new Set(ids)].slice(-CURSOR_IDS_MAX);
+/** DX-4233: the one rule of the cursor: a record at or below its seq has been delivered. */
+export const acknowledged = (seq, cursor) => cursor !== null && seq <= cursor.seq;
+export class PlanEventRelay {
+    deps;
+    buffer = [];
+    waiter = null;
+    run = null;
+    lastPlanId = null;
+    /** The last seq given: it continues from a presented cursor and survives a suspend, so a cursor stays valid across the gap. */
+    seq = 0;
+    /** The dashboard event ids that arrived (or were presented in a cursor), oldest first, bounded: the next record's `recent`. */
+    recentIds = [];
+    /** A terminal outcome nobody was waiting for: answered by the next call. */
+    pendingStop = null;
+    /** Dashboard ids already given to the buffer (and the cursor the run started from): handed to a re-mint so a replay is dropped. */
+    seenIds = [];
+    connectionState = "reconnecting";
+    stoppedReason = null;
+    lastInventoryError = null;
+    lastActivityAt = 0;
+    heartbeat = null;
+    reporter = null;
+    digest = new DigestHold((event) => this.accept(event));
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The one entry point: see the module docblock for the contract. */
+    async wait(args, signal) {
+        // Parsed first: a cursor this server did not issue is refused before it changes anything.
+        const cursor = args.cursor === null ? null : parseCursor(args.cursor);
+        // DX-4233: a request already cancelled (a plugin reload) touches nothing and starts nothing.
+        if (signal?.aborted)
+            return { events: [] };
+        // DX-4233: one wait at a time; the older call answers empty so its caller is never left hanging.
+        this.supersedeWaiter();
+        // DX-4233: a plan move starts clean (the very first call has no last plan; after a suspend the last plan is still known, and `dropPlanScoped` already ran).
+        if (this.lastPlanId !== null && args.planId !== this.lastPlanId)
+            this.startClean();
+        this.lastPlanId = args.planId;
+        if (cursor !== null) {
+            // DX-4233: a fresh relay (a restarted server) continues the caller's sequence and remembers the ids it was handed; a
+            // running one is already past both.
+            this.seq = Math.max(this.seq, cursor.seq); // DX-4233: max, never `=`: a stale cursor (a plugin reload) must not reuse a buffered seq
+            this.recentIds = boundedIds([...cursor.ids, ...this.recentIds]);
+            // What the caller delivered precedes every record still buffered, so each of their cursors carries it (a dropped
+            // plan-scoped record's ids were taken out of them, and the caller's own delivered ids go back in).
+            this.buffer = this.buffer.map((r) => ({ ...r, recent: boundedIds([...cursor.ids, ...r.recent]) }));
+        }
+        this.touch();
+        this.ensureReporter(args.transcriptPath);
+        this.buffer = this.buffer.filter((r) => !acknowledged(r.seq, cursor));
+        if (this.pendingStop !== null) {
+            const stopped = this.pendingStop;
+            this.pendingStop = null;
+            return { stopped };
+        }
+        // DX-4233: a server holding no key answers a stop without calling the dashboard (a dispatch never reaches here).
+        if (this.deps.auth() === null) {
+            return { stopped: this.stopRecord("credential_unavailable", "this session holds no dashboard key") };
+        }
+        if (this.run === null)
+            this.start(cursor);
+        if (this.buffer.length > 0)
+            return this.answer();
+        return new Promise((resolve) => {
+            const onAbort = () => this.supersedeWaiter();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            const waiter = {
+                settle: resolve,
+                timer: setTimeout(() => {
+                    this.waiter = null;
+                    this.finishCall(waiter, { events: [] });
+                }, args.timeoutMs),
+                detach: () => signal?.removeEventListener("abort", onAbort),
+            };
+            this.waiter = waiter;
+        });
+    }
+    /** Stop everything: the pending call, the stream, the heartbeat, the transcript tailer. For the server's shutdown. */
+    close() {
+        this.supersedeWaiter();
+        this.suspend();
+    }
+    // ---------------------------------------------------------------------------------------------------------------- calls
+    finishCall(waiter, answer) {
+        clearTimeout(waiter.timer);
+        waiter.detach();
+        this.lastActivityAt = this.deps.now();
+        waiter.settle(answer);
+    }
+    /** The pending call, if any, answers empty at once (a newer call replaced it, or its request went away). */
+    supersedeWaiter() {
+        const waiter = this.waiter;
+        if (waiter === null)
+            return;
+        this.waiter = null;
+        this.finishCall(waiter, { events: [] });
+    }
+    /** Everything buffered, each record with the cursor to store once it is delivered. */
+    answer() {
+        return { events: this.buffer.map(({ seq, recent, text }) => ({ cursor: formatCursor({ seq, ids: recent }), text })) };
+    }
+    // ------------------------------------------------------------------------------------------------------------ the buffer
+    /**
+     * A record the session should now be told: given the next seq, buffered for the caller, and the pending call answers with it.
+     * A replayed dashboard event never reaches here twice: the listener's duplicate guard (seeded from the cursor) drops it first.
+     */
+    accept(event) {
+        // DX-4233: the seq is given at arrival and never reused, so a record the dashboard publishes late is just the next one.
+        const own = event.ids ?? (event.id === null ? [] : [event.id]);
+        this.recentIds = boundedIds([...this.recentIds, ...own]);
+        for (const id of own) {
+            this.seenIds.push(id);
+            if (this.seenIds.length > DELIVERED_ID_MEMORY)
+                this.seenIds.shift();
+        }
+        this.seq += 1;
+        this.buffer.push({ seq: this.seq, own, recent: [...this.recentIds], text: event.text, scope: event.scope ?? "plan" });
+        const waiter = this.waiter;
+        if (waiter === null)
+            return;
+        this.waiter = null;
+        this.finishCall(waiter, this.answer());
+    }
+    // ---------------------------------------------------------------------------------------------------- lifecycle and health
+    /**
+     * DX-4233: drop the plan-scoped records, keeping the session-scoped ones. The ids of what is dropped leave the cursors of what
+     * stays (and the remembered ids): delivering a kept record must not claim an event that was dropped undelivered, or a
+     * restart would resume past it and the dashboard would never replay it.
+     */
+    dropPlanScoped() {
+        const dropped = new Set(this.buffer.filter((r) => r.scope === "plan").flatMap((r) => r.own));
+        this.buffer = this.buffer
+            .filter((r) => r.scope === "session")
+            .map((r) => ({ ...r, recent: r.recent.filter((id) => !dropped.has(id)) }));
+        this.recentIds = this.recentIds.filter((id) => !dropped.has(id));
+        // DX-4233: `seenIds` (the listener's duplicate guard for a re-mint on the SAME run) deliberately keeps them. A plan move's
+        // dropped events belong to a plan the session left, and the dashboard replays only the session's current plan, so nothing
+        // legitimate is replayed into the guard; and the gap, which does need them replayed, ends the run, so `start` builds a fresh `seenIds` from the next call's cursor.
+    }
+    /** The session moved to another plan: drop what was buffered or held for the plan it left; session-scoped records stay. */
+    startClean() {
+        this.dropPlanScoped();
+        this.digest.reset();
+    }
+    /** Creates the heartbeat reporter on the first call; a later call's transcript path (a resumed session) is handed to it. */
+    ensureReporter(transcriptPath) {
+        if (this.reporter !== null) {
+            this.reporter.useTranscript(transcriptPath);
+            return;
+        }
+        this.reporter = new HeartbeatReporter({
+            auth: () => {
+                const auth = this.deps.auth();
+                if (auth === null)
+                    throw new Error("plan_events_wait: this server holds no dashboard key to heartbeat with");
+                return auth;
+            },
+            http: this.deps,
+            makeStatsWatcher: this.deps.makeStatsWatcher,
+            connection: () => heartbeatConnection(this.connectionState, this.stoppedReason, this.lastInventoryError),
+            streaming: () => this.connectionState === "streaming",
+            // `origin: null` skips the agent/machine hold: the notice reaches the session at once. It is about the session, not a plan.
+            announce: (text) => this.digest.route({ type: "event", id: null, text, origin: null, scope: "session" }),
+            forceReconnect: () => this.run?.forceReconnect?.(),
+        }, transcriptPath ?? null);
+    }
+    /** Mark the relay in use and make sure the heartbeat is scheduled. */
+    touch() {
+        this.lastActivityAt = this.deps.now();
+        this.heartbeat ??= this.deps.scheduleInterval(() => this.heartbeatTick(), HEARTBEAT_INTERVAL_MS);
+    }
+    heartbeatTick() {
+        // DX-4233: a pending call keeps the relay alive however long it waits; only a gap with no call at all suspends it.
+        if (this.waiter === null && this.deps.now() - this.lastActivityAt > HEARTBEAT_ACTIVITY_WINDOW_MS) {
+            // Nobody is reading this session's events any more: stop heartbeating (the dashboard then reads the listener not
+            // healthy) and let go of the stream. The next call starts it again from its cursor; the dashboard replays what it missed.
+            this.suspend();
+            return;
+        }
+        if (this.deps.auth() === null)
+            return;
+        this.reporter?.tick();
+    }
+    /**
+     * Let go of everything the relay holds for a caller: the stream, the heartbeat, the digest, and the plan-scoped records.
+     * What was held for a digest was never marked delivered, so the dashboard's replay (after the caller's cursor) returns it to
+     * whoever calls next. Session-scoped records stay (the dashboard never replays them), and so does the sequence, so a cursor
+     * stays valid across the gap; the delivered ids come back with the next call's cursor.
+     */
+    suspend() {
+        this.heartbeat?.stop();
+        this.heartbeat = null;
+        this.run?.abort.abort();
+        this.run = null;
+        this.reporter?.stop();
+        this.reporter = null;
+        this.digest.reset();
+        this.dropPlanScoped();
+        // DX-4233: `dropPlanScoped` already took the undelivered records' ids out of `recentIds`, so the dashboard replays them; what
+        // stays there was delivered. `seenIds` is reassigned by `start`, and a plan move after the gap is dropped by `dropPlanScoped`
+        // above, so neither is reset here.
+        this.pendingStop = null;
+        this.connectionState = "reconnecting";
+        this.stoppedReason = null;
+        this.lastInventoryError = null;
+    }
+    // ------------------------------------------------------------------------------------------------- the mint / stream loop
+    start(cursor) {
+        // The listener's duplicate guard starts with every event the caller was handed and everything still buffered: the dashboard
+        // replays its 30 s overlap before the highest of them, so a replayed one is dropped and a never-delivered one is delivered.
+        this.seenIds = capResumeIds([...(cursor?.ids ?? []), ...this.buffer.flatMap((r) => r.own)]);
+        this.stoppedReason = null;
+        const run = { abort: new AbortController(), forceReconnect: null };
+        this.run = run;
+        void this.loop(run).catch((err) => {
+            // A bug, not a stream outcome: say so out loud, and answer it like any terminal outcome rather than idle silently.
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`plan_events_wait: the event relay failed: ${message}\n`);
+            this.terminal(run, "relay_failed", message);
+        });
+    }
+    current(run) {
+        return this.run === run && !run.abort.signal.aborted;
+    }
+    stopRecord(reason, detail) {
+        return { reason, detail, fix: fixForStop(reason) };
+    }
+    /** A terminal outcome: the pending call (or else the next) answers `{stopped}`; the loop ends. */
+    terminal(run, reason, detail) {
+        // DX-4233: only the run that is still current may end the relay; a superseded or closed run ending late is ignored.
+        if (!this.current(run))
+            return;
+        this.digest.cancel();
+        this.run = null;
+        this.connectionState = "stopped";
+        this.stoppedReason = reason;
+        const stopped = this.stopRecord(reason, detail);
+        const waiter = this.waiter;
+        if (waiter === null) {
+            this.pendingStop = stopped;
+            return;
+        }
+        this.waiter = null;
+        this.finishCall(waiter, { stopped });
+    }
+    async loop(run) {
+        const sleep = (ms) => this.deps.sleep(ms, run.abort.signal);
+        // The mint and the inventory read end with the run, so a closed relay leaves no request in flight.
+        const http = { ...this.deps, signal: run.abort.signal };
+        let backoff = INITIAL_BACKOFF_MS;
+        let refusedInRow = 0;
+        let inventoryRead = false;
+        for (;;) {
+            if (!this.current(run))
+                return;
+            this.connectionState = "reconnecting";
+            this.reporter?.resetFailureStreak();
+            run.forceReconnect = null;
+            const auth = this.deps.auth();
+            if (auth === null)
+                return this.terminal(run, "credential_unavailable", "this session holds no dashboard key");
+            const minted = await mintTicket(auth, http);
+            if (!this.current(run))
+                return;
+            if (minted.kind === "terminal")
+                return this.terminal(run, minted.reason, minted.detail);
+            if (minted.kind === "transient") {
+                await sleep(backoff);
+                backoff = Math.min(MAX_BACKOFF_MS, backoff * 2);
+                continue;
+            }
+            // The inventory is a property of the credential and the plan: read best effort, never a gate. A failed read is reported
+            // on the heartbeat (`inventory: unavailable`), never silently healthy, and is tried again at the next re-mint.
+            if (!inventoryRead) {
+                const inventory = await fetchPlanInventory(auth, http);
+                if (!this.current(run))
+                    return;
+                inventoryRead = inventory.kind === "ok";
+                this.lastInventoryError = inventory.kind === "ok" ? null : inventory.detail;
+            }
+            backoff = INITIAL_BACKOFF_MS;
+            const attempt = { stopped: null, emitted: false };
+            const startedAt = this.deps.now();
+            await runListener({
+                streamUrl: minted.streamUrl,
+                ticket: minted.ticket,
+                leaseMs: minted.leaseMs,
+                resumeIds: capResumeIds([...this.seenIds, ...this.digest.heldIds()]),
+            }, {
+                fetch: this.deps.fetch,
+                sleep,
+                now: this.deps.now,
+                readIdleTimeoutMs: this.deps.readIdleTimeoutMs,
+                signal: run.abort.signal,
+                write: (output) => {
+                    if (!this.current(run))
+                        return;
+                    if (output.type === "stopped") {
+                        attempt.stopped = output;
+                        return;
+                    }
+                    attempt.emitted = true;
+                    this.digest.route(output);
+                },
+                onState: (state) => {
+                    if (!this.current(run))
+                        return;
+                    this.connectionState = state;
+                    // Report `streaming` now, not up to a beat later: the session reads healthy as soon as it is.
+                    if (state === "streaming" && this.deps.auth() !== null)
+                        this.reporter?.tick();
+                },
+                onConnectionAttempt: (abort) => {
+                    run.forceReconnect = abort;
+                },
+            });
+            if (!this.current(run))
+                return;
+            const stopped = attempt.stopped;
+            // DX-4233: the listener always ends with a stop record; its absence is a bug, answered as `relay_failed` by `start`'s catch.
+            if (stopped === null)
+                throw new Error("the stream reader ended without a stop record");
+            if (stopped.reason === "lease_expired") {
+                refusedInRow = 0;
+                continue;
+            }
+            if (stopped.reason === "refused") {
+                const classified = classifyAdmissionRefusal(stopped.refusal);
+                if (classified !== null)
+                    return this.terminal(run, classified.reason, classified.detail);
+                const provedHealthy = attempt.emitted || this.deps.now() - startedAt >= HEALTHY_CONNECTION_MS;
+                refusedInRow = provedHealthy ? 1 : refusedInRow + 1;
+                if (refusedInRow >= MAX_REFUSED_TICKETS_IN_A_ROW) {
+                    return this.terminal(run, "refused", `${stopped.detail} (a freshly minted ticket was refused ${refusedInRow} times in a row)`);
+                }
+                continue;
+            }
+            return this.terminal(run, stopped.reason, stopped.detail);
+        }
+    }
+}

package/dist/plan-events-tool.js

@@ -0,0 +1,9 @@
+import { checkedTranscriptPath } from "./session-stats.js";
+/**
+ * DX-4233 - the body of the `plan_events_wait` tool: the transcript path is checked (a refusal names it), then the relay waits,
+ * and a cancelled request (`signal`, the SDK's `extra.signal`) drops the pending wait. A malformed cursor is refused by the relay.
+ */
+export function servePlanEventsWait(relay, args, signal) {
+    const transcriptPath = args.transcript_path === undefined ? undefined : checkedTranscriptPath(args.transcript_path, "plan_events_wait transcript_path");
+    return relay.wait({ planId: args.plan_id, cursor: args.cursor, timeoutMs: args.timeout_ms, transcriptPath }, signal);
+}

package/dist/restart-notice.js

@@ -22,10 +22,10 @@
  *     non-2xx, bad shape, for every one). Never silent: the hook prints a could-not-load notice.
  *
  * The credential is the PREDECESSOR's own record's source, resolved through the
- * same resolver the bridge uses, so the lookup reaches the dashboard that
+ * same resolver the relay uses, so the lookup reaches the dashboard that
  * connected it. READ-ONLY: it advances no cursor on the server.
  */
-import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
+import { SESSION_ID_HEADER, resolveDashboardAuth } from "./session-options.js";
 import { findPredecessorCandidates, projectKeyOf } from "./session-connection.js";
 export const RESTART_NOTICE_SUBCOMMAND = "restart-notice";
 export const RESTART_NOTICE_REQUEST_TIMEOUT_MS = 5_000;
@@ -119,7 +119,7 @@ resolveFrom = {}) {
     for (const predecessor of candidates) {
         let options;
         try {
-            options = resolveBridgeOptions({ sessionId: predecessor.sessionId, resumeIds: [] }, env, resolveFrom);
+            options = resolveDashboardAuth(predecessor.sessionId, env, resolveFrom);
         }
         catch (err) {
             const start = err;

package/dist/session-access.js

@@ -49,7 +49,7 @@ const DENIED_INSTRUCTION = "The user denied the request. Do not retry unless the
 const DASHBOARD_OUTDATED_ERROR = "this dashboard does not support request-and-approve yet (POST /api/access-requests answered 404): " +
     "it must be updated before this session can sign in";
 const RATE_LIMITED_ERROR = "too many access requests from this address; wait, then call plan_connect again";
-const unknownTeamError = (team) => `the dashboard has no team "${team}" (DANXBOT_TEAM); fix DANXBOT_TEAM in this server's env (the repo's .mcp.json env block or the shell) and restart the session`;
+const unknownTeamError = (team) => `the dashboard has no team "${team}" (DANXBOT_TEAM); fix DANXBOT_TEAM in this server's env (your shell, or a repo's committed .claude/settings.json env block) and restart the session`;
 const NO_SESSION_ID_ERROR = "this server has no CLAUDE_CODE_SESSION_ID, so it cannot request a session key";
 const CLAIMED_LOST_ERROR = "the dashboard says this request was already claimed, but this process never received the key; " +
     "start a new request";
@@ -109,7 +109,7 @@ export class SessionAccess {
         this.dropKey();
         return this.revokedHalt();
     }
-    /** Where the current credential comes from and its fingerprint, for the bridge's connection record. */
+    /** Where the current credential comes from and its fingerprint, for the relay's connection record. */
     connection() {
         if (this.credential === null || this.revoked !== null)
             return null;
@@ -152,7 +152,7 @@ export class SessionAccess {
         return { result };
     }
     /**
-     * DX-4390: the stored file is the bridge's only way to the key, and the 7-day prune ages out
+     * DX-4390: the stored file is the relay's only way to the key, and the 7-day prune ages out
      * a file by when it was last written. A server in use rewrites it (atomically) at most hourly,
      * which also restores a file someone deleted while this process still holds the key.
      */

package/dist/session-connection.js

@@ -1,22 +1,21 @@
 /**
  * DX-2862 — the record that hands ONE Claude Code session's dashboard
- * connection from its MCP server to its event bridge.
+ * connection from its MCP server to the plugin's hook subcommands.
  *
- * THE PROBLEM THIS SOLVES. `danx-dashboard-mcp bridge` runs from a plugin hook,
- * in the SESSION's environment — not in the MCP server's, which is the only
- * place the server's `.mcp.json` env block exists. So the bridge cannot see
- * what the server was configured with, and before this it simply used its own
- * ambient env credential. When that was a different credential from
- * the server's, every event was dropped silently (the card's incident).
+ * THE PROBLEM THIS SOLVES. A hook's subcommand (`activity`, `background-work`, `event-text`,
+ * `ready-cards`, `restart-notice`) runs in the SESSION's environment, not in the MCP server's, which is the only
+ * place the server's `.mcp.json` env block exists. So it cannot see what the server was configured with, and before this it
+ * simply used its own ambient env credential. When that was a different credential from the server's, its report was
+ * dropped silently (the card's incident). The plan event relay (`plan_events_wait`) needs none of this: it runs inside the
+ * server, with the server's own credential. The listener reminder reads this record too.
  *
  * WHAT IS WRITTEN, AND WHAT IS NOT. On a successful `plan_connect` the server
  * writes the dashboard URL, the credential SOURCE (a session key file path, or the name of
- * an env var — never a credential) and the credential's FINGERPRINT. The bridge
+ * an env var — never a credential) and the credential's FINGERPRINT. A subcommand
  * reads that record, resolves the SAME source through the same resolver
  * (`credential.ts`), and refuses to run unless what it resolved fingerprints
  * identically. A rotated file or a session environment that disagrees with the
- * server's therefore fails loud instead of streaming somebody else's events —
- * or, as in DX-2862, none at all.
+ * server's therefore fails loud instead of reporting as somebody else.
  *
  * WHY `plan_connect` AND NOTHING ELSE WRITES IT. A session can have several
  * dashboard MCP servers configured (gpt-manager has a deployed one and a local
@@ -92,7 +91,7 @@ export function pruneStaleSessionFiles(dir, now) {
     }
 }
 /**
- * Record this session's connection. Write-then-rename, so a bridge reading
+ * Record this session's connection. Write-then-rename, so a subcommand reading
  * concurrently sees the old record or the new one, never a torn one.
  */
 export function writeSessionConnection(record, options = {}) {
@@ -147,8 +146,8 @@ export function readSessionConnection(sessionId, options = {}) {
  * that tool's own answer when it could not be recorded.
  *
  * FAIL LOUD, IN THE ONE PLACE THE AGENT IS LOOKING. A connect whose record is
- * missing produces a session that is connected and a bridge that refuses to
- * start — so the failure belongs in the connect's answer, not only in a file
+ * missing produces a session that is connected but whose hook reports (activity, background work, ready cards, the
+ * restart notice) refuse to run — so the failure belongs in the connect's answer, not only in a file
  * nobody reads. It does NOT fail the connect itself: the session IS connected,
  * and reporting otherwise would be a second lie on top of the first.
  */
@@ -157,8 +156,8 @@ export function recordSessionConnectionAfterConnect(result, inputs, write = writ
         return {};
     if (inputs.sessionId === undefined || inputs.sessionId === "") {
         return {
-            event_bridge_error: "connected, but this server has no CLAUDE_CODE_SESSION_ID, so the plan event bridge has no connection to read — " +
-                "dashboard events will NOT reach this session",
+            connection_record_error: "connected, but this server has no CLAUDE_CODE_SESSION_ID, so no connection record can be written — " +
+                "the plugin's activity, background-work, ready-cards and restart-notice reports will not reach the dashboard",
         };
     }
     try {
@@ -173,8 +172,8 @@ export function recordSessionConnectionAfterConnect(result, inputs, write = writ
     }
     catch (err) {
         return {
-            event_bridge_error: `connected, but recording the connection for the plan event bridge failed (${err.message}) — ` +
-                "dashboard events will NOT reach this session until it succeeds",
+            connection_record_error: `connected, but recording this session's connection failed (${err.message}) — ` +
+                "the plugin's activity, background-work, ready-cards and restart-notice reports will not reach the dashboard until it succeeds",
         };
     }
 }

package/dist/session-key.js

@@ -1,6 +1,6 @@
 /**
  * DX-4390 (PLAN-17 section 96) - the dashboard key a user approved for ONE agent session, kept on
- * this machine so the session's MCP server and its event bridge both authenticate with it.
+ * this machine so the session's MCP server and its event relay both authenticate with it.
  *
  * One file per dashboard and per session:
  * `~/.config/danxbot/session-keys/<sha12(dashboard url)>/<session id>.json`, mode 0600. The key
@@ -11,7 +11,7 @@
  * rewrites its file at least hourly (`SessionAccess.guard`), so only an unused session's file
  * ages out. The session id picks the file but never selects a key on the dashboard.
  *
- * Written write-then-rename, like the session connection record, so a bridge reading
+ * Written write-then-rename, like the session connection record, so a relay reading
  * concurrently sees the old file or the new one, never a torn one.
  */
 import { createHash } from "node:crypto";

package/dist/session-options.js

@@ -0,0 +1,58 @@
+/**
+ * DX-2862 / DX-4233 - how a one-shot client of the dashboard (`activity`, `background-work`, `event-text`, `ready-cards`,
+ * `restart-notice`) learns WHICH dashboard to call and AS WHOM: the connection record this session's own MCP server wrote when
+ * it connected a plan (`session-connection.ts`), resolved through the same credential resolver the server used, and refused
+ * unless it fingerprints identically. (The in-process relay behind `plan_events_wait` needs none of this: it lives inside the
+ * server that holds the credential.)
+ */
+import { homedir } from "node:os";
+import { credentialFingerprint, describeCredentialSource, readCredential } from "./credential.js";
+import { readSessionConnection } from "./session-connection.js";
+import { fixForStop } from "./stop-fixes.js";
+export const SESSION_ID_HEADER = "x-danx-session-id";
+/** A start this process cannot make, named the way the session will be told about it. */
+export class SessionStartError extends Error {
+    // `ListenStopReason`, not `string`: a start-time failure is always one of `no_connection_record` / `credential_unavailable`
+    // / `credential_mismatch` (there is no stream yet).
+    reason;
+    fix;
+    constructor(reason, detail, fix) {
+        super(detail);
+        this.name = "SessionStartError";
+        this.reason = reason;
+        this.fix = fix;
+    }
+}
+/**
+ * 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.
+ */
+export function resolveDashboardAuth(sessionId, env, options = {}) {
+    const home = options.home ?? homedir();
+    let record;
+    try {
+        record = readSessionConnection(sessionId, { home });
+    }
+    catch (err) {
+        throw new SessionStartError("no_connection_record", err.message, fixForStop("no_connection_record"));
+    }
+    if (record === null) {
+        throw new SessionStartError("no_connection_record", `session ${sessionId} has no dashboard connection record — no danx-dashboard MCP server has connected it to a plan`, fixForStop("no_connection_record"));
+    }
+    let token;
+    try {
+        token = readCredential(record.source, env);
+    }
+    catch (err) {
+        const credentialError = err;
+        throw new SessionStartError("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);
+    }
+    const fingerprint = credentialFingerprint(token);
+    if (fingerprint !== record.fingerprint) {
+        throw new SessionStartError("credential_mismatch", `${describeCredentialSource(record.source)} now yields credential ${fingerprint}, but this session's ` +
+            `danx-dashboard MCP server is using ${record.fingerprint} — a one-shot call would authenticate as somebody else`, fixForStop("credential_mismatch"));
+    }
+    return { dashboardUrl: record.dashboardUrl.replace(/\/+$/, ""), token, sessionId };
+}