@thehammer/danx-dashboard-mcp 0.1.286 → 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.
 
@@ -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) => {
@@ -861,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) => {
@@ -903,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/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/package.json

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

package/dist/activity.js

@@ -1,260 +0,0 @@
-/**
- * `danx-dashboard-mcp activity <SubagentStart|SubagentStop|PostToolUse> <event-at>` — the
- * ONE-SHOT client of `POST /api/plan-sessions/me/activity` (DX-3284).
- *
- * WHO RUNS IT. The danxbot Claude Code plugin's `SubagentStart`, `SubagentStop` and
- * `PostToolUse` (matcher `Bash`) hooks (`danxbot/scripts/activity-report.mjs` in
- * claude-plugins), all registered `async: true`. The plugin runs the INSTALLED package
- * with `node` (DX-3811), never a cold `npx`, and pipes the hook's own JSON envelope on
- * stdin. This module owns what each event MEANS for the session's running set; the plugin
- * decides only whether to call at all (a plan-connected session, a background Bash call).
- *
- * THE THREE EVENTS (the Claude Code hooks reference, `code.claude.com/docs/en/hooks`):
- *
- * | Event          | Reports                                                          | Key                        |
- * |----------------|------------------------------------------------------------------|----------------------------|
- * | `SubagentStart`| an `agent` activity, running                                     | `agent-<agent_id>`         |
- * | `SubagentStop` | the same activity, FINISHED                                      | `agent-<agent_id>`         |
- * | `PostToolUse`  | a `bash` activity, running — only for `Bash` with                | `tool_use_id`              |
- * |                | `tool_input.run_in_background: true`                             |                            |
- *
- * THE SUB-AGENT KEY. A sub-agent's transcript is `<session>/subagents/agent-<agent_id>.jsonl`,
- * and the transcript producer (`createActivityObserver`) keys its row on that file's
- * basename, `agent-<agent_id>`. Reporting the bare `agent_id` would upsert a SECOND row for
- * the same sub-agent, so the hook-side key is the same basename: the two producers converge
- * on one row. The hooks docs disagree on whether `agent_id` already carries the `agent-`
- * prefix, so {@link subagentActivityId} normalizes both forms to the one key.
- *
- * KNOWN LIMITS (DX-3284, pinned in `plan-session-activity.test.ts`):
- *   - a sub-agent RESUMED after its SubagentStop reports a second start, but the server's
- *     first finish wins, so the row stays closed;
- *   - a SubagentStop with no `agent_id` (Claude Code's internal agents) is refused below, and
- *     the plugin leaves a failure trace. One WITH an id but no recorded start is
- *     indistinguishable from a stop that beat its (async) start, so it is recorded as an
- *     already-finished row — it never counts as running. (`transcript_path` cannot supply it: on these events it is the MAIN session's
- * transcript — only `SubagentStop`'s `agent_transcript_path` names the sub-agent's own, and
- * it is used below to REFUSE a mismatch, never to guess one.)
- *
- * THERE IS NO "BACKGROUND SHELL FINISHED" EVENT. None of the documented hook events fires
- * when a `run_in_background` Bash command ends (verified against the full event list on
- * DX-2954's Step 0 note; `TaskCreated` / `TaskCompleted` are the `TaskCreate` tool, not a
- * shell). A `bash` activity therefore gets a start here and no finish: its end comes from
- * the dispatch's own terminal write (`finishOpenActivities`), never from inferring one out
- * of transcript lines. Until then it reads as running and silent, which is the honest
- * signal. Do not "fix" this with a proxy event.
- *
- * THE EVENT TIME is the hook's own, captured by the plugin when the hook FIRED and passed
- * as `<event-at>` — never this process's clock, which starts only after the (possibly
- * cold) install step. The server's upsert is monotone in every field, so hooks that finish
- * out of order, or one that fires twice, still reach the same row.
- *
- * THE CONTRACT (identical to `background-work`, so the plugin treats both alike):
- *   - print EXACTLY ONE JSON line on stdout and ALWAYS exit 0 — a hook has no business
- *     spamming the session with a stack trace;
- *   - `{"ok":true,"runningActivities":<n>}` on success;
- *   - `{"ok":false,"reason":"<why>"}` otherwise. `no_connection_record` and
- *     `session_not_connected` are the ordinary "this session is not on a plan" answers;
- *   - human-readable diagnostics go to stderr only.
- *
- * THE CREDENTIAL — the SAME resolver `plan_events_wait` uses (`resolveSessionOptions`): the URL,
- * credential source and credential come from the connection record this session's own MCP
- * server wrote on `plan_connect`, never from this process's ambient env (DX-2862).
- */
-import { win32 } from "node:path";
-import { readFileSync } from "node:fs";
-import { labelOf } from "@thehammer/danx-session-telemetry";
-import { parseEventAtArg } from "./background-work.js";
-import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
-export const ACTIVITY_SUBCOMMAND = "activity";
-export const ACTIVITY_PATH = "/api/plan-sessions/me/activity";
-/** How long this one-shot call may take before it counts as a timeout. */
-export const ACTIVITY_REQUEST_TIMEOUT_MS = 5_000;
-/** The hook events this subcommand accepts, exactly as Claude Code names them in `hook_event_name`. */
-export const ACTIVITY_HOOK_EVENTS = ["SubagentStart", "SubagentStop", "PostToolUse"];
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${ACTIVITY_SUBCOMMAND} <${ACTIVITY_HOOK_EVENTS.join("|")}> <event-at ISO-8601 UTC>  (the hook's JSON envelope on stdin)`;
-const SUBAGENT_PREFIX = "agent-";
-/**
- * A sub-agent's transcript file basename — the key `createActivityObserver` reports it under.
- *
- * DX-3284: the hooks documentation shows `agent_id` BOTH ways — SubagentStart's example carries
- * the `agent-` prefix (`agent-abc123`), SubagentStop's does not (`def456`, against the file
- * `agent-def456.jsonl`). The key is `agent-` + the id with ONE leading `agent-` stripped, so both
- * forms converge on the transcript producer's row; keying on the raw id would leave a phantom
- * `agent-agent-<id>` row that no stop ever closes.
- */
-export function subagentActivityId(agentId) {
-    const bare = agentId.startsWith(SUBAGENT_PREFIX) ? agentId.slice(SUBAGENT_PREFIX.length) : agentId;
-    return `${SUBAGENT_PREFIX}${bare}`;
-}
-/**
- * DX-4498 — the facts only a transcript knows (the spawning sub-agent, effort, current tool call, how a background task
- * ended, the card its spawning `Agent` call names). A hook envelope carries none of them, so it reports each as unknown; the server's merge
- * never lets an unknown erase a value the transcript producer stored. A `SubagentStop` names no status either: its
- * finish reads as `done` unless a task notification says otherwise.
- */
-const NO_TRANSCRIPT_FACTS = {
-    parentActivityId: null,
-    effort: null,
-    currentActivity: null,
-    endStatus: null,
-    briefIssueId: null,
-};
-function nonEmptyString(value) {
-    return typeof value === "string" && value !== "";
-}
-/**
- * One hook envelope -> the ONE `ActivityChange` it stands for, or the reason it stands for
- * none. Pure: `eventAtMs` is the hook's own event time.
- */
-export function activityChangeFromHook(event, envelope, eventAtMs) {
-    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) {
-        return { ok: false, reason: "bad_envelope" };
-    }
-    const e = envelope;
-    // The envelope names the event it was fired for; a mismatch is a wiring bug, not data.
-    if (e.hook_event_name !== undefined && e.hook_event_name !== event) {
-        return { ok: false, reason: "event_mismatch" };
-    }
-    if (event === "PostToolUse") {
-        const input = e.tool_input;
-        if (e.tool_name !== "Bash" || typeof input !== "object" || input === null) {
-            return { ok: false, reason: "not_background_bash" };
-        }
-        const toolInput = input;
-        if (toolInput.run_in_background !== true)
-            return { ok: false, reason: "not_background_bash" };
-        if (!nonEmptyString(e.tool_use_id))
-            return { ok: false, reason: "no_tool_use_id" };
-        return {
-            ok: true,
-            change: {
-                kind: "bash",
-                activityId: e.tool_use_id,
-                agentType: null,
-                // DX-4498 — agent-written free text, so it is redacted like every label that reaches the running set.
-                description: labelOf(toolInput.description),
-                startedAt: eventAtMs,
-                // No hook ever refreshes or ends a background shell (see the module docblock), so
-                // its liveness is its start and `finishedAt` stays null until the dispatch ends.
-                lastActivityAt: eventAtMs,
-                finishedAt: null,
-                ...NO_TRANSCRIPT_FACTS,
-            },
-        };
-    }
-    // A SubagentStop from one of Claude Code's own internal agents carries no `agent_id`: it names
-    // no activity, so it is refused here (the plugin leaves a failure trace) and nothing is
-    // written — a stop must never invent a row.
-    if (!nonEmptyString(e.agent_id) || e.agent_id === SUBAGENT_PREFIX)
-        return { ok: false, reason: "no_agent_id" };
-    const activityId = subagentActivityId(e.agent_id);
-    if (event === "SubagentStop" && e.agent_transcript_path !== undefined) {
-        // The one place the hook names the sub-agent's own file: if it disagrees with the
-        // key derived from `agent_id`, this process would upsert a duplicate row. Refuse.
-        const file = typeof e.agent_transcript_path === "string" ? win32.basename(e.agent_transcript_path, ".jsonl") : null;
-        if (file !== activityId)
-            return { ok: false, reason: "agent_id_mismatch" };
-    }
-    return {
-        ok: true,
-        change: {
-            kind: "agent",
-            activityId,
-            agentType: nonEmptyString(e.agent_type) ? e.agent_type : null,
-            description: null,
-            startedAt: eventAtMs,
-            lastActivityAt: eventAtMs,
-            finishedAt: event === "SubagentStop" ? eventAtMs : null,
-            ...NO_TRANSCRIPT_FACTS,
-        },
-    };
-}
-/**
- * One authenticated POST, with a hard timeout, classified into the output shape this
- * subcommand always prints — never a throw. Status is checked before any body is parsed
- * (an HTML 5xx page must read as `http_error`, not `bad_response`); only a 409 needs its
- * body, to tell "no plan" from "a worker's session".
- */
-export async function postActivity(options, change, deps) {
-    const sent = await sendSessionRequest(options, ACTIVITY_PATH, { method: "POST", body: JSON.stringify({ activities: [change] }) }, deps);
-    if ("reason" in sent)
-        return sent;
-    const { status, text } = sent;
-    if (status === 401 || status === 403)
-        return { ok: false, reason: "unauthorized" };
-    if (status === 409) {
-        const parsed = tryParseJsonBody(text);
-        const error = parsed.ok ? parsed.body?.error : undefined;
-        if (error === "session_not_connected" || error === "session_is_worker")
-            return { ok: false, reason: error };
-        return { ok: false, reason: "http_error" };
-    }
-    if (status < 200 || status >= 300)
-        return { ok: false, reason: "http_error" };
-    const parsed = tryParseJsonBody(text);
-    if (!parsed.ok)
-        return { ok: false, reason: "bad_response" };
-    const body = parsed.body;
-    if (typeof body?.runningActivities !== "number")
-        return { ok: false, reason: "bad_response" };
-    return { ok: true, runningActivities: body.runningActivities };
-}
-/** The bin's `activity` subcommand, wired to the real process. Always resolves to exit code 0. */
-export async function runActivityCommand(argv, env = process.env, 
-/** Test seam: the home the session's connection record is read from. */
-resolveFrom = {}, 
-/** Test seam: the hook envelope's text (the real process reads stdin). */
-readEnvelope = () => readFileSync(0, "utf8")) {
-    const write = (output) => {
-        process.stdout.write(`${JSON.stringify(output)}\n`);
-    };
-    const usageFailure = (detail) => {
-        write({ ok: false, reason: "usage" });
-        process.stderr.write(`${detail}\n${USAGE}\n`);
-        return 0;
-    };
-    if (argv.length !== 2)
-        return usageFailure("expected exactly two arguments");
-    const event = ACTIVITY_HOOK_EVENTS.includes(argv[0]) ? argv[0] : null;
-    if (event === null)
-        return usageFailure(`unknown hook event "${argv[0]}"`);
-    const eventAt = parseEventAtArg(argv[1]);
-    if (typeof eventAt === "object")
-        return usageFailure(eventAt.error);
-    let envelope;
-    try {
-        envelope = JSON.parse(readEnvelope());
-    }
-    catch {
-        write({ ok: false, reason: "bad_envelope" });
-        process.stderr.write("the hook envelope on stdin is not JSON\n");
-        return 0;
-    }
-    const mapped = activityChangeFromHook(event, envelope, Date.parse(eventAt));
-    if (!mapped.ok) {
-        write(mapped);
-        process.stderr.write(`${event} envelope reports no activity: ${mapped.reason}\n`);
-        return 0;
-    }
-    // The connection record is this session's: an envelope for ANOTHER session must never
-    // be reported under it.
-    const envelopeSession = envelope.session_id;
-    if (envelopeSession !== undefined && envelopeSession !== env.CLAUDE_CODE_SESSION_ID) {
-        write({ ok: false, reason: "session_mismatch" });
-        process.stderr.write("the envelope's session_id is not CLAUDE_CODE_SESSION_ID\n");
-        return 0;
-    }
-    const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
-    if (!resolved.ok) {
-        // A session that never `plan_connect`-ed has no connection record: the ordinary
-        // "not on a plan" case, silent for the plugin.
-        write(resolved.output);
-        process.stderr.write(`${resolved.detail}\n`);
-        return 0;
-    }
-    write(await postActivity(resolved.options, mapped.change, {
-        fetch: (input, init) => fetch(input, init),
-        requestTimeoutMs: ACTIVITY_REQUEST_TIMEOUT_MS,
-    }));
-    return 0;
-}

package/dist/background-work.js

@@ -1,162 +0,0 @@
-/**
- * `danx-dashboard-mcp background-work <count|clear> <event-at>` — the ONE-SHOT client of
- * `PUT /api/plan-sessions/me/background-work` (DX-3367).
- *
- * WHO RUNS IT. The danxbot Claude Code plugin's `Stop` / `SubagentStop` /
- * `SessionStart` / `StopFailure` hooks (`danxbot/hooks/hooks.json` in
- * claude-plugins), via the SAME `npx -y @thehammer/danx-dashboard-mcp`
- * MECHANISM the plugin already uses for `plan_events_wait` — no separate install, no
- * deep import of this package's `dist/` internals.
- * DX-3367 fix-up — that does NOT mean the SAME PINNED VERSION: `npx -y
- * <pkg>` resolves whatever version string that ONE hook's own invocation
- * names, and this plugin's hooks pin each call independently (verified
- * against production drift, comment 7102 on the card: the background-work
- * hooks pinned `0.1.136` while `plan_events_wait` was still pinned `0.1.95`) — a
- * version bump to one hook's pin never moves the others. The plugin decides
- * WHAT to report (parsing `Stop`/`SubagentStop`'s own `background_tasks`
- * snapshot, counting only `shell` / `subagent` / `workflow` entries,
- * sending `clear` on `SessionStart`/`StopFailure`); this module only
- * delivers the report.
- *
- * THE CONTRACT (binding, so a future plugin build against this module can
- * trust it without re-reading this file):
- *   - print EXACTLY ONE JSON line on stdout, and ALWAYS exit 0 — success or
- *     failure alike, because a hook must stay silent rather than spam the
- *     session's own turn with a stack trace;
- *   - a session with no connection record (never `plan_connect`-ed, e.g. an
- *     operator session that never joined a plan) is a silent, expected
- *     no-op — `{"ok":false,"reason":"no_connection_record"}` — the plugin
- *     hook simply does not forward anything further in this case, exactly
- *     what "no-op when the session isn't plan-connected" means in practice;
- *   - on success, `{"ok":true,"count":<number|null>,"applied":<boolean>}`
- *     echoes the SUBMITTED `count`; `applied` is the server's answer to
- *     whether it was stored (DX-3676: `false` for an out-of-order report
- *     older than the one already on file — the caller must not treat it as
- *     the dashboard's current count);
- *   - DX-3676 — `<event-at>` is the ISO-8601 UTC time the reporting HOOK
- *     fired, captured by the caller, never this process's own clock: the
- *     hooks are async and can finish out of order, and the server orders
- *     reports by this time;
- *   - human-readable diagnostics go to stderr only, never stdout.
- *
- * THE CREDENTIAL — the SAME resolver `plan_events_wait` uses, via `resolveDashboardAuth`
- * (the relay): the dashboard URL, credential source, and credential come
- * from the connection record this session's OWN danx-dashboard MCP server
- * wrote on its last successful `plan_connect` (`session-connection.ts`),
- * never from this process's own ambient env (DX-2862).
- *
- * A HARD TIMEOUT — `BACKGROUND_WORK_REQUEST_TIMEOUT_MS`. A `Stop` hook
- * blocks the session's turn boundary, so this call must never hang: a slow
- * or wedged dashboard is `{ok:false, reason:"timeout"}`, not a stuck hook.
- *
- * THE REQUEST/RUN SCAFFOLDING (`one-shot-session-request.ts`, DX-3367
- * fix-up) is shared, general-purpose plumbing for any one-shot subcommand
- * shaped like this one — not maintained as an independent copy of the
- * authenticated-fetch-with-timeout logic or the session/credential
- * resolution boilerplate.
- */
-import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
-export const BACKGROUND_WORK_SUBCOMMAND = "background-work";
-export const BACKGROUND_WORK_PATH = "/api/plan-sessions/me/background-work";
-/** How long this one-shot call may take before it counts as a timeout. */
-export const BACKGROUND_WORK_REQUEST_TIMEOUT_MS = 5_000;
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BACKGROUND_WORK_SUBCOMMAND} <non-negative-integer|clear> <event-at ISO-8601 UTC>`;
-/**
- * Parse the ONE positional argument: `clear`, or a non-negative integer
- * string. Anything else is a usage error — never guessed or floored.
- */
-export function parseCountArg(raw) {
-    if (raw === "clear")
-        return null;
-    if (!/^\d+$/.test(raw))
-        return { error: `count must be "clear" or a non-negative integer, got "${raw}"` };
-    return Number.parseInt(raw, 10);
-}
-/** DX-3676 — an ISO-8601 UTC instant, as `Date#toISOString` writes it (the server accepts exactly this). */
-const ISO_UTC_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
-/** Parse the event-time argument (DX-3676). Never substituted with this process's clock. */
-export function parseEventAtArg(raw) {
-    if (!ISO_UTC_INSTANT.test(raw) || Number.isNaN(Date.parse(raw))) {
-        return { error: `event-at must be an ISO-8601 UTC timestamp (e.g. 2026-09-30T00:00:00.000Z), got "${raw}"` };
-    }
-    return raw;
-}
-/**
- * One authenticated PUT, with a hard timeout, classified into the output
- * shape this subcommand always prints — never a throw, never a non-2xx
- * bubbling past this function.
- *
- * DX-3367 fix-up — STATUS IS CHECKED BEFORE THE BODY IS EVER PARSED. A 5xx
- * (or any other non-2xx) response can carry an HTML error page instead of
- * JSON; parsing first would misreport that as `bad_response` when the true
- * classification is `http_error`. This subcommand has no status that needs
- * the BODY inspected to classify (no `409 session_not_connected`
- * equivalent), so status alone decides whether a body read is even
- * attempted.
- */
-export async function putBackgroundWork(options, report, deps) {
-    const sent = await sendSessionRequest(options, BACKGROUND_WORK_PATH, { method: "PUT", body: JSON.stringify({ count: report.count, eventAt: report.eventAt }) }, deps);
-    if ("reason" in sent)
-        return sent;
-    const { status, text } = sent;
-    if (status === 401 || status === 403) {
-        return { ok: false, reason: "unauthorized" };
-    }
-    if (status < 200 || status >= 300) {
-        return { ok: false, reason: "http_error" };
-    }
-    const parsed = tryParseJsonBody(text);
-    if (!parsed.ok)
-        return { ok: false, reason: "bad_response" };
-    const body = parsed.body;
-    if (typeof body !== "object" ||
-        body === null ||
-        !("count" in body) ||
-        (body.count !== null && typeof body.count !== "number") ||
-        typeof body.applied !== "boolean") {
-        return { ok: false, reason: "bad_response" };
-    }
-    const shaped = body;
-    return { ok: true, count: shaped.count, applied: shaped.applied };
-}
-/** The bin's `background-work` subcommand, wired to the real process. Always resolves to exit code 0. */
-export async function runBackgroundWorkCommand(argv, env = process.env, 
-/** Test seam: the home the session's connection record is read from. */
-resolveFrom = {}) {
-    const write = (output) => {
-        process.stdout.write(`${JSON.stringify(output)}\n`);
-    };
-    if (argv.length !== 2) {
-        write({ ok: false, reason: "usage" });
-        process.stderr.write(`${USAGE}\n`);
-        return 0;
-    }
-    const parsed = parseCountArg(argv[0]);
-    if (typeof parsed === "object" && parsed !== null && "error" in parsed) {
-        write({ ok: false, reason: "usage" });
-        process.stderr.write(`${parsed.error}\n${USAGE}\n`);
-        return 0;
-    }
-    const count = parsed;
-    const eventAt = parseEventAtArg(argv[1]);
-    if (typeof eventAt === "object") {
-        write({ ok: false, reason: "usage" });
-        process.stderr.write(`${eventAt.error}\n${USAGE}\n`);
-        return 0;
-    }
-    const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
-    if (!resolved.ok) {
-        // A session that never `plan_connect`-ed has no connection record — this
-        // is the ORDINARY "not plan-connected" case, not an error the plugin
-        // should surface: it simply forwards nothing further this turn.
-        write(resolved.output);
-        process.stderr.write(`${resolved.detail}\n`);
-        return 0;
-    }
-    const output = await putBackgroundWork(resolved.options, { count, eventAt }, {
-        fetch: (input, init) => fetch(input, init),
-        requestTimeoutMs: BACKGROUND_WORK_REQUEST_TIMEOUT_MS,
-    });
-    write(output);
-    return 0;
-}

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

