@thehammer/danx-dashboard-mcp 0.1.274 → 0.1.276

package/README.md

@@ -78,11 +78,17 @@ 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`, `event-text`, `ready-cards`, `restart-notice`) 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).
+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)
+## `restart_notice` — what a restarted session was working on (DX-3928, DX-4632)
 
-Run by the danxbot plugin's SessionStart hook for a session that is **not** plan-connected. A restarted Claude Code session gets a new session id and no plan binding, so nothing told 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); this subcommand finds the newest OTHER session's record for the same project within `STALE_RECORD_MS`, resolves that 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). Exit 0 with text on stdout = say it (the registry's `plan_restart.waiting_events` text — this package carries no wording); exit 0 with nothing = nothing to say (never connected from this project, plan archived or deleted, record stale); exit 1 = the lookup failed. A record from an older server (schema v1) is skipped here and refused, with the fix, everywhere a session reads its OWN record.
+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:
+
+- `{notice: "<text>"}`: say it (the registry's `plan_restart.waiting_events` text; this package carries no wording).
+- `{notice: null}`: nothing to say (no earlier session of this project connected a plan, the plan is archived or deleted, the record is stale, or every predecessor is still live).
+- `{stopped: {reason, detail, fix}}`: the lookup could not answer: `no_session_id`, `lookup_failed` (no candidate answered; the detail names each reason) or `lookup_timeout`. Never a silent null.
+
+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)
 

package/dist/index.js

@@ -86,11 +86,10 @@ import { PlanEventRelay, WAIT_MAX_MS, WAIT_MIN_MS } from "./plan-events-relay.js
 import { READ_IDLE_TIMEOUT_MS } from "./listen.js";
 import { REQUEST_TIMEOUT_MS, realScheduleInterval, realSleep } from "./session-stream.js";
 import { servePlanEventsWait } from "./plan-events-tool.js";
+import { lookupRestartNotice } 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 { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
-import { RESTART_NOTICE_SUBCOMMAND, runRestartNoticeCommand } from "./restart-notice.js";
 import { READY_CARDS_SUBCOMMAND, runReadyCardsCommand } from "./ready-cards.js";
 import { SUBAGENTS_LIVE_SUBCOMMAND, runSubagentsLiveCommand } from "./subagents-live.js";
 import { resolveBootCredential } from "./credential.js";
@@ -785,6 +784,17 @@ strictTool("plan_events_wait",
 // The relay is bound to the session the server booted for (the id every other tool on this server also sends); a server
 // with none holds no session key, so the surface never shows this tool and the relay would answer `credential_unavailable`.
 async (args, extra) => jsonResult(await servePlanEventsWait(planEventRelay, args, extra.signal)));
+// ---------------- restart_notice (DX-4632) ----------------
+strictTool("restart_notice", 
+// DX-4632 - for the danxbot plugin's session-start hook, not for a model to call. General-audience text (DX-4550).
+"Which plan the session this one replaced was working, and what waits there. For the danxbot plugin's session start: " +
+    "a model never calls it. Works before sign-in. Answers `{notice: text}` (tell the session), `{notice: null}` (nothing " +
+    "to say) or `{stopped: {reason, detail, fix}}`.", {}, async () => jsonResult(await lookupRestartNotice({
+    sessionId: config.session?.id,
+    cwd: process.cwd(),
+    env: process.env,
+    fetch: (input, init) => fetch(input, init),
+})));
 // ---------------- main ----------------
 async function main() {
     boot();
@@ -808,7 +818,7 @@ 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, event-text, ready-cards, restart-notice, subagents-live)
+// 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
@@ -834,26 +844,8 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(0);
         });
     }
-    else if (subcommand === EVENT_TEXT_SUBCOMMAND) {
-        // DX-3421 (was DX-3366's `mantra` subcommand) — unlike background-work, a
-        // rejection here is a genuine fatal (never expected: runEventTextCommand
-        // itself already classifies every network/shape failure into its own
-        // {ok:false} exit 1), so it exits 1 too rather than the "always 0, stay
-        // silent" contract background-work's hook-only subcommand uses.
-        runEventTextCommand(rest).then((code) => process.exit(code), (err) => {
-            console.error(`[danx-dashboard-mcp] event-text fatal: ${err.message}`);
-            process.exit(1);
-        });
-    }
-    else if (subcommand === RESTART_NOTICE_SUBCOMMAND) {
-        // DX-3928 — same exit-code contract as event-text: 0 (text, or nothing to say) / 1 (lookup failed).
-        runRestartNoticeCommand(rest).then((code) => process.exit(code), (err) => {
-            console.error(`[danx-dashboard-mcp] restart-notice fatal: ${err.message}`);
-            process.exit(1);
-        });
-    }
     else if (subcommand === READY_CARDS_SUBCOMMAND) {
-        // DX-4534 — the plugin Stop hook's read; the event-text exit-code contract: 0 (one JSON line) / 1 (read failed).
+        // 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);
@@ -869,8 +861,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}", "${EVENT_TEXT_SUBCOMMAND}", ` +
-            `"${RESTART_NOTICE_SUBCOMMAND}", "${READY_CARDS_SUBCOMMAND}", and "${SUBAGENTS_LIVE_SUBCOMMAND}")`);
+            `"${BACKGROUND_WORK_SUBCOMMAND}", "${ACTIVITY_SUBCOMMAND}", ` +
+            `"${READY_CARDS_SUBCOMMAND}", and "${SUBAGENTS_LIVE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/listen.js

@@ -181,6 +181,13 @@ export function invalidEventReason(value) {
         }
         case "blocked":
             return isCappedText(d.reason) ? null : "detail.reason is not capped text";
+        // DX-4622: a reviewer asked for changes on the card's pull request (GitHub review webhook).
+        case "pull_request_changes_requested":
+            if (typeof d.reviewer !== "string")
+                return "detail.reviewer is not a string";
+            if (typeof d.review_url !== "string")
+                return "detail.review_url is not a string";
+            return isCappedText(d.excerpt) ? null : "detail.excerpt is not capped text";
         default:
             return null;
     }
@@ -256,6 +263,9 @@ function describe(event) {
             return `${who} blocked the card: ${quoted(d.reason)}`;
         case "unblocked":
             return `${who} unblocked the card`;
+        // DX-4622: the agent must act on the review, so the line names who, where, and what to do next.
+        case "pull_request_changes_requested":
+            return `${who}: ${d.reviewer} requested changes on the pull request (${d.review_url})${d.excerpt.text === "" ? "" : `: ${quoted(d.excerpt)}`}. Address the review, push, and reply on the pull request`;
         default:
             // A kind newer than this listener still produces a line: an event the
             // agent is never told about is exactly the failure this reader prevents.

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

@@ -24,6 +24,7 @@
  *     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
@@ -32,8 +33,7 @@ import { SESSION_ID_HEADER, resolveDashboardAuth, SessionStartError } from "./se
  * might produce from the status/body it gets back on success.
  */
 export async function sendSessionRequest(options, path, init, deps) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
+    const bound = boundRequest(deps.requestTimeoutMs, deps.signal);
     try {
         try {
             const response = await deps.fetch(`${options.dashboardUrl}${path}`, {
@@ -45,7 +45,7 @@ export async function sendSessionRequest(options, path, init, deps) {
                     [SESSION_ID_HEADER]: options.sessionId,
                 },
                 body: init.body,
-                signal: controller.signal,
+                signal: bound.signal,
             });
             const text = await response.text();
             return { status: response.status, text };
@@ -54,11 +54,11 @@ export async function sendSessionRequest(options, path, init, deps) {
             // 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: controller.signal.aborted ? "timeout" : "request_failed" };
+            return { ok: false, reason: bound.aborted() ? "timeout" : "request_failed" };
         }
     }
     finally {
-        clearTimeout(timer);
+        bound.release();
     }
 }
 /** `JSON.parse`, classified rather than thrown — the ONE shared parse point

package/dist/request-bound.js

@@ -0,0 +1,22 @@
+/**
+ * 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
+ * heartbeat), so the controller, the timer, the link to the outer signal and the cleanup exist once.
+ */
+export function boundRequest(timeoutMs, outer) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const timer = setTimeout(abort, timeoutMs);
+    if (outer?.aborted === true)
+        abort();
+    outer?.addEventListener("abort", abort, { once: true });
+    return {
+        signal: controller.signal,
+        aborted: () => controller.signal.aborted,
+        release: () => {
+            clearTimeout(timer);
+            outer?.removeEventListener("abort", abort);
+        },
+    };
+}

package/dist/restart-notice.js

@@ -1,83 +1,61 @@
 /**
- * `danx-dashboard-mcp restart-notice` — DX-3928. The ONE-SHOT client the
- * claude-plugins `danxbot` plugin's SessionStart hook runs for a session that is
- * NOT plan-connected, to tell it when the previous session of the same project
- * was working a plan.
+ * The `restart_notice` tool - DX-3928, DX-4632. How a RESTARTED Claude Code session learns which plan the session it replaced was
+ * working, so it can say so to its agent and reconnect.
  *
- * WHY IT EXISTS. A restarted Claude Code session gets a NEW session id and no
- * plan binding, and nothing told it (or the operator) that the plan it had been
- * working was unattended: six operator answers sat unread for an hour on
- * 2026-10-01. The session's own connection record cannot help (it is the new
- * session's, and does not exist yet); the PREVIOUS session's record can, found by
- * the project key `plan_connect` wrote into it (`findPredecessorCandidates`).
+ * WHY IT EXISTS. A restarted session gets a NEW session id, no plan binding and, until a person approves its first call, no
+ * dashboard key of its own: its MCP server boots signed out. Nothing told it (or the operator) that the plan it had been
+ * 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
+ * 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`).
  *
