@thehammer/danx-dashboard-mcp 0.1.285 → 0.1.287

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.
 
@@ -65,7 +65,7 @@ A program calls this, not a person: the danxbot Claude Code plugin's relay loop,
 
 Input `{plan_id: number, cursor: string | null, timeout_ms: 1000..30000, transcript_path?: string}`. Answer, one of:
 
-- `{events: [{cursor: string, text: string}]}`: 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.
+- `{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.
 
 The contract the plugin builds against:
@@ -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/digest-hold.js

@@ -1,3 +1,4 @@
+import { isUrgent } from "./urgent-records.js";
 export const DIGEST_INTERVAL_MS = 10 * 60_000;
 export const DIGEST_PREFIX = "[plan events]";
 /** ONE combined record for every event held since the last flush. */
@@ -39,7 +40,7 @@ export class DigestHold {
         const entries = this.held;
         this.held = [];
         const ids = entries.map((e) => e.id).filter((id) => id !== null);
-        this.emit({ type: "event", id: ids.length === 0 ? null : Math.max(...ids), ids, text: formatDigest(entries), origin: null });
+        this.emit({ type: "event", id: ids.length === 0 ? null : Math.max(...ids), ids, text: formatDigest(entries), origin: null, urgent: isUrgent({ source: "digest" }) });
     }
     /**
      * Stop the timer WITHOUT flushing. For a stop where a newer listener already streams this session and will receive (and

package/dist/heartbeat-reporter.js

@@ -85,7 +85,7 @@ export class HeartbeatReporter {
             // dashboard call says the same.
             if (answer.revocation !== null && !this.revocationAnnounced) {
                 this.revocationAnnounced = true;
-                this.deps.announce(keyRevokedHalt(answer.revocation, false));
+                this.deps.announce(keyRevokedHalt(answer.revocation, false), "key_revoked");
             }
             return answer;
         })
@@ -104,7 +104,7 @@ export class HeartbeatReporter {
             // The session finds out, rather than continuing to believe it is connected.
             this.deps.announce(oneLine(`${DIGEST_PREFIX} this session's listener stopped reaching the dashboard for ` +
                 `${Math.round((HEARTBEAT_SILENT_FAILURE_THRESHOLD * HEARTBEAT_INTERVAL_MS) / 1000)}s while it still ` +