@@ -1,105 +0,0 @@
-/**
- * DX-3367 fix-up — shared scaffolding for a "one-shot session request"
- * subcommand. Extracted when `plan-state` (`GET /api/plan-sessions/me/turn-state`,
- * removed by DX-3689 — it never had a caller) and `background-work`
- * (`PUT /api/plan-sessions/me/background-work`) turned out to duplicate this
- * exact shape independently (`fetchTurnState` / `putBackgroundWork`,
- * `runPlanStateCommand` / `runBackgroundWorkCommand`). This module is the ONE
- * place that shape lives now; a future one-shot subcommand extends it
- * instead of copying `background-work.ts` again.
- *
- * Two pieces:
- *   - `sendSessionRequest` — the authenticated HTTP call itself: bearer +
- *     session header, a hard abort-timeout, and network-level failure
- *     classification (`timeout` / `request_failed`). Returns the raw
- *     `{status, text}` UNPARSED — each caller decides for itself which
- *     statuses need the body inspected and which don't, so a non-2xx status
- *     with an unparseable (e.g. HTML) body is classified from the status
- *     alone rather than colliding with "the JSON didn't parse"
- *     (`bad_response`).
- *   - `resolveSessionOptions` — session-id + credential resolution via
- *     `resolveDashboardAuth`, with `SessionStartError` narrowed by
- *     `instanceof` rather than an unchecked `as SessionStartError` cast, so
- *     an error of some OTHER shape (a bug in the resolver, a thrown
- *     non-Error) still comes back as a reported reason instead of a value
- *     whose `.reason`/`.message`/`.fix` fields are silently `undefined`.
- */
-import { boundRequest } from "./request-bound.js";
-import { SESSION_ID_HEADER, resolveDashboardAuth, SessionStartError } from "./session-options.js";
-/**
- * One authenticated HTTP call to this session's dashboard, with a hard
- * timeout. Never throws — a network failure or an abort is reported as
- * `OneShotFailure`, 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 };
-    }
-}
-/**
- * Resolve this process's session id + dashboard credential, the identical
- * first step every one-shot subcommand's `runXCommand` takes before it can
- * make its own request. `detail` is the stderr-only human-readable line the
- * caller prints alongside `output` — never part of the stdout JSON contract.
- */
-export async function resolveSessionOptions(env, resolveFrom, usage) {
-    const sessionId = env.CLAUDE_CODE_SESSION_ID;
-    if (!sessionId) {
-        return { ok: false, output: { ok: false, reason: "no_session_id" }, detail: usage };
-    }
-    try {
-        const options = resolveDashboardAuth(sessionId, env, resolveFrom);
-        return { ok: true, options };
-    }
-    catch (err) {
-        // DX-3367 fix-up — `instanceof`, never an unchecked `as SessionStartError`
-        // cast: `resolveDashboardAuth` throws exactly `SessionStartError` today,
-        // but a cast reports a fabricated reason/message/fix (all `undefined`)
-        // for any OTHER thrown shape instead of a real one, silently.
-        if (err instanceof SessionStartError) {
-            return {
-                ok: false,
-                output: { ok: false, reason: err.reason },
-                detail: `${err.reason}: ${err.message}. Fix: ${err.fix}.`,
-            };
-        }
-        const message = err instanceof Error ? err.message : String(err);
-        return { ok: false, output: { ok: false, reason: "start_failed" }, detail: `start_failed: ${message}` };
-    }
-}

