@thehammer/danx-dashboard-mcp 0.1.286 → 0.1.289

package/README.md

@@ -9,7 +9,7 @@ Stdio MCP server fronting danxbot's dashboard HTTP API. Since DX-3465 it exposes
 | Var | Purpose |
 |---|---|
 | `DANXBOT_DASHBOARD_URL` | Dashboard base, e.g. `http://danxbot-dashboard:5555` (inside compose) or `http://localhost:5555` (host). An operator session gets it from the danxbot plugin: its `dashboard_url` option (default the hosted dashboard), overridden by `DANXBOT_DASHBOARD_URL` in your shell or a repo's committed `.claude/settings.json` `env` block |
-| `DANX_DASHBOARD_CREDENTIAL` | A DISPATCH's credential: the bearer verbatim, substituted into the materialized `.mcp.json` from its overlay (DX-2862, `src/credential.ts`). Authoritative when set; it never signs out. An operator session sets nothing: with no credential the server boots SIGNED OUT, every tool except `plan_connect` returns one "not signed in" halt, and `plan_connect` requests access (below). The one-shot subcommands use the same resolver, so a session's tools and its hook reports can never sign in as two different identities; the relay in this server (`plan_events_wait`) signs in with the server's own credential |
+| `DANX_DASHBOARD_CREDENTIAL` | A DISPATCH's credential: the bearer verbatim, substituted into the materialized `.mcp.json` from its overlay (DX-2862, `src/credential.ts`). Authoritative when set; it never signs out. An operator session sets nothing: with no credential the server boots SIGNED OUT, every tool except `plan_connect` returns one "not signed in" halt, and `plan_connect` requests access (below). `restart_notice` uses the same resolver, so a session's tools and its predecessor lookups can never sign in as two different identities; the relay in this server (`plan_events_wait`) signs in with the server's own credential |
 | `DANXBOT_TEAM` | OPTIONAL, non-secret (DX-4446): the team slug (or id) whose approvers see this session's access request in their danxbot site. Set it in your shell or a repo's committed `.claude/settings.json` `env` block. Unset, the request is answered by link only. A value that is not a team slug fails at boot; a team the dashboard does not know makes `plan_connect` answer `unknown_team` (fix `DANXBOT_TEAM`), never a silent link fallback |
 | `DANX_REPO_NAME` | OPTIONAL (DX-4555): repo half of the qualified board id; sent as the access request's repo label |
 | `DANXBOT_BOARD_NAME` | OPTIONAL (DX-4555; needs `DANX_REPO_NAME`): board-slug half of the qualified board id (the dispatch injects `board.slug` here). With neither variable set (the danxbot plugin's own server) the server has no default board: a call that needs a board must carry its `board` argument or the dashboard answers 400 (plan and plan-session routes take their boards from the plan and need none) |
@@ -20,7 +20,7 @@ BOARD-ONLY (DX-1171): board is the first-level concept; repo is DERIVED from boa
 
 An operator session has no stored credential. Signed out, `plan_connect` (optionally with `title`, the session's own Claude title) posts `POST /api/access-requests` and answers at once `{state: "approval_required", approvalUrl, confirmCode, expiresAt, instruction}`: show the user the code and open the URL; they approve in the dashboard. The server polls `POST /api/access-requests/claim` in the background, so the key is stored when the approval lands; the next `plan_connect` waits up to about 45 seconds for it, then connects, or answers `approval_pending`. One tool call never blocks for minutes. `denied` is reported once; a request that lapsed (the dashboard deletes it within about a minute of expiry, so a claim answers 404) starts a fresh one on the next call.
 
-- **Storage.** `~/.config/danxbot/session-keys/<sha12(dashboard url)>/<session id>.json`, mode 0600, written write-then-rename, pruned after 7 days. One file per dashboard and per session; this server reads it at boot, and a one-shot subcommand reads the same file through the `session-key` credential source and proves the fingerprint. The key lapses on the dashboard after 24 hours without use (every authenticated call, the relay's heartbeat included, renews it), and is revocable from the account page.
+- **Storage.** `~/.config/danxbot/session-keys/<sha12(dashboard url)>/<session id>.json`, mode 0600, written write-then-rename, pruned after 7 days. One file per dashboard and per session; this server reads it at boot, and `restart_notice` reads the same file through the `session-key` credential source and proves the fingerprint. The key lapses on the dashboard after 24 hours without use (every authenticated call, the relay's heartbeat included, renews it), and is revocable from the account page.
 - **A 401 on the stored key** deletes the file and returns the sign-in halt (in `plan_connect`: a new request in the same call). That is a key that lapsed. A key a PERSON revoked is answered `401 key_revoked` (DX-4418): the key file is deleted and EVERY dashboard tool, `plan_connect` included, returns one stop halt (who revoked it and when; commit work in progress and end; a dispatched agent makes no further call), for the rest of the process. No access request is made. The worker finds the revocation itself and ends the dispatch as revoked (every dashboard route, the dispatch-complete one included, refuses a revoked key). `plan_events_wait` answers `stopped` with the reason `key_revoked` the same way. **A 404 on create** means the dashboard predates request-and-approve and says so.
 - A dispatch's `DANX_DASHBOARD_CREDENTIAL` skips all of this. There is no token-file credential source.
 
@@ -63,7 +63,7 @@ Card and plan reads/writes go through `danxbot_api` against the issue/plan route
 
 A program calls this, not a person: the danxbot Claude Code plugin's relay loop, inside the session, calls it over and over on the session's own danx-dashboard MCP server and hands every event it gets to the session. A plan-orchestrator dispatch (a headless session that works one plan) has no plugin relay, so it keeps ONE background waiter sub-agent that loops on this tool until events exist and returns them with the last cursor, and the orchestrator passes that cursor to the next waiter it arms (DX-4667); the `plan-orchestrator` profile alone is granted the tool on a dispatch (it is an opt-in tool). The `bridge` subcommand is gone: no process is spawned, no `npx` cold start, and nothing outlives the session, because the stream lives in the MCP server, which ends with its session.
 
-Input `{plan_id: number, cursor: string | null, timeout_ms: 1000..30000, transcript_path?: string}`. Answer, one of:
+Input `{plan_id: number | null, cursor: string | null, timeout_ms: 1000..30000, transcript_path?: string}`. `plan_id` is `null` for a signed-in session on no plan (DX-4882): its stream still carries the pacing and resume messages of its Claude account, and it receives no plan events. A move between a plan and `null` starts clean like a move between plans: the plan-scoped records of the plan left are dropped, the session-scoped ones kept. Answer, one of:
 
 - `{events: [{cursor: string, text: string, urgent: boolean}]}`: every record the caller has not delivered, in arrival order (empty at the timeout). Each record carries the cursor to store once THAT record is delivered. There is no `id`: the caller compares nothing. `urgent` (DX-4721) is decided in one place by the record's kind (`src/urgent-records.ts`): true for a critical usage-pacing stop and the revoked-key notice, false for everything else (activity events, nudge, resume message, digest, the relay's failure notice, an unreadable line). The caller adds an urgent record to a running turn at once and delivers any other after the turn ends; `urgent` never changes order, seq or acknowledgement. The dashboard writes no operator-stop record yet; when it does, it becomes one more kind in that function.
 - `{stopped: {reason, detail, fix}}`: a terminal outcome (`not_connected`, `plan_archived`, `unauthorized`, `key_revoked`, `mint_refused`, `mint_bad_response`, `session_is_worker`, `superseded`, `replaced`, `revoked`, `refused`, `credential_unavailable`, `relay_failed`). `fix` is the remedy text (`STOP_FIXES`, `src/stop-fixes.ts`). The next call starts from scratch.
@@ -79,8 +79,6 @@ The contract the plugin builds against:
 - **Nothing outlives the session.** The heartbeat interval, the backoff sleep and the digest hold are unref'd; `close()` (run when the transport closes and when stdin ends) aborts the stream and the mint and inventory requests and clears a pending call's wait timer, the one ref'd timer, which otherwise holds the process only until the call answers.
 - **Credential and audience.** The server's own, from its boot-time `CLAUDE_CODE_SESSION_ID`: no connection record, fingerprint check or environment variable is involved. The tool is advertised only to a person's session holding `plans.view`, never to a dispatch. The stream's advisory frames (the idle nudge, DX-4340's pacing message, DX-4342's auto-resume message) arrive as records like any event, at once and never held for a digest. The digest (agent and machine events held up to 10 minutes) is one record, `[plan events] digest`, and a held id is never acknowledged before it is returned.
 
-The one-shot subcommands below (`activity`, `background-work`, `ready-cards`) still read the connection record this server wrote on `plan_connect` (`src/session-connection.ts`) and refuse to run unless the credential it names fingerprints identically (`credential_mismatch`, DX-2862).
-
 ## `restart_notice` — what a restarted session was working on (DX-3928, DX-4632)
 
 A tool for the danxbot plugin's session-start hook, not for a model, advertised only on a person's session (never a dispatch) and **usable before sign-in**: a restarted Claude Code session gets a new session id, no plan binding and, until a person approves its first call, no dashboard key of its own, so nothing else could tell it that the plan it had been working was unattended. `plan_connect` writes the session's working directory into its connection record (`projectKey`, record schema v2); `restart_notice` finds the newest OTHER sessions' records for the same project (at most ten, each within `STALE_RECORD_MS`), resolves each record's own credential, and asks `GET /api/plan-sessions/<predecessor>/restart-notice` which plan it was on and how many operator events wait there (the connect digest's own query, read-only). No arguments. Answers one of:
@@ -91,10 +89,6 @@ A tool for the danxbot plugin's session-start hook, not for a model, advertised
 
 ONE deadline of 8 s bounds the whole lookup, every candidate included (each request also keeps its own 5 s bound), so a hung dashboard answers `lookup_timeout` and never wedges a session start. A record from an older server (schema v1) is skipped here and refused, with the fix, everywhere a session reads its OWN record.
 
-## `ready-cards` — the plan's cards anyone could pick up now (DX-4534)
-
-Run by the danxbot plugin's Stop hook for a plan-connected session. `GET /api/plans/mine` answers the session's plan and the boards its cards live on (a session on no plan is a 409 `session_not_connected`, read as an empty answer); then, for each board, `GET /api/issues?board=` with `filter.plan_id` + `filter.status_derived` returns the plan's ToDo cards, and the ready ones are kept: a Story, Bug or Chore with no assigned agent, no live dispatch, no block, no open problem, no unmet `depends_on` and no active `conflict_on`. No dashboard route was added. Exit 0 prints one JSON line `{"plan_id": <n|null>, "cards": [{"id", "title"}]}`; exit 1 prints one stderr line that starts with its reason (`credential_unavailable`, `no_connection_record`, `http_error`, ...) and nothing on stdout.
-
 ## `subagents-live` — the plan pane's local live sub-agent feed (DX-4508)
 
 `danx-dashboard-mcp subagents-live <absolute path to the session's main transcript .jsonl>`. Spawned by the danxbot plugin's plan pane, which cannot tail files itself; the dashboard's sub-agent read lags the transcript by about 80s, this by about one second. It tails the session's transcript tree (the main file and `<session-id>/subagents/agent-*.jsonl` beside it) with the same `SessionLogWatcher` the relay runs, from byte 0 once and then only appended bytes, polling every second, and computes each sub-agent through `@thehammer/danx-session-telemetry`'s `createSubagentLiveView` (the same observer, ledger counter and pricing rule the dashboard uses). stdout carries only `{"subagents":[...]}` lines: the first, after the catch-up read, holds every sub-agent (an empty array when there are none); each later one holds only the sub-agents a poll changed. No network, no credential. A missing, relative or non-`.jsonl` path exits 2 with one stderr line; SIGTERM, SIGINT or a closed stdout exits 0.

package/dist/credential.js

@@ -2,10 +2,10 @@
  * DX-2862 / DX-4390 - the ONE resolver for this package's dashboard credential.
  *
  * WHY IT IS ONE FUNCTION AND NOT TWO. Two kinds of caller speak to the dashboard for the same
- * Claude Code session: the MCP SERVER (the session's tools and its event relay) and the one-shot subcommands the plugin runs
- * from hooks. When they resolved their credential independently they could differ (DX-2862): the session's tools worked, a
- * subcommand authenticated as somebody else, and its result was dropped with no error anywhere. So resolution lives HERE,
- * both go through it, and a subcommand additionally PROVES it holds the server's credential by comparing fingerprints
+ * Claude Code session: the MCP SERVER (the session's tools and its event relay) and the `restart_notice` predecessor lookup.
+ * When they resolved their credential independently they could differ (DX-2862): the session's tools worked, a
+ * lookup authenticated as somebody else, and its result was dropped with no error anywhere. So resolution lives HERE,
+ * both go through it, and the lookup additionally PROVES it holds the server's credential by comparing fingerprints
  * (`session-connection.ts`).
  *
  * A credential comes from exactly one of two places:
@@ -27,7 +27,7 @@ export const CREDENTIAL_TOKEN_ENV = "DANX_DASHBOARD_CREDENTIAL";
 /**
  * A credential that cannot be resolved. Carries the remedy beside the reason, because both of this
  * module's callers report failures to a human who is not reading a log: the server prints it to
- * stderr, and a one-shot subcommand prints it for the hook that ran it.
+ * stderr, and `restart_notice` answers it to the session.
  */
 export class CredentialError extends Error {
     fix;

package/dist/index.js

@@ -88,9 +88,6 @@ import { REQUEST_TIMEOUT_MS, realScheduleInterval, realSleep } from "./session-s
 import { servePlanEventsWait } from "./plan-events-tool.js";
 import { lookupRestartNotice, RESTART_NOTICE_ARGS } from "./restart-notice.js";
 import { stopWhenSessionEnds } from "./shutdown.js";
-import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./background-work.js";
-import { ACTIVITY_SUBCOMMAND, runActivityCommand } from "./activity.js";
-import { READY_CARDS_SUBCOMMAND, runReadyCardsCommand } from "./ready-cards.js";
 import { SUBAGENTS_LIVE_SUBCOMMAND, runSubagentsLiveCommand } from "./subagents-live.js";
 import { resolveBootCredential } from "./credential.js";
 import { SessionKeyUnusableError, deleteSessionKey } from "./session-key.js";
@@ -161,10 +158,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). 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
+ * none (signed out). The plan event relay in this server signs in with it directly (`access.currentToken()`).
+ * `restart_notice` runs against other sessions' credentials and 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.
+ * for it.
  */
 let access;
 // DX-4434 — late-bound with `access` and `client`; see `permission-request.ts`.
@@ -329,8 +326,8 @@ 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
- * one-shot subcommands also use (`session-options.ts`), so a session's tools and its hook reports can never sign in as
+ * DX-2862 / DX-4390 — the credential this server boots with, through the ONE resolver
+ * `restart_notice` also uses (`session-options.ts`), so a session's tools and its lookups 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.
@@ -737,7 +734,7 @@ strictTool("plan_connect",
     '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 the session's connection record is written for the one-shot subcommands: of the
+// DX-2862 — the connect is also the moment the session's connection record is written for `restart_notice` and the listener reminder: 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) => {
@@ -771,7 +768,7 @@ async (args) => {
     await syncToolsAfterSignIn();
     // 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 relay's stream ends `not_connected`; a later connect writes a fresh one).
+    // DX-2985 — a leave drops the local connection record (its stream stays open, DX-4882: the relay keeps serving the session's pacing and resume messages; a later connect writes a fresh one).
     if (args.disconnect === true) {
         removeSessionConnectionAfterLeave(result, config.session?.id);
         return jsonResult(result);
@@ -792,20 +789,22 @@ async (args) => {
 });
 // ---------------- plan_events_wait (DX-4233) ----------------
 strictTool("plan_events_wait", 
+// DX-4882 - `plan_id` is null for a signed-in session on no plan: its stream still carries its account's pacing and resume messages.
 // DX-4233 - for the danxbot plugin's relay loop. DX-4667 - and for a background waiter sub-agent of a plan orchestrator, which
 // loops on it until events exist and returns them (and the cursor) to the orchestrator it wakes. It answers `events` (each
 // `{cursor, text, urgent}`; 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 a relay or a background waiter that calls it in a loop " +
-    "and hands every event to the session; do not call it for any other reason. `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 " +
+"Waits for events for this session: the events of the plan it is connected to, and the messages about its usage. For a relay " +
+    "or a background waiter that calls it in a loop and hands every event to the session; do not call it for any other reason. " +
+    "`plan_id` is the plan the session is on, or null when it is on no plan (then only the usage messages arrive; a different " +
+    "plan than the last call's, or a move to or from null, starts clean). `cursor` is the `cursor` of the last event delivered, as answered (null " +
     "when none). Answers `{events: [{cursor, text, urgent}]}`, 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. `urgent` is true for an event the session must hear at once (a critical usage limit, a revoked " +
     "key) and false for every other: deliver an urgent one to the session even while it is working, and any other once its " +
     "current turn ends. Only one wait is pending per session: a newer call ends the older. " +
     "`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."),
+    plan_id: z.number().int().positive().nullable().describe("Id of the plan this session is connected to, or null when it is on no plan."),
     cursor: z
         .string()
         .nullable()
@@ -861,40 +860,14 @@ 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`.
 //
-// The subcommands are one-shot clients (activity, background-work, ready-cards, 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).
+// The only subcommand is `subagents-live`, which the danxbot plugin's plan pane runs (DX-4508); it does not boot the MCP
+// server and uses no network or credential. 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 === 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`);
-            process.exit(0);
-        });
-    }
-    else if (subcommand === ACTIVITY_SUBCOMMAND) {
-        // DX-3284 — the same hook-only contract as background-work: a rejection prints one
-        // failure line and exits 0, so an async hook never surfaces a stack trace.
-        runActivityCommand(rest).then((code) => process.exit(code), (err) => {
-            console.error(`[danx-dashboard-mcp] activity fatal: ${err.message}`);
-            process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
-            process.exit(0);
-        });
-    }
-    else if (subcommand === READY_CARDS_SUBCOMMAND) {
-        // DX-4534 — the plugin Stop hook's read; exit 0 (one JSON line) / 1 (read failed).
-        runReadyCardsCommand(rest).then((code) => process.exit(code), (err) => {
-            console.error(`[danx-dashboard-mcp] ${READY_CARDS_SUBCOMMAND} fatal: ${err.message}`);
-            process.exit(1);
-        });
-    }
-    else if (subcommand === SUBAGENTS_LIVE_SUBCOMMAND) {
+    if (subcommand === SUBAGENTS_LIVE_SUBCOMMAND) {
         // DX-4508 — the plugin pane's local live sub-agent feed: stdout is its JSON Lines channel, so a fatal goes to
         // stderr only and exits 1; a refused path exits 2 from the command itself.
         runSubagentsLiveCommand(rest).then((code) => process.exit(code), (err) => {
@@ -903,9 +876,8 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
         });
     }
     else if (subcommand !== undefined) {
-        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BACKGROUND_WORK_SUBCOMMAND}", "${ACTIVITY_SUBCOMMAND}", ` +
-            `"${READY_CARDS_SUBCOMMAND}", and "${SUBAGENTS_LIVE_SUBCOMMAND}")`);
+        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is ` +
+            `"${SUBAGENTS_LIVE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/json-body.js

@@ -1,20 +1,9 @@
 /**
  * DX-2920 — the ONE place that reads a JSON body's top-level `.error` string.
  *
- * 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: 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 `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.
+ * WHY THIS EXISTS. the stream client (`session-stream.ts`, classifying a mint refusal such as `409 session_is_worker`) reads a refusal's
+ * error code from the parsed body, and this is the one place that decides what "carries an error code" means. Generic: it knows no
+ * dashboard error name, only that a JSON object may carry a top-level string field named `error`.
  */
 export function errorCodeOf(body) {
     return typeof body === "object" && body !== null && typeof body.error === "string"

package/dist/listen.js

@@ -16,16 +16,10 @@
  *     DX-4342's `resume` frame (`formatResumeLine`): all are advisory, written fresh by the dashboard's own keep-alive tick,
  *     and never replayed, so they ride this same shape with `id: null` rather
  *     than growing a THIRD output variant.
- *   - `{type:"stopped", reason, detail, refusal?}` — once, last. `reason`
+ *   - `{type:"stopped", reason, detail}` — once, last. `reason`
  *     is the dashboard's own end reason (`superseded`, `replaced`, `revoked`,
  *     `not_connected`), `refused` (the ticket was not admitted), or
- *     `lease_expired` (no healthy connection for the lease). DX-2920 —
- *     `refusal` is populated ONLY for `reason === "refused"`: `{status,
- *     errorCode, body}`, the admission response parsed ONCE here, so a
- *     consumer can recognize a SPECIFIC refusal (the dashboard's own
- *     `409 session_not_connected`, the same shape the mint route uses) by
- *     status + error code rather than re-deriving it from the flattened
- *     `detail` string. A wire `reason` value this build does not recognize (a
+ *     `lease_expired` (no healthy connection for the lease). A wire `reason` value this build does not recognize (a
  *     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
@@ -48,7 +42,6 @@
  * (`src/issues/db/issue-activity.ts`); this published package cannot import
  * danxbot source.
  */
-import { errorCodeOf } from "./json-body.js";
 import { LINE_PREFIX, oneLine } from "./one-line.js";
 import { pacingRelayLine } from "./pacing-relay.js";
 import { isUrgent } from "./urgent-records.js";
@@ -490,8 +483,8 @@ export async function runListener(options, deps) {
     };
     for (const id of capResumeIds(options.resumeIds))
         remember(id);
-    function stop(reason, detail, code, extra) {
-        deps.write({ type: "stopped", reason, detail, refusal: extra?.refusal });
+    function stop(reason, detail, code) {
+        deps.write({ type: "stopped", reason, detail });
         return code;
     }
     /**
@@ -614,24 +607,7 @@ export async function runListener(options, deps) {
             const response = await deps.fetch(options.streamUrl, { headers, signal: controller.signal });
             if (response.status >= 400 && response.status < 500 && !RETRYABLE_CLIENT_STATUSES.has(response.status)) {
                 const text = await response.text();
-                // DX-2920 — parsed ONCE, here, into a structured outcome a consumer can
-                // classify by status + error code (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;
-                try {
-                    body = text === "" ? null : JSON.parse(text);
-                }
-                catch {
-                    body = null;
-                }
-                return {
-                    kind: "refused",
-                    status: response.status,
-                    errorCode: errorCodeOf(body),
-                    body,
-                    detail: `HTTP ${response.status} ${oneLine(text, 300)}`,
-                };
+                return { kind: "refused", detail: `HTTP ${response.status} ${oneLine(text, 300)}` };
             }
             if (!response.ok || response.body === null) {
                 await response.body?.cancel();
@@ -682,9 +658,7 @@ export async function runListener(options, deps) {
             return stop(outcome.reason, "the dashboard ended this listener", 1);
         }
         if (outcome.kind === "refused") {
-            return stop("refused", `the dashboard refused the listener ticket: ${outcome.detail}`, 1, {
-                refusal: { status: outcome.status, errorCode: outcome.errorCode, body: outcome.body },
-            });
+            return stop("refused", `the dashboard refused the listener ticket: ${outcome.detail}`, 1);
         }
         if (outcome.detail !== undefined)
             lastDropDetail = outcome.detail;

package/dist/plan-events-relay.js

@@ -30,8 +30,9 @@
  *      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
+ *   3. ONE PLAN. A call names the plan the session is on (`planId`), or `null` for a signed-in session on no plan (DX-4882: its stream
+ *      still carries the pacing and resume messages of its account). A plan different from the last call's, to or from `null` included,
+ *      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
@@ -55,7 +56,7 @@
 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 { fetchPlanInventory, HEARTBEAT_INTERVAL_MS, heartbeatConnection, MAX_REFUSED_TICKETS_IN_A_ROW, mintTicket, } from "./session-stream.js";
 import { fixForStop } from "./stop-fixes.js";
 import { isUrgent } from "./urgent-records.js";
 /** The shortest and longest wait one call may ask for; a short ceiling keeps an orphaned waiter's life short. */
@@ -91,7 +92,8 @@ export class PlanEventRelay {
     buffer = [];
     waiter = null;
     run = null;
-    lastPlanId = null;
+    /** The plan the last call named (`null` = a session on no plan); `undefined` before the first call, which has no plan to have moved from. */
+    lastPlanId = undefined;
     /** 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`. */
@@ -103,6 +105,8 @@ export class PlanEventRelay {
     connectionState = "reconnecting";
     stoppedReason = null;
     lastInventoryError = null;
+    /** DX-4882: whether the connected plan's inventory has been read in this run (a session on no plan has none to read). */
+    inventoryRead = false;
     lastActivityAt = 0;
     heartbeat = null;
     reporter = null;
@@ -120,8 +124,10 @@ export class PlanEventRelay {
         // 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)
+        if (this.lastPlanId !== undefined && args.planId !== this.lastPlanId) {
             this.startClean();
+            this.planMovedInventory(args.planId);
+        }
         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
@@ -224,6 +230,31 @@ export class PlanEventRelay {
         // 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.
     }
+    /** Whether the last call named a plan (not `null` = no plan, not `undefined` = no call yet). */
+    onAPlan() {
+        return typeof this.lastPlanId === "number";
+    }
+    /**
+     * DX-4882: the plan changed, so the inventory read for the old one no longer describes the session. On no plan there is nothing to read (and
+     * nothing to report as unavailable); on a plan, a live run reads it now (a run that is not live reads it when it starts).
+     */
+    planMovedInventory(planId) {
+        this.inventoryRead = false;
+        this.lastInventoryError = null;
+        const run = this.run;
+        const auth = this.deps.auth();
+        if (planId === null || run === null || auth === null)
+            return;
+        void this.readInventory(run, auth, { ...this.deps, signal: run.abort.signal });
+    }
+    /** 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`) and tried again at the next re-mint. */
+    async readInventory(run, auth, http) {
+        const inventory = await fetchPlanInventory(auth, http);
+        if (!this.current(run))
+            return;
+        this.inventoryRead = inventory.kind === "ok";
+        this.lastInventoryError = inventory.kind === "ok" ? null : inventory.detail;
+    }
     /** The session moved to another plan: drop what was buffered or held for the plan it left; session-scoped records stay. */
     startClean() {
         this.dropPlanScoped();
@@ -297,6 +328,7 @@ export class PlanEventRelay {
         // 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;
+        this.inventoryRead = false;
         const run = { abort: new AbortController(), forceReconnect: null };
         this.run = run;
         void this.loop(run).catch((err) => {
@@ -336,7 +368,6 @@ export class PlanEventRelay {
         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;
@@ -356,14 +387,11 @@ export class PlanEventRelay {
                 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);
+            // DX-4882: only a session on a plan has an inventory to read.
+            if (!this.inventoryRead && this.onAPlan()) {
+                await this.readInventory(run, 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 };
@@ -412,9 +440,6 @@ export class PlanEventRelay {
                 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) {

package/dist/request-bound.js

@@ -1,7 +1,6 @@
 /**
  * DX-4632 - the ONE bound every dashboard request of this package shares: a timeout of its own, plus an OUTER signal that ends
- * the request early (a lookup's one deadline, a closed relay). Used by `sendSessionRequest` (`one-shot-session-request.ts`: the
- * one-shot subcommands and `restart_notice`) and by `request` in `session-stream.ts` (the relay's mint, inventory and
+ * the request early (a lookup's one deadline, a closed relay). Used by `sendSessionRequest` (`restart-notice.ts`) and by `request` in `session-stream.ts` (the relay's mint, inventory and
  * heartbeat), so the controller, the timer, the link to the outer signal and the cleanup exist once.
  */
 export function boundRequest(timeoutMs, outer) {

package/dist/restart-notice.js

@@ -7,7 +7,7 @@
  * working was unattended: six operator answers sat unread for an hour on 2026-10-01. The session's own connection record cannot
  * help (it does not exist yet); the PREVIOUS session's record can, found by the project key `plan_connect` wrote into it
  * (`findPredecessorCandidates`). So this asks the dashboard about each predecessor as the predecessor, with the credential
- * that predecessor's record names (`resolveDashboardAuth`, the resolver the one-shot subcommands use), which a signed-out
+ * that predecessor's record names (`resolveDashboardAuth`, the resolver `session-options.ts` holds), which a signed-out
  * session needs no key of its own to do. The tool is therefore usable signed out: it is declared like `plan_connect` (no
  * permission) and only on a person's session (`tool-access.ts`).
  *
@@ -41,12 +41,58 @@
  * no cursor on the server.
  */
 import { z } from "zod";
-import { sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
-import { resolveDashboardAuth, SessionStartError } from "./session-options.js";
+import { boundRequest } from "./request-bound.js";
+import { resolveDashboardAuth, SESSION_ID_HEADER, SessionStartError } from "./session-options.js";
 import { findPredecessorCandidates, projectKeyOf, readSessionConnection } from "./session-connection.js";
 import { checkedTranscriptPath } from "./session-stats.js";
 import { readTranscriptLineage, TranscriptReadAborted, TranscriptUnreadable } from "./transcript-lineage.js";
 import { fixForStop } from "./stop-fixes.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
+ * `RequestFailure`, exactly like any other classified failure the caller
+ * might produce from the status/body it gets back on success.
+ */
+export async function sendSessionRequest(options, path, init, deps) {
+    const bound = boundRequest(deps.requestTimeoutMs, deps.signal);
+    try {
+        try {
+            const response = await deps.fetch(`${options.dashboardUrl}${path}`, {
+                method: init.method,
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                    Accept: "application/json",
+                    ...(init.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                    [SESSION_ID_HEADER]: options.sessionId,
+                },
+                body: init.body,
+                signal: bound.signal,
+            });
+            const text = await response.text();
+            return { status: response.status, text };
+        }
+        catch {
+            // DX-3367 fix-up — the caught value is never inspected (an aborted
+            // fetch's own rejection shape varies by runtime), so binding it to a
+            // name the code never reads was dead weight the linter never caught.
+            return { ok: false, reason: bound.aborted() ? "timeout" : "request_failed" };
+        }
+    }
+    finally {
+        bound.release();
+    }
+}
+/** `JSON.parse`, classified rather than thrown — the ONE shared parse point
+ *  every caller uses once it has decided (from `status`) that the body is
+ *  worth reading at all. */
+export function tryParseJsonBody(text) {
+    try {
+        return { ok: true, body: text === "" ? null : JSON.parse(text) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
 export const RESTART_NOTICE_REQUEST_TIMEOUT_MS = 5_000;
 /** DX-4632: the whole lookup, every candidate included (the old hook's `timeout 8s`). */
 export const RESTART_NOTICE_DEADLINE_MS = 8_000;
@@ -58,7 +104,7 @@ export const RESTART_NOTICE_DEADLINE_MS = 8_000;
 export const RESTART_NOTICE_MAX_CANDIDATES = 10;
 /** The registry row whose text is the notice (`src/issues/reminders/seed.yaml`). */
 export const RESTART_NOTICE_REMINDER_KEY = "plan_restart.waiting_events";
-/** One authenticated GET (the shared one-shot request, so its bound and its failure names are the same), answering the notice text or `null`. */
+/** One authenticated GET (`sendSessionRequest` above, so its bound and its failure names are the same), answering the notice text or `null`. */
 export async function fetchRestartNotice(target, deps) {
     // The bearer is the predecessor's; the session id header names the ASKING session.
     const auth = { dashboardUrl: target.dashboardUrl, token: target.token, sessionId: target.askingSessionId };

package/dist/session-connection.js

@@ -1,9 +1,8 @@
 /**
  * DX-2862 — the record that hands ONE Claude Code session's dashboard
- * connection from its MCP server to the plugin's hook subcommands.
+ * connection from its MCP server to its other readers (`restart_notice`, the listener reminder).
  *
- * THE PROBLEM THIS SOLVES. A hook's subcommand (`activity`, `background-work`,
- * `ready-cards`) runs in the SESSION's environment, not in the MCP server's, which is the only
+ * THE PROBLEM THIS SOLVES. A reader outside the server process 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
@@ -11,8 +10,8 @@
  *
  * 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. A subcommand
- * reads that record, resolves the SAME source through the same resolver
+ * an env var — never a credential) and the credential's FINGERPRINT. A reader
+ * (`restart_notice`) 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 reporting as somebody else.
@@ -91,7 +90,7 @@ export function pruneStaleSessionFiles(dir, now) {
     }
 }
 /**
- * Record this session's connection. Write-then-rename, so a subcommand reading
+ * Record this session's connection. Write-then-rename, so a reader
  * concurrently sees the old record or the new one, never a torn one.
  */
 export function writeSessionConnection(record, options = {}) {
@@ -146,8 +145,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 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
+ * missing produces a session that is connected but whose `restart_notice` lookup and listener reminder cannot
+ * find its connection — 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,7 +156,7 @@ export function recordSessionConnectionAfterConnect(result, inputs, write = writ
     if (inputs.sessionId === undefined || inputs.sessionId === "") {
         return {
             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 and ready-cards reports will not reach the dashboard",
+                "`restart_notice` and the listener reminder will not find this session's connection",
         };
     }
     try {
@@ -173,7 +172,7 @@ export function recordSessionConnectionAfterConnect(result, inputs, write = writ
     catch (err) {
         return {
             connection_record_error: `connected, but recording this session's connection failed (${err.message}) — ` +
-                "the plugin's activity, background-work and ready-cards reports will not reach the dashboard until it succeeds",
+                "`restart_notice` and the listener reminder will not find this session's connection until it succeeds",
         };
     }
 }