- * THE CONTRACT, which `event-hook.sh` reads by exit code:
- *   - exit 0, text on stdout: say this to the agent (the registry's
- *     `plan_restart.waiting_events` text — this module carries no wording).
- *   - exit 0, nothing on stdout: nothing to say — no earlier session of this
- *     project connected a plan, or the plan is archived/deleted, or the record is
- *     stale. The plugin stays silent, as PLN-11 R-10 requires of a project that
- *     never connected a plan.
- *   - exit 1, reasons on stderr: NO candidate answered (credential, network,
- *     non-2xx, bad shape, for every one). Never silent: the hook prints a could-not-load notice.
+ * THE ANSWER (the plugin's hooks module reads it through `$.mcp.call`):
+ *   - `{notice: "<text>"}` - say this to the agent (the registry's `plan_restart.waiting_events` text; this module carries no
+ *     wording of its own).
+ *   - `{notice: null}` - nothing to say: no earlier session of this project connected a plan, or the plan is archived or
+ *     deleted, or the record is stale, or every predecessor is still live. The plugin stays silent, as PLN-11 R-10 requires of
+ *     a project that never connected a plan.
+ *   - `{stopped: {reason, detail, fix}}` - the lookup could not answer: no session id, NO candidate answered (credential,
+ *     network, non-2xx, bad shape, for every one), or the one deadline passed. Never a silent null. (A failure that is not
+ *     one of these, a bug in the credential resolver, is rethrown: fail loud, never dressed as a lookup failure.)
  *
- * The credential is the PREDECESSOR's own record's source, resolved through the
- * same resolver the relay uses, so the lookup reaches the dashboard that
- * connected it. READ-ONLY: it advances no cursor on the server.
+ * ONE DEADLINE over the whole lookup (`RESTART_NOTICE_DEADLINE_MS`): every candidate's request shares it (and each keeps its own
+ * shorter bound), so a hung dashboard cannot wedge a session start however many candidates there are. READ-ONLY: it advances
+ * no cursor on the server.
  */