package/dist/ready-cards.js

@@ -1,176 +0,0 @@
-/**
- * `danx-dashboard-mcp ready-cards` — DX-4534. The ONE-SHOT client the claude-plugins `danxbot`
- * plugin's Stop hook runs for a plan-connected session, to learn which of its plan's cards
- * anyone could pick up right now.
- *
- * WHY IT EXISTS. An orchestrating plan session must keep every unblocked card moving, and
- * nothing enforced it: on 2026-10-04 one builder ran while two readied, unblocked cards sat
- * untouched, because the session only looked for work when a builder reported back. The Stop
- * hook turns that check into something the harness runs. This is its read.
- *
- * NO DASHBOARD ROUTE IS ADDED. It composes existing reads on the session's own credential:
- *   1. `GET /api/plans/mine` answers the session's plan (`id`) and the boards its cards live on
- *      (`boards`) in one read; a session on no plan is a 409 `session_not_connected`.
- *   2. `GET /api/issues?board=<b>` with `filter.plan_id` + `filter.status_derived=ToDo` and the
- *      judged fields, once per board: a plan can span boards (PLAN-11 spans danxbot and
- *      gpt-manager), and an issues read without `board` sees only the default one.
- * Server-side filtering narrows the read; `isReadyCard` is the whole definition of "ready".
- *
- * READY means a card a dispatcher or a session could claim this minute: a Story, Bug or Chore
- * (Epic and Feature are containers, a Task is a leaf nobody dispatches), derived status ToDo,
- * nobody holding it (no assigned agent, no live dispatch), and nothing in its way: no hold
- * (`blocked`), no open problem (a human is needed), no unmet `depends_on`, no active
- * `conflict_on`. A card whose reason it cannot run is recorded on it therefore stops counting,
- * which is how the hook's "dispatch it, or record why not" instruction is satisfiable.
- *
- * THE CONTRACT, which the hook reads by exit code:
- *   - exit 0, one JSON line on stdout: `{"plan_id": <n|null>, "cards": [{"id","title"}...]}`;
- *     `plan_id` null (the dashboard has the session on no plan) comes with an empty list.
- *   - exit 1, one reason on stderr, nothing on stdout: credential, network, non-2xx, bad shape.
- */
-import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
-export const READY_CARDS_SUBCOMMAND = "ready-cards";
-export const READY_CARDS_REQUEST_TIMEOUT_MS = 5_000;
-/** `GET /api/issues` page size (its maximum): a plan's ToDo cards never approach it. */
-const CARDS_PAGE_SIZE = 1000;
-/** The dispatchable card types: Epic and Feature are containers, a Task is a leaf nobody dispatches. */
-const DISPATCHABLE_TYPES = new Set(["Story", "Bug", "Chore"]);
-/**
- * The fields `isReadyCard` judges beyond the always-returned row, each with the check a row's value
- * must pass: the one list the request's `fields` tree and the row parse both come from.
- */
-const JUDGED_FIELDS = {
-    dispatch: (v) => v !== undefined,
-    blocked: (v) => v !== undefined,
-    open_problem_count: (v) => typeof v === "number",
-    waiting_on: (v) => typeof v === "boolean",
-    conflict_on_active_count: (v) => typeof v === "number",
-};
-const CARD_FIELDS = Object.fromEntries(Object.keys(JUDGED_FIELDS).map((name) => [name, true]));
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${READY_CARDS_SUBCOMMAND}`;
-/** The row, or null when any field `isReadyCard` judges is missing or the wrong type: a card never counts on a guess. */
-function parseCardRow(raw) {
-    if (typeof raw !== "object" || raw === null)
-        return null;
-    const r = raw;
-    const assigned = r.assigned_agent;
-    if (typeof r.id !== "string" || typeof r.type !== "string" || typeof r.title !== "string")
-        return null;
-    if (!(assigned === null || typeof assigned === "string"))
-        return null;
-    if (!Object.entries(JUDGED_FIELDS).every(([name, valid]) => valid(r[name])))
-        return null;
-    return r;
-}
-/** Whether a ToDo card could be claimed right now (see the module banner). */
-export function isReadyCard(card) {
-    return (DISPATCHABLE_TYPES.has(card.type) &&
-        card.assigned_agent === null &&
-        card.dispatch === null &&
-        card.blocked === null &&
-        card.open_problem_count === 0 &&
-        !card.waiting_on &&
-        card.conflict_on_active_count === 0);
-}
-function classifyStatus(status) {
-    if (status === 401 || status === 403)
-        return "unauthorized";
-    if (status === 404)
-        return "not_found";
-    if (status < 200 || status >= 300)
-        return "http_error";
-    return null;
-}
-/** The session's plan and its boards, `null` when the dashboard has the session on no plan, or a failure. */
-async function readSessionPlan(options, deps) {
-    const sent = await sendSessionRequest(options, "/api/plans/mine", { method: "GET" }, deps);
-    if ("ok" in sent)
-        return sent;
-    const parsed = tryParseJsonBody(sent.text);
-    const body = parsed.ok ? parsed.body : null;
-    // A session on no plan is the ordinary answer, not a fault: a 409 `session_not_connected`.
-    if (sent.status === 409 && body?.error === "session_not_connected")
-        return { ok: true, plan: null };
-    const failed = classifyStatus(sent.status);
-    if (failed !== null)
-        return { ok: false, reason: failed };
-    if (body === null ||
-        typeof body.id !== "number" ||
-        !Array.isArray(body.boards) ||
-        !body.boards.every((b) => typeof b === "string")) {
-        return { ok: false, reason: "bad_response" };
-    }
-    return { ok: true, plan: { planId: body.id, boards: body.boards } };
-}
-/** The plan's ready cards on one board. */
-async function readBoardReadyCards(options, deps, planId, board) {
-    const filter = encodeURIComponent(JSON.stringify({ plan_id: planId, status_derived: "ToDo" }));
-    const fields = encodeURIComponent(JSON.stringify(CARD_FIELDS));
-    const sent = await sendSessionRequest(options, `/api/issues?board=${encodeURIComponent(board)}&filter=${filter}&fields=${fields}&limit=${CARDS_PAGE_SIZE}&sort=priority`, { method: "GET" }, deps);
-    if ("ok" in sent)
-        return sent;
-    const failed = classifyStatus(sent.status);
-    if (failed !== null)
-        return { ok: false, reason: failed };
-    const parsed = tryParseJsonBody(sent.text);
-    const body = parsed.ok ? parsed.body : null;
-    if (body === null || !Array.isArray(body.issues) || typeof body.total !== "number")
-        return { ok: false, reason: "bad_response" };
-    // A truncated read would silently miss ready cards: fail loudly instead.
-    if (body.total > body.issues.length)
-        return { ok: false, reason: "too_many_cards" };
-    const cards = [];
-    for (const raw of body.issues) {
-        const row = parseCardRow(raw);
-        if (row === null)
-            return { ok: false, reason: "bad_response" };
-        if (isReadyCard(row))
-            cards.push({ id: row.id, title: row.title });
-    }
-    return { ok: true, cards };
-}
-/** One authenticated read of the session's plan's ready cards, across every board the plan spans. Never throws. */
-export async function fetchReadyCards(options, deps) {
-    const read = await readSessionPlan(options, deps);
-    if (!read.ok)
-        return read;
-    if (read.plan === null)
-        return { ok: true, planId: null, cards: [] };
-    const { planId } = read.plan;
-    const perBoard = await Promise.all(read.plan.boards.map((board) => readBoardReadyCards(options, deps, planId, board)));
-    const cards = [];
-    for (const onBoard of perBoard) {
-        if (!onBoard.ok)
-            return onBoard;
-        cards.push(...onBoard.cards);
-    }
-    return { ok: true, planId: read.plan.planId, cards };
-}
-/** The bin's `ready-cards` subcommand, wired to the real process. */
-export async function runReadyCardsCommand(argv, env = process.env, 
-/** Test seams: the home the connection record is read from, and the HTTP client. */
-seams = {}) {
-    if (argv.length !== 0) {
-        process.stderr.write(`unexpected arguments\n${USAGE}\n`);
-        return 1;
-    }
-    // `resolveSessionOptions` words a missing session id as the usage text alone; every stderr line here starts with its reason.
-    if (!env.CLAUDE_CODE_SESSION_ID) {
-        process.stderr.write(`no_session_id: CLAUDE_CODE_SESSION_ID is not set\n${USAGE}\n`);
-        return 1;
-    }
-    const resolved = await resolveSessionOptions(env, { home: seams.home }, USAGE);
-    if (!resolved.ok) {
-        // `detail` names its reason except for a missing session id, where it is only the usage text.
-        const named = resolved.detail.startsWith(`${resolved.output.reason}:`);
-        process.stderr.write(named ? `${resolved.detail}\n` : `${resolved.output.reason}: CLAUDE_CODE_SESSION_ID is not set\n${resolved.detail}\n`);
-        return 1;
-    }
-    const output = await fetchReadyCards(resolved.options, seams.deps ?? { fetch: (input, init) => fetch(input, init), requestTimeoutMs: READY_CARDS_REQUEST_TIMEOUT_MS });
-    if (!output.ok) {
-        process.stderr.write(`${output.reason}: could not read the plan's ready cards from the dashboard\n`);
-        return 1;
-    }
-    process.stdout.write(`${JSON.stringify({ plan_id: output.planId, cards: output.cards })}\n`);
-    return 0;
-}