@thehammer/danx-dashboard-mcp 0.1.273 → 0.1.274

package/dist/index.js

@@ -54,7 +54,7 @@
  *
  * Env at boot (validated fail-loud — a missing required var → process.exit(1)):
  *   DANXBOT_DASHBOARD_URL   dashboard base (e.g. http://danxbot-dashboard:5555)
- *   the CREDENTIAL (DX-4390), resolved by the ONE resolver this package's event bridge
+ *   the CREDENTIAL (DX-4390), resolved by the ONE resolver this package's event relay
  *   also uses (`credential.ts`, DX-2862), and never a reason to exit:
  *     DANX_DASHBOARD_CREDENTIAL  the bearer verbatim (a dispatch, substituted into
  *                           the materialized `.mcp.json` from its overlay)
@@ -82,7 +82,11 @@
  * 5xx and network failures throw — never silently swallowed.
  */
 import { isEntrypointModule } from "./entrypoint.js";
-import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
+import { PlanEventRelay, WAIT_MAX_MS, WAIT_MIN_MS } from "./plan-events-relay.js";
+import { READ_IDLE_TIMEOUT_MS } from "./listen.js";
+import { REQUEST_TIMEOUT_MS, realScheduleInterval, realSleep } from "./session-stream.js";
+import { servePlanEventsWait } from "./plan-events-tool.js";
+import { stopWhenSessionEnds } from "./shutdown.js";
 import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./background-work.js";
 import { ACTIVITY_SUBCOMMAND, runActivityCommand } from "./activity.js";
 import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
@@ -157,9 +161,10 @@ let client;
 let listenerReminder;
 /**
  * DX-4390 — this server's credential: a dispatch's env bearer, this session's approved key, or
- * none (signed out). It also tells the session's plan event bridge how to reach the dashboard AS
- * THIS SERVER (`access.connection()`: the URL, where the credential is, its fingerprint; never the
- * credential itself), written to the session's connection record on a successful `plan_connect`.
+ * none (signed out). The plan event relay in this server signs in with it directly (`access.currentToken()`). The one-shot
+ * subcommands the plugin runs from hooks cannot see it, so `access.connection()` (the URL, where the credential is, its
+ * fingerprint; never the credential itself) is written to the session's connection record on a successful `plan_connect`
+ * for them.
  */
 let access;
 // DX-4434 — late-bound with `access` and `client`; see `permission-request.ts`.
@@ -167,6 +172,8 @@ let permissionRequests;
 // DX-4523 - late-bound with `access` and `client`; see `tool-surface.ts` and `permission-watch.ts`.
 let toolAccessSync;
 let permissionWatch;
+// DX-4233 - late-bound with `access`; see `plan-events-relay.ts`. The plugin's relay loop calls `plan_events_wait` on it.
+let planEventRelay;
 /**
  * Compose the dispatch's qualified board id (`<repo>:<slug>`) from the two env
  * halves the worker injects and build the HTTP client. DANXBOT_BOARD_NAME
@@ -226,13 +233,32 @@ function boot() {
     // before `server.connect()`) as a session with no key: the bootstrap set plus the callback tools this dispatch's worker
     // gave a URL for. `syncToolsAfterSignIn` widens it once the key's permissions are read. The DX-1606 tool-defs
     // generator imports this module WITHOUT calling `boot()`, so it still sees every tool enabled.
-    const surface = new ToolSurface(registeredTools, presentCallbacksFromEnv(), () => server.sendToolListChanged());
+    const surface = new ToolSurface(registeredTools, presentCallbacksFromEnv(), {
+        // A dispatch's credential is the env bearer its worker injected; a person's session holds none or its own session key.
+        operatorSession: access.connection()?.source.kind !== "env",
+        onChanged: () => server.sendToolListChanged(),
+    });
     surface.apply(new Set());
     toolAccessSync = new ToolAccessSync({
         surface,
         readPermissions: readHeldPermissions,
         log: (line) => console.error(line),
     });
+    // DX-4233 - the relay signs in as THIS server does, with the key it holds now, as this session.
+    planEventRelay = new PlanEventRelay({
+        auth: () => {
+            const connection = access.connection();
+            return connection === null || session === undefined
+                ? null
+                : { dashboardUrl: connection.dashboardUrl, token: access.currentToken(), sessionId: session.id };
+        },
+        fetch: (input, init) => fetch(input, init),
+        sleep: realSleep,
+        now: Date.now,
+        readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
+        requestTimeoutMs: REQUEST_TIMEOUT_MS,
+        scheduleInterval: realScheduleInterval,
+    });
     permissionWatch = new PermissionWatch({
         dashboardUrl,
         token: () => access.currentToken(),
@@ -304,7 +330,7 @@ async function syncToolsAfterSignIn() {
 const sleepHoldingProcess = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * DX-2862 / DX-4390 — the credential this server boots with, through the ONE resolver the
- * `bridge` subcommand also uses, so a session's tools and its event stream can never sign in as
+ * one-shot subcommands also use (`session-options.ts`), so a session's tools and its hook reports can never sign in as
  * two different identities. None is not an error: the server boots signed out. A stored key that
  * is there but unusable is reported loudly and deleted - it is a cache of a revocable key, and the
  * session asks for a new one.
@@ -347,10 +373,10 @@ function resolveInitialCredential(dashboardUrl, sessionId) {
  * calls `plan_connect` — so the title travels as that tool's own `title`
  * argument (see `handlers.ts#planConnect`) at connect time, not as a header
  * stamped here. DX-4461: the session's TRANSCRIPT carries every rename as a
- * `custom-title` record, so the event bridge (not this server) reads it from
+ * `custom-title` record, so the event relay in this server reads it from
  * there and reports it on its heartbeat (`session-title.ts`) and a later rename needs no
  * agent call. A session that never connects with a title keeps the
- * dashboard's own placeholder (`session <id prefix>`) until its bridge reports
+ * dashboard's own placeholder (`session <id prefix>`) until the relay reports
  * one — an honest placeholder beats a guess.
  */
 function readSessionConfig() {
@@ -656,7 +682,9 @@ strictTool("plan_connect",
     "`nextStep`). A session is on at most one plan: connecting elsewhere moves it, and `movedFrom` names the " +
     "plan it left. Afterwards a `danxbot_api` call to a `/api/plans/mine/...` route acts on this plan and " +
     "takes no plan id. A reply's `naming` block (status `needed`) gives your `{Name}: PLAN-NNN {short " +
-    "title}`; rename this thread to it (`set_session_title`, or ask for `/rename`), then connect again with that `title`.", {
+    "title}`; rename this thread to it (`set_session_title`, or ask for `/rename`), then connect again with that `title`. " +
+    // DX-4608: a connect never fails for its title.
+    "The connect itself succeeds whatever `title` you send.", {
     plan_id: z
         .number()
         .int()
@@ -667,13 +695,14 @@ strictTool("plan_connect",
         .string()
         .min(1)
         .optional()
-        .describe('The `naming` block\'s exact `{Name}: PLAN-NNN {short title}`, after renaming this thread. Omit on the first connect.'),
+        .describe(
+    // DX-4608: stored as sent; a wrong one does not refuse the connect, the reply's `naming` says what to rename it to.
+    'The `naming` block\'s exact `{Name}: PLAN-NNN {short title}`, after renaming this thread. Omit on the first connect.'),
     disconnect: z.boolean().optional().describe("true = leave `plan_id` (your current plan); no `title`."),
 }, 
-// DX-2862 — the connect is also the moment this session's event bridge learns
-// WHICH dashboard credential owns its stream: of the dashboard MCP servers a
-// session may have configured, the one that connected the plan is the one
-// whose credential the stream must be minted with.
+// DX-2862 — the connect is also the moment the session's connection record is written for the one-shot subcommands: of the
+// dashboard MCP servers a session may have configured, the one that connected the plan is the one whose credential they
+// must resolve (the relay needs none of this: it lives in each server, with that server's own credential).
 async (args) => {
     // DX-4390 — a leave names the plan it leaves, and needs a key like any other call.
     if (args.disconnect === true && args.plan_id === undefined) {
@@ -703,9 +732,9 @@ async (args) => {
     // DX-4523 - the key just worked: show the tools its permissions allow. After the refusals above, so a revoked or lapsed
     // key is found by the connect itself and answered as before.
     await syncToolsAfterSignIn();
-    // DX-3997 — a (re)connect restarts the bridge; the next `danxbot_api` must re-read health.
+    // DX-3997 — a (re)connect starts or re-keys the plugin's relay loop; the next `danxbot_api` must re-read health.
     listenerReminder.invalidate();
-    // DX-2985 — a leave drops the local connection record (the bridge exits on `not_connected`; a later connect writes a fresh one).
+    // DX-2985 — a leave drops the local connection record (the relay's stream ends `not_connected`; a later connect writes a fresh one).
     if (args.disconnect === true) {
         removeSessionConnectionAfterLeave(result, config.session?.id);
         return jsonResult(result);
@@ -724,14 +753,50 @@ async (args) => {
         }),
     });
 });
+// ---------------- plan_events_wait (DX-4233) ----------------
+strictTool("plan_events_wait", 
+// DX-4233 - for the danxbot plugin's relay loop, not for a model to call. It answers `events` (each `{cursor, text}`; empty after
+// `timeout_ms`), the cursor to send being the last delivered event's, or `stopped` with the remedy to tell the session. General-audience text
+// (DX-4550): nothing here names our own setup.
+"Waits for events on the plan this session is connected to. For the danxbot plugin's relay, which calls it in a loop " +
+    "and hands every event to the session: a model never calls it. `plan_id` is the plan the session is on (a different " +
+    "plan than the last call's starts clean). `cursor` is the `cursor` of the last event delivered, as answered (null " +
+    "when none). Answers `{events: [{cursor, text}]}`, with `events` empty once `timeout_ms` passes, or `{stopped: " +
+    "{reason, detail, fix}}` when the stream ended: tell the session the `fix`. An event stays until a later call's " +
+    "`cursor` passes it. " +
+    "`transcript_path` is the session's transcript file, for its usage and title.", {
+    plan_id: z.number().int().positive().describe("Id of the plan this session is connected to."),
+    cursor: z
+        .string()
+        .nullable()
+        .describe("The `cursor` of the last event delivered to the session, exactly as answered, or null when there is none."),
+    timeout_ms: z
+        .number()
+        .int()
+        .min(WAIT_MIN_MS)
+        .max(WAIT_MAX_MS)
+        .describe(`How long to wait for an event, ${WAIT_MIN_MS} to ${WAIT_MAX_MS} ms.`),
+    transcript_path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Absolute path of this session's transcript (.jsonl file)."),
+}, 
+// The relay is bound to the session the server booted for (the id every other tool on this server also sends); a server
+// with none holds no session key, so the surface never shows this tool and the relay would answer `credential_unavailable`.
+async (args, extra) => jsonResult(await servePlanEventsWait(planEventRelay, args, extra.signal)));
 // ---------------- main ----------------
 async function main() {
     boot();
     await syncToolsAfterSignIn();
-    // DX-4523 - the open permission stream would keep the process alive after the client goes away. The SDK's stdio transport
-    // does not watch stdin for its end (only a transport `close()` reaches `onclose`), so the end of stdin stops the watch too.
-    server.server.onclose = () => permissionWatch.stop();
-    process.stdin.once("end", () => permissionWatch.stop());
+    stopWhenSessionEnds({
+        server: server.server,
+        stdin: process.stdin,
+        stop: () => {
+            permissionWatch.stop();
+            planEventRelay.close();
+        },
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`danx-dashboard-mcp running on stdio (dashboard=${config.baseUrl}, board=${config.board ?? "none, each call names its own"})`);
@@ -743,26 +808,17 @@ async function main() {
 // symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
 // spawns, not just a direct `node dist/index.js`.
 //
-// `bridge` is the session event stream client the danxbot plugin's plan
-// event bridge runs. It never boots the MCP server; its only input is
-// `CLAUDE_CODE_SESSION_ID` (read from its environment) plus `--resume-ids` —
-// the dashboard URL, credential source, and credential itself come from the
-// session-connection record this server's own `plan_connect` wrote
-// (`session-connection.ts`), never from the bridge's own environment
-// (DX-2862: a bridge trusting its own ambient env credential is the
-// exact bug this repo fixed).
+// The subcommands are one-shot clients (activity, background-work, event-text, ready-cards, restart-notice, subagents-live)
+// the danxbot plugin runs. None boots the MCP server; the dashboard URL, credential source and credential come from the
+// session-connection record this server's own `plan_connect` wrote (`session-connection.ts`), never from the subcommand's own
+// environment (DX-2862: trusting an ambient env credential is the exact bug this repo fixed). There is no event-stream
+// subcommand: a session's plan events are served in this process by `plan_events_wait` (DX-4233).
 //
 // Any OTHER argument is refused rather than ignored, so a typo cannot
 // silently start an MCP server on stdio where a subcommand was meant to run.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
     const [subcommand, ...rest] = process.argv.slice(2);
-    if (subcommand === BRIDGE_SUBCOMMAND) {
-        runBridgeCommand(rest).then((code) => process.exit(code), (err) => {
-            console.error(`[danx-dashboard-mcp] bridge fatal: ${err.message}`);
-            process.exit(1);
-        });
-    }
-    else if (subcommand === BACKGROUND_WORK_SUBCOMMAND) {
+    if (subcommand === BACKGROUND_WORK_SUBCOMMAND) {
         runBackgroundWorkCommand(rest).then((code) => process.exit(code), (err) => {
             console.error(`[danx-dashboard-mcp] background-work fatal: ${err.message}`);
             process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
@@ -813,7 +869,7 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
     }
     else if (subcommand !== undefined) {
         console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BRIDGE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", "${ACTIVITY_SUBCOMMAND}", "${EVENT_TEXT_SUBCOMMAND}", ` +
+            `"${BACKGROUND_WORK_SUBCOMMAND}", "${ACTIVITY_SUBCOMMAND}", "${EVENT_TEXT_SUBCOMMAND}", ` +
             `"${RESTART_NOTICE_SUBCOMMAND}", "${READY_CARDS_SUBCOMMAND}", and "${SUBAGENTS_LIVE_SUBCOMMAND}")`);
         process.exit(2);
     }

package/dist/json-body.js

@@ -1,17 +1,17 @@
 /**
  * DX-2920 — the ONE place that reads a JSON body's top-level `.error` string.
  *
- * WHY THIS EXISTS. `bridge.ts` (classifying a mint refusal) and `listen.ts`
+ * WHY THIS EXISTS. the stream client (`session-stream.ts`, classifying a mint refusal) and `listen.ts`
  * (classifying a stream admission refusal) both need to answer "what error
  * code did this JSON body carry", and before this card each answered it a
- * different way: `bridge.ts` parsed the body directly, `listen.ts` never
+ * different way: the mint code parsed the body directly, `listen.ts` never
  * looked past a flattened, human-readable detail string at all — a caller
  * that wanted to react to a SPECIFIC refusal (the admission-time 409 the
  * mint route also uses) had to regex-scrape that flattened string back apart,
  * a second, fragile source of truth for the same fact. This module is generic
  * — it knows nothing about "session_not_connected" or "stream_ticket_invalid",
  * only that a JSON object may carry a top-level string field named `error` —
- * so it can live in BOTH the domain-aware `bridge.ts` and the deliberately
+ * so it can live in BOTH the domain-aware `session-stream.ts` and the deliberately
  * generic `listen.ts` (whose own docblock states it carries no domain
  * knowledge of the dashboard's specific error shapes) without either one
  * importing the other.

package/dist/listen.js

@@ -2,9 +2,9 @@
  * The session event STREAM READER — holds ONE listener ticket's connection to the
  * dashboard's session event stream and emits one record per event.
  *
- * WHO USES IT. Only `bridge.ts` (`danx-dashboard-mcp bridge`), which mints the
- * ticket, runs this reader in-process, and re-mints when a ticket's lease runs out.
- * The ticket therefore never leaves the bridge process: no command line, no
+ * WHO USES IT. Only the in-process event relay (`plan-events-relay.ts`), which mints the
+ * ticket, runs this reader inside the MCP server, and re-mints when a ticket's lease runs out.
+ * The ticket therefore never leaves the server's memory: no command line, no
  * environment variable.
  *
  * THE OUTPUT CONTRACT (`ListenOutput`), because every event record reaches an agent:
@@ -26,7 +26,7 @@
  *     `409 session_not_connected`, the same shape the mint route uses) by
  *     status + error code rather than re-deriving it from the flattened
  *     `detail` string. A wire `reason` value this build does not recognize (a
- *     newer dashboard's reason an older bridge hasn't shipped yet)
+ *     newer dashboard's reason an older client hasn't shipped yet)
  *     normalizes to `"unknown"` rather than passing the raw string through,
  *     so the closed set stays closed — `fixForStop`'s generic
  *     `DEFAULT_STOP_FIX` handles it exactly as it already handled a verbatim
@@ -62,7 +62,7 @@ export const DELIVERED_ID_MEMORY = 1_000;
 /**
  * DX-2829 — the ONE place that caps a resume-id list to the last
  * `DELIVERED_ID_MEMORY` entries. Both `runListener` (seeding its own
- * duplicate-detection `Set` below) and `bridge.ts`'s `runBridge` (seeding its
+ * duplicate-detection `Set` below) and the relay (`plan-events-relay.ts`) (seeding its
  * own delivered-id array) used to each carry their own `slice(-DELIVERED_ID_MEMORY)`
  * — the same cap, on the same kind of input, computed twice.
  */
@@ -457,14 +457,14 @@ export async function runListener(options, deps) {
     /**
      * The shared path of an ADVISORY frame (DX-2885 `nudge`, DX-4340 `pacing`): it carries no usable id (re-derived or written fresh by the
      * dashboard's keep-alive tick, never replayed - see `plan-session-stream.ts`'s module doc), so it rides the SAME `{type:"event", id:null, text}`
-     * shape an ordinary activity line uses. That is what lets `bridge.ts` and the plugin's relay (`danxbot/scripts/plan-event-bridge.mjs`, outside
-     * this repo) forward it with NO changes: both forward any `{type:"event", id, text}` line keyed only on `type`.
+     * shape an ordinary activity line uses. That is what lets the relay (`plan-events-relay.ts`) forward it with no change: it forwards any
+     * `{type:"event", id, text}` record, keyed only on `type`.
      *
      * `origin: null` is DX-2730 D4's exemption: the frame is delivered at once, never held for a digest flush (a nudge exists to interrupt a quiet
      * session; a pacing change is an instruction to act now). A frame that is not JSON or not the right shape is reported from an explicit check
      * naming the fault, and the next frame still emits.
      */
-    const emitAdvisory = (message, what, invalidReason, format) => {
+    const emitAdvisory = (message, what, invalidReason, format, scope) => {
         let parsed;
         let invalid;
         try {
@@ -475,7 +475,7 @@ export async function runListener(options, deps) {
             invalid = `not JSON: ${err.message}`;
         }
         const text = invalid === null ? format(parsed) : `${LINE_PREFIX} could not read ${what} (${invalid}): ${oneLine(message.data, 300)}`;
-        deps.write({ type: "event", id: null, text, origin: null });
+        deps.write({ type: "event", id: null, text, origin: null, ...(scope === undefined ? {} : { scope }) });
         return null;
     };
     const handle = (message) => {
@@ -492,7 +492,7 @@ export async function runListener(options, deps) {
             const reasonRaw = isRecord(parsed) ? parsed.reason : undefined;
             const reason = typeof reasonRaw === "string" ? reasonRaw : "unknown";
             // DX-2920 (round 4) — a wire reason this build does not recognize (a
-            // newer dashboard's reason an older bridge hasn't shipped yet)
+            // newer dashboard's reason an older client hasn't shipped yet)
             // normalizes to "unknown" rather than passing the raw string through:
             // `Outcome`'s "ended" reason is a closed set (`EndedReason`).
             return { kind: "ended", reason: isKnownWireEndReason(reason) ? reason : "unknown" };
@@ -501,10 +501,10 @@ export async function runListener(options, deps) {
             return emitAdvisory(message, "nudge", invalidNudgeReason, (p) => formatNudgeLine(p));
         // DX-4340 - the pacing tick's one message for this session's Claude account (level or budget changed): advisory like a nudge.
         if (message.event === "pacing")
-            return emitAdvisory(message, "pacing message", invalidPacingReason, (p) => formatPacingLine(p));
+            return emitAdvisory(message, "pacing message", invalidPacingReason, (p) => formatPacingLine(p), "session");
         // DX-4342 - the auto-resume's message once the limit that paused or stopped this session has reset: advisory like a pacing message.
         if (message.event === "resume")
-            return emitAdvisory(message, "resume message", invalidResumeReason, (p) => formatResumeLine(p));
+            return emitAdvisory(message, "resume message", invalidResumeReason, (p) => formatResumeLine(p), "session");
         if (message.event !== "activity")
             return null;
         // `Number(null)` is 0, so a frame with no id must never be read as event 0: that id
@@ -550,6 +550,7 @@ export async function runListener(options, deps) {
         // attempt (including before the fetch even starts) targets exactly this
         // controller, never a stale one from a previous attempt.
         deps.onConnectionAttempt?.(() => controller.abort());
+        deps.signal?.addEventListener("abort", () => controller.abort(), { once: true });
         let idle;
         const armIdle = () => {
             clearTimeout(idle);
@@ -570,7 +571,7 @@ export async function runListener(options, deps) {
             if (response.status >= 400 && response.status < 500 && !RETRYABLE_CLIENT_STATUSES.has(response.status)) {
                 const text = await response.text();
                 // DX-2920 — parsed ONCE, here, into a structured outcome a consumer can
-                // classify by status + error code (`bridge.ts` does, matching a specific
+                // classify by status + error code (the relay does, matching a specific
                 // admission refusal such as the dashboard's own `409 session_not_connected`)
                 // rather than re-deriving it from the flattened `detail` string below.
                 let body = null;
@@ -624,7 +625,12 @@ export async function runListener(options, deps) {
         }
     };
     for (;;) {
+        if (deps.signal?.aborted)
+            return 0;
         const outcome = await connectOnce();
+        // DX-4233 - cancelled while connected: the outcome of an attempt the owner abandoned is not the owner's to hear.
+        if (deps.signal?.aborted)
+            return 0;
         if (outcome.kind === "ended") {
             if (outcome.reason === "superseded" || outcome.reason === "replaced") {
                 return stop(outcome.reason, "another listener for this session took over", 0);

package/dist/one-shot-session-request.js

@@ -18,13 +18,13 @@
  *     alone rather than colliding with "the JSON didn't parse"
  *     (`bad_response`).
  *   - `resolveSessionOptions` — session-id + credential resolution via
- *     `resolveBridgeOptions`, with `BridgeStartError` narrowed by
- *     `instanceof` rather than an unchecked `as BridgeStartError` cast, so
+ *     `resolveDashboardAuth`, with `SessionStartError` narrowed by
+ *     `instanceof` rather than an unchecked `as SessionStartError` cast, so
  *     an error of some OTHER shape (a bug in the resolver, a thrown
  *     non-Error) still comes back as a reported reason instead of a value
  *     whose `.reason`/`.message`/`.fix` fields are silently `undefined`.
  */
-import { SESSION_ID_HEADER, resolveBridgeOptions, BridgeStartError } from "./bridge.js";
+import { SESSION_ID_HEADER, resolveDashboardAuth, SessionStartError } from "./session-options.js";
 /**
  * One authenticated HTTP call to this session's dashboard, with a hard
  * timeout. Never throws — a network failure or an abort is reported as
@@ -84,15 +84,15 @@ export async function resolveSessionOptions(env, resolveFrom, usage) {
         return { ok: false, output: { ok: false, reason: "no_session_id" }, detail: usage };
     }
     try {
-        const options = resolveBridgeOptions({ sessionId, resumeIds: [] }, env, resolveFrom);
+        const options = resolveDashboardAuth(sessionId, env, resolveFrom);
         return { ok: true, options };
     }
     catch (err) {
-        // DX-3367 fix-up — `instanceof`, never an unchecked `as BridgeStartError`
-        // cast: `resolveBridgeOptions` throws exactly `BridgeStartError` today,
+        // DX-3367 fix-up — `instanceof`, never an unchecked `as SessionStartError`
+        // cast: `resolveDashboardAuth` throws exactly `SessionStartError` today,
         // but a cast reports a fabricated reason/message/fix (all `undefined`)
         // for any OTHER thrown shape instead of a real one, silently.
-        if (err instanceof BridgeStartError) {
+        if (err instanceof SessionStartError) {
             return {
                 ok: false,
                 output: { ok: false, reason: err.reason },