-import { SESSION_ID_HEADER, resolveDashboardAuth } from "./session-options.js";
+import { sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
+import { resolveDashboardAuth, SessionStartError } from "./session-options.js";
 import { findPredecessorCandidates, projectKeyOf } from "./session-connection.js";
-export const RESTART_NOTICE_SUBCOMMAND = "restart-notice";
+import { fixForStop } from "./stop-fixes.js";
 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;
 /**
- * How many earlier sessions of the project one run asks about, newest first. Many
+ * How many earlier sessions of the project one lookup asks about, newest first. Many
  * sessions share one checkout and the dashboard answers "nothing" for a LIVE sibling
  * (it is not a predecessor), so the newest candidate is often not the one.
  */
 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";
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${RESTART_NOTICE_SUBCOMMAND} [--cwd <project directory>]`;
-/** One authenticated GET with a hard timeout, answering the notice text or `null`. */
+/** One authenticated GET (the shared one-shot request, so its bound and its failure names are the same), answering the notice text or `null`. */
 export async function fetchRestartNotice(target, deps) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
-    let status;
-    let text;
-    try {
-        try {
-            const response = await deps.fetch(`${target.dashboardUrl}/api/plan-sessions/${encodeURIComponent(target.predecessorId)}/restart-notice`, {
-                method: "GET",
-                headers: {
-                    Authorization: `Bearer ${target.token}`,
-                    Accept: "application/json",
-                    [SESSION_ID_HEADER]: target.askingSessionId,
-                },
-                signal: controller.signal,
-            });
-            status = response.status;
-            text = await response.text();
-        }
-        catch {
-            return { ok: false, reason: controller.signal.aborted ? "timeout" : "request_failed" };
-        }
-    }
-    finally {
-        clearTimeout(timer);
-    }
+    // 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 };
+    const sent = await sendSessionRequest(auth, `/api/plan-sessions/${encodeURIComponent(target.predecessorId)}/restart-notice`, { method: "GET" }, deps);
+    if ("ok" in sent)
+        return { ok: false, reason: sent.reason };
+    const { status, text } = sent;
     if (status === 401 || status === 403)
         return { ok: false, reason: "unauthorized" };
     if (status === 404)
         return { ok: false, reason: "not_found" };
     if (status < 200 || status >= 300)
         return { ok: false, reason: "http_error" };
-    let body;
-    try {
-        body = JSON.parse(text);
-    }
-    catch {
-        return { ok: false, reason: "bad_response" };
-    }
+    const parsed = tryParseJsonBody(text);
+    const body = parsed.ok ? parsed.body : null;
     if (typeof body !== "object" || body === null || !("restart" in body))
         return { ok: false, reason: "bad_response" };
     if (body.restart === null)
@@ -90,61 +68,63 @@ export async function fetchRestartNotice(target, deps) {
         return { ok: false, reason: "bad_response" };
     return { ok: true, text: notice.text };
 }
-function parseCwd(argv) {
-    if (argv.length === 0)
-        return process.cwd();
-    if (argv.length === 2 && argv[0] === "--cwd" && argv[1] !== "")
-        return argv[1];
-    return "invalid";
-}
-/** The bin's `restart-notice` subcommand, wired to the real process. */
-export async function runRestartNoticeCommand(argv, env = process.env, 
-/** Test seam: the home the connection records are read from. */
-resolveFrom = {}) {
-    const cwd = parseCwd(argv);
-    if (cwd === "invalid") {
-        process.stderr.write(`bad arguments\n${USAGE}\n`);
-        return 1;
-    }
-    const sessionId = env.CLAUDE_CODE_SESSION_ID;
-    if (!sessionId) {
-        process.stderr.write(`no_session_id: CLAUDE_CODE_SESSION_ID is not set\n${USAGE}\n`);
-        return 1;
+const stop = (reason, detail) => ({ stopped: { reason, detail, fix: fixForStop(reason) } });
+/** The tool's whole body: see the module docblock for the contract. Throws only on a bug, never on a lookup failure. */
+export async function lookupRestartNotice(lookup) {
+    if (lookup.sessionId === undefined || lookup.sessionId === "") {
+        return stop("no_session_id", "this server has no CLAUDE_CODE_SESSION_ID, so it cannot tell which session it replaced");
     }
-    const candidates = findPredecessorCandidates(projectKeyOf(cwd), sessionId, resolveFrom).slice(0, RESTART_NOTICE_MAX_CANDIDATES);
-    // One candidate failing (its credential moved, its dashboard is down) must not hide a LATER candidate that
-    // would answer: keep going, and report failure only when no candidate answered at all.
-    const failures = [];
-    let answered = 0;
-    for (const predecessor of candidates) {
-        let options;
-        try {
-            options = resolveDashboardAuth(predecessor.sessionId, env, resolveFrom);
-        }
-        catch (err) {
-            const start = err;
-            failures.push(`${start.reason}: ${start.message}. Fix: ${start.fix}.`);
-            continue;
+    const resolveFrom = { home: lookup.home, now: lookup.now };
+    const candidates = findPredecessorCandidates(projectKeyOf(lookup.cwd), lookup.sessionId, resolveFrom).slice(0, RESTART_NOTICE_MAX_CANDIDATES);
+    // DX-4632: ONE deadline for every candidate read. It is not unref'd: the lookup is awaited, and a pending request holds the
+    // process anyway.
+    const deadline = new AbortController();
+    const deadlineMs = lookup.deadlineMs ?? RESTART_NOTICE_DEADLINE_MS;
+    const timer = setTimeout(() => deadline.abort(), deadlineMs);
+    try {
+        // One candidate failing (its credential moved, its dashboard is down) must not hide a LATER candidate that
+        // would answer: keep going, and report failure only when no candidate answered at all.
+        const failures = [];
+        let answered = 0;
+        for (const predecessor of candidates) {
+            let options;
+            try {
+                options = resolveDashboardAuth(predecessor.sessionId, lookup.env, resolveFrom);
+            }
+            catch (err) {
+                if (!(err instanceof SessionStartError))
+                    throw err; // a bug in the resolver is not a lookup failure: fail loud
+                failures.push(`${err.reason}: ${err.message}. Fix: ${err.fix}.`);
+                continue;
+            }
+            const output = await fetchRestartNotice({
+                dashboardUrl: options.dashboardUrl,
+                token: options.token,
+                predecessorId: predecessor.sessionId,
+                askingSessionId: lookup.sessionId,
+            }, { fetch: lookup.fetch, requestTimeoutMs: lookup.requestTimeoutMs ?? RESTART_NOTICE_REQUEST_TIMEOUT_MS, signal: deadline.signal });
+            // A notice the dashboard fully answered is kept even when the deadline fired right after it; every other outcome of a
+            // deadline that passed is the stop below (this is the lookup's one deadline check).
+            if (output.ok && output.text !== null)
+                return { notice: output.text };
+            if (deadline.signal.aborted)
+                break;
+            if (!output.ok) {
+                failures.push(`${output.reason}: could not ask the dashboard what session ${predecessor.sessionId} was working`);
+                continue;
+            }
+            answered += 1;
         }
-        const output = await fetchRestartNotice({
-            dashboardUrl: options.dashboardUrl,
-            token: options.token,
-            predecessorId: predecessor.sessionId,
-            askingSessionId: sessionId,
-        }, { fetch: (input, init) => fetch(input, init), requestTimeoutMs: RESTART_NOTICE_REQUEST_TIMEOUT_MS });
-        if (!output.ok) {
-            failures.push(`${output.reason}: could not ask the dashboard what session ${predecessor.sessionId} was working`);
-            continue;
+        // DX-4632: a deadline that passed is a stop even when earlier candidates answered "nothing": an unasked candidate may be the one.
+        if (deadline.signal.aborted) {
+            return stop("lookup_timeout", `the lookup did not finish within ${deadlineMs} ms (${failures.length} of ${candidates.length} candidates had failed)`);
         }
-        answered += 1;
-        if (output.text !== null) {
-            process.stdout.write(output.text);
-            return 0;
+        if (answered === 0 && failures.length > 0) {
+            return stop("lookup_failed", `no candidate answered (${failures.length} of ${candidates.length} failed): ${failures.join(" | ")}`);
         }
+        return { notice: null };
     }
-    if (answered === 0 && failures.length > 0) {
-        process.stderr.write(`no candidate answered (${failures.length} of ${candidates.length} failed):\n${failures.join("\n")}\n`);
-        return 1;
+    finally {
+        clearTimeout(timer);
     }
-    return 0;
 }

package/dist/session-connection.js

@@ -2,8 +2,8 @@
  * DX-2862 — the record that hands ONE Claude Code session's dashboard
  * connection from its MCP server to the plugin's hook subcommands.
  *
- * THE PROBLEM THIS SOLVES. A hook's subcommand (`activity`, `background-work`, `event-text`,
- * `ready-cards`, `restart-notice`) runs in the SESSION's environment, not in the MCP server's, which is the only
+ * 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
  * 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
@@ -157,7 +157,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, ready-cards and restart-notice reports will not reach the dashboard",
+                "the plugin's activity, background-work and ready-cards reports will not reach the dashboard",
         };
     }
     try {
@@ -173,7 +173,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, ready-cards and restart-notice reports will not reach the dashboard until it succeeds",
+                "the plugin's activity, background-work and ready-cards reports will not reach the dashboard until it succeeds",
         };
     }
 }

package/dist/session-options.js

@@ -1,6 +1,6 @@
 /**
- * DX-2862 / DX-4233 - how a one-shot client of the dashboard (`activity`, `background-work`, `event-text`, `ready-cards`,
- * `restart-notice`) learns WHICH dashboard to call and AS WHOM: the connection record this session's own MCP server wrote when
+ * 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.)

package/dist/session-stream.js

@@ -7,6 +7,7 @@
  * what a stop means for the session) belongs to the relay.
  */
 import { errorCodeOf } from "./json-body.js";
+import { boundRequest } from "./request-bound.js";
 import { keyRevocationOf, keyRevokedHalt } from "./key-revoked-halt.js";
 import { oneLine } from "./one-line.js";
 import { SESSION_ID_HEADER } from "./session-options.js";
@@ -64,12 +65,7 @@ const TRANSIENT_CLIENT_STATUSES = new Set([408, 429]);
  * failures are worth retrying.
  */
 async function request(options, deps, what, url, init = { method: "GET" }) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
-    const abort = () => controller.abort();
-    if (deps.signal?.aborted === true)
-        abort();
-    deps.signal?.addEventListener("abort", abort, { once: true });
+    const bound = boundRequest(deps.requestTimeoutMs, deps.signal);
     try {
         let status;
         let text;
@@ -85,7 +81,7 @@ async function request(options, deps, what, url, init = { method: "GET" }) {
                 method: init.method,
                 headers,
                 body: init.body,
-                signal: controller.signal,
+                signal: bound.signal,
             });
             status = response.status;
             text = await response.text();
@@ -93,7 +89,7 @@ async function request(options, deps, what, url, init = { method: "GET" }) {
         catch (err) {
             return {
                 kind: "transient",
-                detail: controller.signal.aborted
+                detail: bound.aborted()
                     ? `${what} timed out after ${deps.requestTimeoutMs} ms`
                     : `${what} failed: ${err.message}`,
             };
@@ -111,8 +107,7 @@ async function request(options, deps, what, url, init = { method: "GET" }) {
         return { kind: "answer", status, text, body };
     }
     finally {
-        clearTimeout(timer);
-        deps.signal?.removeEventListener("abort", abort);
+        bound.release();
     }
 }
 /** What is wrong with a 2xx mint body, or `null` when it is a ticket. Never echoes the body. */

package/dist/stop-fixes.js

@@ -12,6 +12,8 @@
  * DX-4233 - the texts name the session's listener, never a process: with the relay inside the session's own MCP server there
  * is no separate process to restart.
  */
+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 " +
         "(a server older than the one that introduced the record writes none)",
@@ -32,6 +34,10 @@ export const STOP_FIXES = {
     refused: "call plan_connect again to mint a new listener ticket for this session",
     // DX-3028 - this session id belongs to a worker dispatch; there is no listener ticket a worker session can ever use.
     session_is_worker: "this session id belongs to a worker dispatch; start a new session",
+    // DX-4632: `restart_notice` only tells a restarted session which plan its predecessor was on; none of its stops blocks anything.
+    no_session_id: `${RESTART_NOTICE_STOP_LEAD}: this server was started without a session id, so it cannot tell which session it replaced; ${RESTART_NOTICE_STOP_TAIL}`,
+    lookup_timeout: `${RESTART_NOTICE_STOP_LEAD}: the dashboard did not answer in time; ${RESTART_NOTICE_STOP_TAIL}`,
+    lookup_failed: `${RESTART_NOTICE_STOP_LEAD}: no earlier session's record could be checked (the detail says why); ${RESTART_NOTICE_STOP_TAIL}`,
     relay_failed: "the event relay inside this session's danx-dashboard MCP server failed (the detail says why); the next call tries again, and if it keeps failing restart this Claude Code session",
 };
 export const DEFAULT_STOP_FIX = "call plan_connect again in this session to restart the listener";