-                `believed it was streaming — forcing a fresh connection now.`));
+                `believed it was streaming — forcing a fresh connection now.`), "relay_notice");
             // End the CURRENT connection now, rather than wait on the stream reader's own read-idle timeout (which this exact
             // failure mode can outlive indefinitely: the connection reads as established and keeps producing keep-alive bytes,
             // only the outbound heartbeat silently never lands). The new attempt reconnects with the SAME ticket; the

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) => {
@@ -794,14 +791,16 @@ async (args) => {
 strictTool("plan_events_wait", 
 // 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}`; empty after `timeout_ms`), the cursor to send being the last delivered event's, or `stopped` with the remedy
+// `{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 " +
-    "when none). Answers `{events: [{cursor, text}]}`, with `events` empty once `timeout_ms` passes, or `{stopped: " +
+    "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. Only one wait is pending per session: a newer call ends the older. " +
+    "`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."),
     cursor: z
@@ -859,40 +858,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) => {
@@ -901,9 +874,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/listen.js

@@ -51,6 +51,7 @@
 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";
 export const INITIAL_BACKOFF_MS = 1_000;
 export const MAX_BACKOFF_MS = 30_000;
 /** Three of the dashboard's 15 s keep-alives without a byte means the connection is dead. */
@@ -503,7 +504,7 @@ export async function runListener(options, deps) {
      * 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, scope) => {
+    const emitAdvisory = (message, what, invalidReason, format, sourceOf, scope) => {
         let parsed;
         let invalid;
         try {
@@ -514,7 +515,9 @@ 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, ...(scope === undefined ? {} : { scope }) });
+        // DX-4721: an unreadable frame is a fault line, never the frame it failed to be (a malformed `critical` pacing frame is not a stop).
+        const urgent = isUrgent(invalid === null ? sourceOf(parsed) : { source: "fault" });
+        deps.write({ type: "event", id: null, text, origin: null, urgent, ...(scope === undefined ? {} : { scope }) });
         return null;
     };
     const handle = (message) => {
@@ -537,13 +540,13 @@ export async function runListener(options, deps) {
             return { kind: "ended", reason: isKnownWireEndReason(reason) ? reason : "unknown" };
         }
         if (message.event === "nudge")
-            return emitAdvisory(message, "nudge", invalidNudgeReason, (p) => formatNudgeLine(p));
+            return emitAdvisory(message, "nudge", invalidNudgeReason, (p) => formatNudgeLine(p), () => ({ source: "nudge" }));
         // 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), "session");
+            return emitAdvisory(message, "pacing message", invalidPacingReason, (p) => formatPacingLine(p), (p) => ({ source: "pacing", level: p.level }), "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), "session");
+            return emitAdvisory(message, "resume message", invalidResumeReason, (p) => formatResumeLine(p), () => ({ source: "resume" }), "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
@@ -577,7 +580,9 @@ export async function runListener(options, deps) {
         // 10-minute digest wait just because it happened to come from an agent or
         // a machine writer.
         const origin = invalid === null ? parsed.origin : null;
-        deps.write({ type: "event", id: knownId ? id : null, text, origin });
+        // DX-4721: an unreadable event is a fault line; a readable one is urgent by its kind (none is today).
+        const urgent = isUrgent(invalid === null ? { source: "activity", kind: parsed.kind } : { source: "fault" });
+        deps.write({ type: "event", id: knownId ? id : null, text, origin, urgent });
         if (knownId)
             remember(id);
         return null;

package/dist/plan-events-relay.js

@@ -57,6 +57,7 @@ import { HeartbeatReporter } from "./heartbeat-reporter.js";
 import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, INITIAL_BACKOFF_MS, MAX_BACKOFF_MS, runListener, } from "./listen.js";
 import { classifyAdmissionRefusal, fetchPlanInventory, HEARTBEAT_INTERVAL_MS, heartbeatConnection, MAX_REFUSED_TICKETS_IN_A_ROW, mintTicket, } from "./session-stream.js";
 import { fixForStop } from "./stop-fixes.js";
+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. */
 export const WAIT_MIN_MS = 1_000;
 export const WAIT_MAX_MS = 30_000;
@@ -183,7 +184,7 @@ export class PlanEventRelay {
     }
     /** Everything buffered, each record with the cursor to store once it is delivered. */
     answer() {
-        return { events: this.buffer.map(({ seq, recent, text }) => ({ cursor: formatCursor({ seq, ids: recent }), text })) };
+        return { events: this.buffer.map(({ seq, recent, text, urgent }) => ({ cursor: formatCursor({ seq, ids: recent }), text, urgent })) };
     }
     // ------------------------------------------------------------------------------------------------------------ the buffer
     /**
@@ -200,7 +201,7 @@ export class PlanEventRelay {
                 this.seenIds.shift();
         }
         this.seq += 1;
-        this.buffer.push({ seq: this.seq, own, recent: [...this.recentIds], text: event.text, scope: event.scope ?? "plan" });
+        this.buffer.push({ seq: this.seq, own, recent: [...this.recentIds], text: event.text, scope: event.scope ?? "plan", urgent: event.urgent });
         const waiter = this.waiter;
         if (waiter === null)
             return;
@@ -246,7 +247,7 @@ export class PlanEventRelay {
             connection: () => heartbeatConnection(this.connectionState, this.stoppedReason, this.lastInventoryError),
             streaming: () => this.connectionState === "streaming",
             // `origin: null` skips the agent/machine hold: the notice reaches the session at once. It is about the session, not a plan.
-            announce: (text) => this.digest.route({ type: "event", id: null, text, origin: null, scope: "session" }),
+            announce: (text, source) => this.digest.route({ type: "event", id: null, text, origin: null, scope: "session", urgent: isUrgent({ source }) }),
             forceReconnect: () => this.run?.forceReconnect?.(),
         }, transcriptPath ?? null);
     }

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",
         };
     }
 }

package/dist/session-options.js

@@ -1,9 +1,9 @@
 /**
- * DX-2862 / DX-4233 - how a one-shot client of the dashboard (`activity`, `background-work`, `ready-cards`, and the
- * predecessor lookup of `restart_notice`) learns WHICH dashboard to call and AS WHOM: the connection record this session's own MCP server wrote when
- * it connected a plan (`session-connection.ts`), resolved through the same credential resolver the server used, and refused
- * unless it fingerprints identically. (The in-process relay behind `plan_events_wait` needs none of this: it lives inside the
- * server that holds the credential.)
+ * DX-2862 / DX-4233 - how `restart_notice` (`restart-notice.ts`, this file's only caller) learns which dashboard to call and
+ * as whom when it asks about an earlier session. It reads the connection record that session's own MCP server wrote when it
+ * connected a plan (`session-connection.ts`), resolves the credential the record names through the same resolver the server
+ * used, and refuses unless it fingerprints identically. The in-process relay behind `plan_events_wait` needs none of this: it
+ * lives inside the server that holds the credential.
  */
 import { homedir } from "node:os";
 import { credentialFingerprint, describeCredentialSource, readCredential } from "./credential.js";
@@ -52,7 +52,7 @@ export function resolveDashboardAuth(sessionId, env, options = {}) {
     const fingerprint = credentialFingerprint(token);
     if (fingerprint !== record.fingerprint) {
         throw new SessionStartError("credential_mismatch", `${describeCredentialSource(record.source)} now yields credential ${fingerprint}, but this session's ` +
-            `danx-dashboard MCP server is using ${record.fingerprint} — a one-shot call would authenticate as somebody else`, fixForStop("credential_mismatch"));
+            `danx-dashboard MCP server is using ${record.fingerprint} — a lookup would authenticate as somebody else`, fixForStop("credential_mismatch"));
     }
     return { dashboardUrl: record.dashboardUrl.replace(/\/+$/, ""), token, sessionId };
 }

package/dist/stop-fixes.js

@@ -1,8 +1,8 @@
 /**
  * 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 client that ends in these texts is the in-process relay behind `plan_events_wait` (`plan-events-relay.ts`); `session-options.ts` uses
+ * `fixForStop` for a start it 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.
@@ -15,10 +15,10 @@
 const RESTART_NOTICE_STOP_LEAD = "continue without it";
 const RESTART_NOTICE_STOP_TAIL = "call plan_connect to connect this session to a plan";
 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 " +
+    no_connection_record: "call plan_connect again in this session — its danx-dashboard MCP server records the connection that restart_notice and the listener reminder read " +
         "(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",
+    credential_mismatch: "restart this Claude Code session so its MCP server resolves its credential afresh, 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",

package/dist/urgent-records.js

@@ -0,0 +1,34 @@
+/**
+ * DX-4721 - THE ONE PLACE that decides whether a relayed plan-event record is URGENT.
+ *
+ * Background. `plan_events_wait` hands the caller (the danxbot plugin's relay, or a plan orchestrator's waiter sub-agent) a
+ * stream of records. The caller delivers an ordinary record after the session's running turn ends, and adds an URGENT one to
+ * the running turn at once. Which record is which is decided here, by the record's KIND, and nowhere else: every site that
+ * creates a record names its source and calls `isUrgent`; none writes an `urgent` literal of its own. The flag is a required
+ * boolean on `ListenEvent`, so a site that forgets it fails `make typecheck`, and no reader defaults a missing one.
+ *
+ * Urgent: a critical usage-pacing stop (the account is about to hit its limit and the session must wind down now), and the
+ * notice that this session's key was revoked (it can no longer call the dashboard). Everything else is not: activity events
+ * (comments, answers, problems, blocks, design and pull-request outcomes), the idle nudge, the auto-resume message, a digest,
+ * the relay's own failure notice, and any line that reports an unreadable event or frame (a fault line).
+ *
+ * The operator's direct stop. The dashboard writes no stop record today (the activity vocabulary, `IssueActivityKind` in
+ * `src/issues/db/issue-activity.ts`, and the stream's frames have none), so there is no kind to key on. When the dashboard adds
+ * one, it becomes a `RecordSource` here, urgent, in this same function: never a text match.
+ */
+/** DX-4721: true for a critical pacing stop and a revoked key; false for every other source (see the module docblock). */
+export function isUrgent(record) {
+    switch (record.source) {
+        case "pacing":
+            return record.level === "critical";
+        case "key_revoked":
+            return true;
+        case "activity":
+        case "nudge":
+        case "resume":
+        case "digest":
+        case "relay_notice":
+        case "fault":
+            return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.285",
+  "version": "0.1.287",
   "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",