@thehammer/danx-dashboard-mcp 0.1.271 → 0.1.274

package/dist/session-stats.js

@@ -1,5 +1,5 @@
 /**
- * DX-2954 — an operator session's live stats, collected by the bridge and sent
+ * DX-2954 — an operator session's live stats, collected by the relay and sent
  * in its DX-2952 heartbeat.
  *
  * Workers and operator sessions report the same stats the same way (epic
@@ -14,7 +14,7 @@
  *
  * ## Process start: the first heartbeat's answer, never the mint (round 22)
  *
- * A restarted bridge (watchdog restart, compact, resume) may fail its mint and
+ * A restarted session's relay (a resume or a restarted MCP server) may fail its mint and
  * still heartbeat (DX-2952), so the heartbeat is the one call that always
  * answers. Until this process holds that answer it sends ONLY its connection
  * state: no ledger entries, no cursors — the transcript is not even opened. The
@@ -37,22 +37,13 @@
  */
 import { basename, dirname, isAbsolute } from "node:path";
 import { DispatchUsage, SessionLogWatcher, createActivityObserver, } from "@thehammer/danx-session-telemetry";
-/** The environment variable the plugin passes the hook input's `transcript_path` in. */
-export const TRANSCRIPT_PATH_ENV = "DANX_BRIDGE_TRANSCRIPT_PATH";
 /**
- * The session's transcript path from the environment, or `null` when the
- * plugin supplied none (an older plugin, a hand run): the bridge then runs
- * exactly as before, heartbeating its connection state only. A value that is
- * present but is not an absolute `.jsonl` path is refused loudly — silently
- * ignoring it would leave the session's usage uncounted with nothing to say why.
+ * DX-4233 - the one rule for a transcript path, wherever it comes from (the `transcript_path` argument of
+ * `plan_events_wait`): an absolute `.jsonl` path, or a loud refusal naming `source`.
  */