package/dist/tool-access.js

@@ -27,6 +27,8 @@ export const CALLBACK_ENV = {
 };
 const BOOTSTRAP = { permission: null, callback: null };
 const needs = (permission) => ({ permission, callback: null });
+/** DX-4632: usable with no key (a session that has not signed in yet) and only on a person's session. */
+const OPERATOR_SESSION_BOOTSTRAP = { permission: null, callback: null, operatorSessionOnly: true };
 const operatorSessionNeeds = (permission) => ({ permission, callback: null, operatorSessionOnly: true });
 const needsAndPostsTo = (permission, callback) => ({ permission, callback });
 /**
@@ -44,6 +46,10 @@ export const TOOL_ACCESS = {
     // DX-4233 - the plugin's relay waits on the session's plan events here: it opens the listener ticket
     // (`POST /api/plan-sessions/me/stream-ticket`) and heartbeats (`.../me/heartbeat`), both `plans.view`.
     plan_events_wait: operatorSessionNeeds("plans.view"),
+    // DX-4632 - the plugin's session-start hook asks which plan the session this one replaced was working. A restarted session boots
+    // signed out, so it holds no permission: like `plan_connect` it is a bootstrap tool, and (like `plan_events_wait`) a person's
+    // session's only. The lookup asks the dashboard as the predecessor, with the credential the predecessor's record names.
+    restart_notice: OPERATOR_SESSION_BOOTSTRAP,
     // The one dispatch callback that stays a tool (DX-4525): it reads local files. Its dashboard route's own policy names the
     // permission (`route-policies/index.ts`); every other callback is a `danxbot_api` call to a route under `callback-routes.ts`.
     danxbot_slack_reply: needsAndPostsTo("slack.threads.post", "slackReply"),
@@ -62,7 +68,10 @@ export function isUsable(access, grant) {
 export function toolsFor(grant) {
     return Object.keys(TOOL_ACCESS).filter((name) => isUsable(TOOL_ACCESS[name], grant)).sort();
 }
-/** The bootstrap set: usable with no key and no callback. */
+/**
+ * The bootstrap set a DISPATCH sees: usable with no key, no callback, and not operator-session-only. A signed-out PERSON's
+ * session is shown this plus the operator-only bootstrap tools (`restart_notice`): see `bootstrapSurfaceTools()`.
+ */
 export function bootstrapTools() {
     return toolsFor({ permissions: new Set(), callbacks: new Set(), operatorSession: false });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.274",
+  "version": "0.1.276",
   "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/event-text.js

@@ -1,136 +0,0 @@
-/**
- * `danx-dashboard-mcp event-text <event>` — the ONE-SHOT client of
- * `GET /api/reminders/event/<event>` (DX-3421).
- *
- * WHO RUNS IT. The claude-plugins `danxbot` plugin's single event hook
- * (`event-hook.sh`, SessionStart matcher "startup|resume|compact" plus
- * SubagentStart matcher ".*") — replaces the old `mantra` subcommand's ONE
- * consumer, `mantra.sh` (deleted, DX-3421, along with
- * `plan-workflow-autoload.sh` and `compaction-skill-reload.sh`; all three
- * collapse into the one hook + this one subcommand). `<event>` is one of
- * `session_start` | `session_resume` | `after_compaction` |
- * `sub_agent_start` — the SAME `npx -y @thehammer/danx-dashboard-mcp@<pin>`
- * path the plugin's other one-shot subcommands (`activity`, `background-work`, `ready-cards`, `restart-notice`) already use — never a
- * separate install, never a deep import of this package's `dist/` internals.
- *
- * THE CREDENTIAL — the SAME resolver the other one-shot subcommands use
- * (`resolveDashboardAuth`, `session-options.ts`): the dashboard URL, credential source
- * and credential all 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. This
- * is only ever called once a session is already connected (`event-hook.sh`
- * checks that first via `plan-connection.mjs` and stays completely silent
- * otherwise — DX-3421 comment 7748/7752 verdict: no output at all before a
- * plan is connected), so a connection record always exists by the time this
- * runs.
- *
- * THE CONTRACT — `event-hook.sh` needs to tell success from failure so it
- * can print the operator-facing "could not load" notice (DX-3421 AC: no
- * committed offline fallback exists any more — a fetch failure is ALWAYS
- * reported to the agent, never silently swallowed and never a `mantra.md`
- * reread). So:
- *
- *   - success: the event's EFFECTIVE text on stdout, nothing else, exit 0.
- *   - failure (missing env, no connection record, network error, timeout,
- *     non-2xx, 404, bad shape): NOTHING on stdout, one short reason on
- *     stderr, exit 1. `event-hook.sh` is the one that decides what to print
- *     for the agent — this module only reports whether the fetch worked.
- *
- * A HARD TIMEOUT — a SessionStart hook must never hang on a wedged
- * dashboard.
- */
-import { SESSION_ID_HEADER, resolveDashboardAuth } from "./session-options.js";
-export const EVENT_TEXT_SUBCOMMAND = "event-text";
-export const EVENT_TEXT_REQUEST_TIMEOUT_MS = 5_000;
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${EVENT_TEXT_SUBCOMMAND} <event>`;
-function eventPath(event) {
-    return `/api/reminders/event/${encodeURIComponent(event)}`;
-}
-/** One authenticated GET, with a hard timeout — never throws, never bubbles a non-2xx. */
-export async function fetchEventText(event, options, deps) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs);
-    let status;
-    let text;
-    try {
-        try {
-            const response = await deps.fetch(`${options.dashboardUrl}${eventPath(event)}`, {
-                method: "GET",
-                headers: {
-                    Authorization: `Bearer ${options.token}`,
-                    Accept: "application/json",
-                    [SESSION_ID_HEADER]: options.sessionId,
-                },
-                signal: controller.signal,
-            });
-            status = response.status;
-            text = await response.text();
-        }
-        catch {
-            return { ok: false, reason: controller.signal.aborted ? "timeout" : "request_failed" };
-        }
-    }
-    finally {
-        clearTimeout(timer);
-    }
-    if (status === 401 || status === 403)
-        return { ok: false, reason: "unauthorized" };
-    if (status === 404)
-        return { ok: false, reason: "not_found" };
-    if (status < 200 || status >= 300)
-        return { ok: false, reason: "http_error" };
-    let body;
-    try {
-        body = text === "" ? null : JSON.parse(text);
-    }
-    catch {
-        return { ok: false, reason: "bad_response" };
-    }
-    const effectiveText = typeof body === "object" &&
-        body !== null &&
-        typeof body.effective_text === "string"
-        ? body.effective_text
-        : null;
-    if (effectiveText === null)
-        return { ok: false, reason: "bad_response" };
-    return { ok: true, text: effectiveText };
-}
-/**
- * The bin's `event-text` subcommand, wired to the real process. Success
- * prints the effective text on stdout and returns 0; every failure prints
- * nothing on stdout, one reason on stderr, and returns 1 — `event-hook.sh`
- * reads the exit code, never parses stdout to guess.
- */
-export async function runEventTextCommand(argv, env = process.env, 
-/** Test seam: the home the session's connection record is read from. */
-resolveFrom = {}) {
-    const [event, ...rest] = argv;
-    if (rest.length !== 0 || typeof event !== "string" || event === "") {
-        process.stderr.write(`missing or extra arguments\n${USAGE}\n`);
-        return 1;
-    }
-    const sessionId = env.CLAUDE_CODE_SESSION_ID;
-    if (!sessionId) {
-        process.stderr.write(`no_session_id: CLAUDE_CODE_SESSION_ID is not set\n${USAGE}\n`);
-        return 1;
-    }
-    let options;
-    try {
-        options = resolveDashboardAuth(sessionId, env, resolveFrom);
-    }
-    catch (err) {
-        const start = err;
-        process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
-        return 1;
-    }
-    const output = await fetchEventText(event, options, {
-        fetch: (input, init) => fetch(input, init),
-        requestTimeoutMs: EVENT_TEXT_REQUEST_TIMEOUT_MS,
-    });
-    if (!output.ok) {
-        process.stderr.write(`${output.reason}: could not fetch the effective "${event}" text from the dashboard\n`);
-        return 1;
-    }
-    process.stdout.write(output.text);
-    return 0;
-}