-export function transcriptPathFromEnv(env) {
-    const raw = env[TRANSCRIPT_PATH_ENV];
-    if (raw === undefined || raw.trim() === "")
-        return null;
-    const path = raw.trim();
+export function checkedTranscriptPath(path, source) {
     if (!isAbsolute(path) || !path.endsWith(".jsonl")) {
-        throw new Error(`${TRANSCRIPT_PATH_ENV} must be an absolute path to a session .jsonl transcript (got "${path}")`);
+        throw new Error(`${source} must be an absolute path to a session .jsonl transcript (got "${path}")`);
     }
     return path;
 }
@@ -60,7 +51,7 @@ const realWatcher = (options) => new SessionLogWatcher(options);
 /** The collector's dispatch-id argument; the heartbeat is addressed by session, not dispatch. */
 const OPERATOR_DISPATCH_REF = "operator-session";
 /**
- * DX-3962 - the bridge's collector. `"operator-bridge"` is the ONE mode that credits a sub-agent's replies to the card
+ * DX-3962 - the relay's collector. `"operator-bridge"` (the telemetry package's published mode value, kept under its old name) is the ONE mode that credits a sub-agent's replies to the card
  * it claimed (from its own transcript's pickup); a worker builds its collector with attribution off.
  */
 function newCollector() {
@@ -85,7 +76,7 @@ export class OperatorSessionStats {
      * connection-state heartbeat, whose answer starts collection. After: the
      * collector's flush, carried by the heartbeat (a flush with nothing new
      * sends one plain heartbeat instead, so an idle session still heartbeats).
-     * Returns whether a heartbeat landed, for the bridge's silent-failure count.
+     * Returns whether a heartbeat landed, for the relay's silent-failure count.
      */
     async tick(send) {
         if (this.watcher === null) {
@@ -120,7 +111,7 @@ export class OperatorSessionStats {
         this.watcher?.stop();
     }
     begin(stored) {
-        // `this.watcher !== null`: the bridge fires `tick` without awaiting it, so
+        // `this.watcher !== null`: the relay fires `tick` without awaiting it, so
         // two ticks can both be waiting on a pre-collection heartbeat. The first
         // answer starts collection; a second must not start (and leak) another
         // tailer over the same transcript.
@@ -141,7 +132,7 @@ export class OperatorSessionStats {
         this.usage.attachCursors(() => watcher.cursorState(), stored.sourceCursors);
         this.usage.setTranscriptPath(path);
         // Replays are credited (the ledger is idempotent) and marked so the
-        // collector's own estimate never counts them twice; the bridge has no
+        // collector's own estimate never counts them twice; the relay has no
         // side-effecting transcript subscriber to skip them for.
         watcher.onUsageLine((raw, meta) => this.usage.observeRawLine(raw, meta));
         // DX-4498 — the raw line feed: the brief and Claude Code's task notifications are not entries.

package/dist/session-stream.js

@@ -0,0 +1,358 @@
+/**
+ * DX-4233 - the dashboard HTTP contract of a session's event stream, spoken by the in-process relay behind
+ * `plan_events_wait` (`plan-events-relay.ts`).
+ *
+ * One authenticated request with a timeout, the listener-ticket mint, the best-effort plan inventory read and the 15 s
+ * heartbeat. Everything here is about talking to the dashboard; WHEN to talk (the mint/stream loop, the heartbeat schedule,
+ * what a stop means for the session) belongs to the relay.
+ */
+import { errorCodeOf } from "./json-body.js";
+import { keyRevocationOf, keyRevokedHalt } from "./key-revoked-halt.js";
+import { oneLine } from "./one-line.js";
+import { SESSION_ID_HEADER } from "./session-options.js";
+import { isClaimState } from "@thehammer/danx-session-telemetry";
+/**
+ * DX-3912 — the longest heartbeat `reason` the relay 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. `plan-events-wait.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";
+// 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;
+/** 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-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]);
+/**
+ * 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);
+    const abort = () => controller.abort();
+    if (deps.signal?.aborted === true)
+        abort();
+    deps.signal?.addEventListener("abort", abort, { once: true });
+    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);
+        deps.signal?.removeEventListener("abort", abort);
+    }
+}
+/** 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-relay-contract.test.ts` runs this parser
+ * on the server's own response, so a rename there fails that test instead of silently
+ * degrading every listener. 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 — the relay 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).
+ */
+export 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;
+}
+/**
+ * The one real `scheduleInterval`: a `setInterval` and its canceler, for the relay's heartbeat. Unref'd: a heartbeat never keeps
+ * the MCP server alive after its session ended.
+ */
+export function realScheduleInterval(tick, ms) {
+    const timer = setInterval(tick, ms);
+    timer.unref();
+    return { stop: () => clearInterval(timer) };
+}
+/**
+ * The one real sleep of the relay's mint / stream loop: unref'd, so a backoff never keeps the MCP server alive after its session
+ * ended, and cut short by `signal` (the run was ended), so a suspended relay does not leave a timer behind.
+ */
+export function realSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        timer.unref();
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/**
+ * The truthful `connection` for a heartbeat: `streaming` only while the SSE connection is open (with whether the plan
+ * inventory read worked), `stopped` with the reason the stream ended, otherwise `reconnecting`.
+ */
+export function heartbeatConnection(state, stoppedReason, inventoryError) {
+    if (state === "streaming") {
+        return inventoryError === null
+            ? { state, inventory: "ok" }
+            : { state, inventory: "unavailable", reason: oneLine(inventoryError, HEARTBEAT_REASON_MAX_CODE_POINTS) };
+    }
+    return state === "stopped" ? { state, reason: stoppedReason ?? undefined } : { state };
+}
+/**
+ * One heartbeat POST. Never throws on a failure of the request itself and NEVER stops the relay 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 relay down) (card AC1 — "a failed heartbeat never stops the relay"): `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.
+ */
+export 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 the relay 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);
+}

package/dist/session-title.js

@@ -6,9 +6,9 @@
  * again. DX-2816 found no env var, hook input or MCP-reachable signal carrying the title, but Claude Code writes every
  * title change into the session's transcript as a `{"type":"custom-title","customTitle":"..."}` line the moment the
  * rename happens, even while the session is idle (observed on session 952f0739: 76 records of the old title, then the
- * renamed one, no turn in between). The bridge already holds the transcript path (the plugin passes the hook input's
- * `transcript_path` as `DANX_BRIDGE_TRANSCRIPT_PATH`, `session-stats.ts`), so it reads the last such record on each
- * heartbeat and reports it when it differs from the title the dashboard answered with (`bridge.ts`); the dashboard
+ * renamed one, no turn in between). the relay already holds the transcript path (the plugin passes the hook input's
+ * `transcript_path` as the `transcript_path` argument, `session-stats.ts`), so it reads the last such record on each
+ * heartbeat and reports it when it differs from the title the dashboard answered with (the relay); the dashboard
  * stores it (`plan-sessions-routes.ts`).
  *
  * INCREMENTAL, NEVER A RE-READ. The reader remembers how far it has scanned (always a line boundary) and the title it
@@ -16,7 +16,7 @@
  * bounded to its last {@link TRANSCRIPT_TITLE_MAX_SCAN_BYTES}: Claude Code repeats the record on every turn, so the
  * latest one is always near the end, and a transcript with none in that window has nothing to report.
  *
- * It reads synchronously on purpose: the bridge's heartbeat tick is synchronous up to its first request, and a read
+ * It reads synchronously on purpose: the relay's heartbeat tick is synchronous up to its first request, and a read
  * of a few appended kilobytes every 15 seconds costs less than the plumbing an async read would need.
  */
 import { closeSync, fstatSync, openSync, readSync } from "node:fs";
@@ -111,7 +111,7 @@ function parseTitleRecord(line, path) {
 }
 /**
  * At most {@link SESSION_TITLE_MAX_CHARS} UTF-16 units, cut on a code-point boundary. A cut that lands after a space is
- * trimmed again: the dashboard stores the trimmed title, so an untrimmed one would never equal it and the bridge would
+ * trimmed again: the dashboard stores the trimmed title, so an untrimmed one would never equal it and the relay would
  * resend it on every heartbeat.
  */
 function boundTitle(title) {

package/dist/shutdown.js

@@ -0,0 +1,12 @@
+/**
+ * DX-4523 / DX-4233 - what the server lets go of when its session ends: the permission watch's open stream and the plan event
+ * relay (its pending call, stream, heartbeat and tailer), so nothing keeps the process alive after the client is gone.
+ *
+ * Two triggers, both needed: the transport's `onclose` (an orderly close of the connection) and the end of stdin. The SDK's stdio
+ * transport does not watch stdin for its end (only a transport `close()` reaches `onclose`), so a client that simply exits
+ * would leave the process running without the second one.
+ */
+export function stopWhenSessionEnds(wiring) {
+    wiring.server.onclose = wiring.stop;
+    wiring.stdin.once("end", wiring.stop);
+}

package/dist/stop-fixes.js

@@ -0,0 +1,40 @@
+/**
+ * DX-4233 - the remedy a session is shown for each way its dashboard event stream can stop, in ONE place.
+ *
+ * The client that ends in these texts is the in-process relay behind `plan_events_wait` (`plan-events-relay.ts`); the one-shot
+ * subcommands use `fixForStop` for a start they cannot make. Pure data and one function with no imports.
+ */
+/**
+ * The remedy per terminal reason. ONE map, so the message a session is shown and the message a log carries can never drift.
+ * `KnownStopReason` is only a SUBSET of `ListenStopReason` (which also has `unknown`, for a newer dashboard's wire reason this
+ * build predates), so `fixForStop` accepts a plain string and falls back to `DEFAULT_STOP_FIX`.
+ *
+ * DX-4233 - the texts name the session's listener, never a process: with the relay inside the session's own MCP server there
+ * is no separate process to restart.
+ */
+export const STOP_FIXES = {
+    no_connection_record: "call plan_connect again in this session — its danx-dashboard MCP server records the connection a hook command 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 the plugin's hook commands 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 listener 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 listener 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; 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",
+    relay_failed: "the event relay inside this session's danx-dashboard MCP server failed (the detail says why); the next call tries again, and if it keeps failing restart this Claude Code session",
+};
+export const DEFAULT_STOP_FIX = "call plan_connect again in this session to restart the listener";
+export function fixForStop(reason) {
+    return STOP_FIXES[reason] ?? DEFAULT_STOP_FIX;
+}

package/dist/subagents-live.js

@@ -3,12 +3,12 @@
  * sub-agents for the danxbot plugin's plan pane (DX-4508).
  *
  * WHY IT EXISTS. The pane's dashboard read (`GET /api/plan-sessions/:id/subagents`) lags the transcript by about 80s
- * (the bridge's 5s transcript poll, its 15s heartbeat flush, the pane's 60s read). A hooks module cannot tail the files
+ * (the relay's 5s transcript poll, its 15s heartbeat flush, the pane's 60s read). A hooks module cannot tail the files
  * itself (`$.fs.read` has no offset and refuses files over 4 MiB), but it can spawn a long-lived child and read its
  * stdout. This is that child: it tails the session's transcript tree on this machine and prints each change within one
  * 1s poll of Claude Code writing it.
  *
- * ONE PLACE COMPUTES EACH NUMBER. It runs the same `SessionLogWatcher` the bridge runs (`session-stats.ts`), over the
+ * ONE PLACE COMPUTES EACH NUMBER. It runs the same `SessionLogWatcher` the relay runs (`session-stats.ts`), over the
  * same session layout (the main transcript, and `<sessionDir>/<sessionId>/subagents/agent-<id>.jsonl` beside it), into
  * the shared `createSubagentLiveView`, which feeds the same activity observer, usage ledger counter and pricing rule
  * the dashboard's numbers come from. Nothing is counted or priced here.

package/dist/tool-access.js

@@ -27,6 +27,7 @@ export const CALLBACK_ENV = {
 };
 const BOOTSTRAP = { permission: null, callback: null };
 const needs = (permission) => ({ permission, callback: null });
+const operatorSessionNeeds = (permission) => ({ permission, callback: null, operatorSessionOnly: true });
 const needsAndPostsTo = (permission, callback) => ({ permission, callback });
 /**
  * Every tool this server registers, with what makes it usable. `index.ts` refuses to register a tool that is not
@@ -40,6 +41,9 @@ export const TOOL_ACCESS = {
     danxbot_api_spec: BOOTSTRAP,
     // `POST /api/issues/:id/attachments`
     attach_file: needs("cards.edit"),
+    // DX-4233 - the plugin's relay waits on the session's plan events here: it opens the listener ticket
+    // (`POST /api/plan-sessions/me/stream-ticket`) and heartbeats (`.../me/heartbeat`), both `plans.view`.
+    plan_events_wait: operatorSessionNeeds("plans.view"),
     // The one dispatch callback that stays a tool (DX-4525): it reads local files. Its dashboard route's own policy names the
     // permission (`route-policies/index.ts`); every other callback is a `danxbot_api` call to a route under `callback-routes.ts`.
     danxbot_slack_reply: needsAndPostsTo("slack.threads.post", "slackReply"),
@@ -50,6 +54,8 @@ export function isUsable(access, grant) {
         return false;
     if (access.callback !== null && !grant.callbacks.has(access.callback))
         return false;
+    if (access.operatorSessionOnly === true && !grant.operatorSession)
+        return false;
     return true;
 }
 /** The ONE mapping from what a session holds to the tool names it advertises, sorted. */
@@ -58,5 +64,5 @@ export function toolsFor(grant) {
 }
 /** The bootstrap set: usable with no key and no callback. */
 export function bootstrapTools() {
-    return toolsFor({ permissions: new Set(), callbacks: new Set() });
+    return toolsFor({ permissions: new Set(), callbacks: new Set(), operatorSession: false });
 }

package/dist/tool-surface.js

@@ -11,17 +11,15 @@ import { toolsFor } from "./tool-access.js";
 export class ToolSurface {
     tools;
     callbacks;
-    onChanged;
-    constructor(tools, callbacks, 
-    /** Announces that the tool list changed: the server's `sendToolListChanged` (a no-op until a client is connected). */
-    onChanged) {
+    options;
+    constructor(tools, callbacks, options) {
         this.tools = tools;
         this.callbacks = callbacks;
-        this.onChanged = onChanged;
+        this.options = options;
     }
     /** Show exactly the tools `permissions` and this dispatch's callbacks allow. Returns the names whose visibility changed. */
     apply(permissions) {
-        const wanted = new Set(toolsFor({ permissions, callbacks: this.callbacks }));
+        const wanted = new Set(toolsFor({ permissions, callbacks: this.callbacks, operatorSession: this.options.operatorSession }));
         const changed = [];
         for (const [name, tool] of this.tools) {
             const want = wanted.has(name);
@@ -31,7 +29,7 @@ export class ToolSurface {
             changed.push(name);
         }
         if (changed.length > 0)
-            this.onChanged();
+            this.options.onChanged();
         return changed.sort();
     }
     /** The tool names currently shown. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.271",
+  "version": "0.1.274",
   "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, request_permission, attach_file, and danxbot_slack_reply) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",
@@ -21,6 +21,7 @@
     "node": ">=20"
   },
   "scripts": {
+    "prepublishOnly": "bash ../../scripts/assert-tree-contains-origin-main.sh @thehammer/danx-dashboard-mcp",
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
     "verify:boot": "bash scripts/verify-boot.sh",
     "start": "node dist/index.js",
@@ -31,7 +32,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@thehammer/danx-session-telemetry": "0.1.29",
+    "@thehammer/danx-session-telemetry": "0.1.44",
     "zod": "^3.25.76"
   },
   "devDependencies": {