@thehammer/danx-dashboard-mcp 0.1.201 → 0.1.203

package/README.md

@@ -46,6 +46,10 @@ CLAUDE_CODE_SESSION_ID=<session> npx -y @thehammer/danx-dashboard-mcp@<version>
 - **Stopping.** Last, one `{"type":"stopped","reason":"…","detail":"…","fix":"…"}` and exit, only on a terminal outcome. `fix` is the remedy shown to the session (`STOP_FIXES` in `src/bridge.ts` — never a log-only hint), so a session that hits a stop it cannot otherwise see still knows what to do about it. Terminal reasons: `no_connection_record` / `credential_unavailable` / `credential_mismatch` (the start-time checks above), `not_connected` (a `409 session_not_connected` at mint OR at stream admission, or a live `end("not_connected")` — all three mapped identically), `plan_archived` (DX-3809 — the plan was archived or deleted while the stream was live; the session is disconnected, and reconnects by hand after a restore), `unauthorized` (401/403), `mint_refused` (any other non-transient mint refusal), `mint_bad_response`, `superseded` / `replaced` (exit 0 — a newer or replacing connection already serves this session, so `fix` says no action is needed), `revoked`, or `refused` (two freshly minted tickets refused in a row with no more specific classification). A transient mint failure (network, timeout, 408, 429, 5xx) backs off and retries; a lapsed ticket lease re-mints.
 - **Reconnect and resume.** A read-idle timeout (three missed keep-alives) turns a silently dead connection into a drop. Capped exponential backoff (1s → 30s) that resets only after a healthy connection, with `Last-Event-ID`, so a dashboard restart replays what was missed and nothing is emitted twice. `--resume-ids` carries the same guarantee across a process restart: the ids already delivered seed the duplicate guard, and the highest is the first `Last-Event-ID`. The dashboard floors that replay at the later of the session's first ticket and when it joined its current plan, so a restart loses nothing and a plan move replays nothing from before the move.
 
+## `restart-notice` — what a restarted session was working on (DX-3928)
+
+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.
+
 ## Build + test
 
 ```bash

package/dist/index.js

@@ -77,8 +77,9 @@ import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.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 { resolveDeclaredCredential } from "./credential.js";
-import { recordSessionConnectionAfterConnect } from "./session-connection.js";
+import { projectKeyOf, recordSessionConnectionAfterConnect } from "./session-connection.js";
 import { createListenerReminder, isPlanConnectedOnThisMachine, } from "./listener-reminder.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -448,7 +449,7 @@ strictTool("attach_file", "Attach a LOCAL file to a card: `card_id` + `path` (an
 // no existing plan for an id to name yet.
 strictTool("plan_connect", 
 // DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
-"Connect THIS session to a plan. ONE CALL IS ENOUGH TO START: the reply carries `{session, movedFrom, browserInstruction, briefing, listenerHealth}` — `browserInstruction` is a server-built action to take NOW: it names the plan's URL and tells you to open it (in-app browser if you have one, else default), keep that tab open for the whole session without navigating it away, and use a different tab for your own browsing — the operator's tab for following and talking to you. Returned on every connect, including a re-connect, so it doubles as the post-context-loss reminder. `briefing` is every goal/rule/caveat (ref+body), every architecture section (id+title), the plan's own ref/name/status, a first page of open cards (id/type/status/title/openProblemCount/assignedAgent) with a `morePagesHint` when more exist, and the closed-card count — usually replacing the plan read + card batch-read a fresh session used to need. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and `movedFrom: {id, name} | null` says which plan it left (null = no plan, or already this one). Binds only your OWN session, resolved from the session id this server forwards; afterwards a `danxbot_api` call to a `/api/plans/mine/...` route (there is no dedicated plan-write tool) acts on this plan and takes no plan id. `listenerHealth` reports the event bridge's state — `null` (no session), or `{attached, state: \"unattached\"|\"credential_mismatch\"|\"healthy\", nextStep}` naming a concrete fix per unhealthy state (same shape the plan list/get routes report). Once healthy, every comment, answer, problem added and block/unblock on this plan's cards reaches the session unpolled, relayed by the plugin's event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<statement>\": chose \"Pause E2E\"`. An action the operator DECLINES arrives as `... rejected the action \"<title>\" for \"<statement>\" — reason: \"<note>\". Do not perform it; re-plan from the reason` (a decision with `outcome: \"rejected\"` — never treat it as work done). Pass `title` (call `get_session({session_id:\"self\"})` first and forward its `title` verbatim) so the dashboard shows the same name Claude does — this server cannot read it itself. The response's `reminders[]` (when present) carries the mantra — read and follow it.", {
+"Connect THIS session to a plan. ONE CALL IS ENOUGH TO START: the reply carries `{session, movedFrom, browserInstruction, briefing, listenerHealth, missedEvents}` — `missedEvents` is `{events, omitted}`: the operator events on this plan that no session had been told about before you connected, oldest first, newest 50 at most (`omitted` counts older ones) — read them before anything else. `browserInstruction` is a server-built action to take NOW: it names the plan's URL and tells you to open it (in-app browser if you have one, else default), keep that tab open for the whole session without navigating it away, and use a different tab for your own browsing — the operator's tab for following and talking to you. Returned on every connect, including a re-connect, so it doubles as the post-context-loss reminder. `briefing` is every goal/rule/caveat (ref+body), every architecture section (id+title), the plan's own ref/name/status, a first page of open cards (id/type/status/title/openProblemCount/assignedAgent) with a `morePagesHint` when more exist, and the closed-card count — usually replacing the plan read + card batch-read a fresh session used to need. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and `movedFrom: {id, name} | null` says which plan it left (null = no plan, or already this one). Binds only your OWN session, resolved from the session id this server forwards; afterwards a `danxbot_api` call to a `/api/plans/mine/...` route (there is no dedicated plan-write tool) acts on this plan and takes no plan id. `listenerHealth` reports the event bridge's state — `null` (no session), or `{attached, state: \"unattached\"|\"credential_mismatch\"|\"healthy\", nextStep}` naming a concrete fix per unhealthy state (same shape the plan list/get routes report). Once healthy, every comment, answer, problem added and block/unblock on this plan's cards reaches the session unpolled, relayed by the plugin's event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<statement>\": chose \"Pause E2E\"`. An action the operator DECLINES arrives as `... rejected the action \"<title>\" for \"<statement>\" — reason: \"<note>\". Do not perform it; re-plan from the reason` (a decision with `outcome: \"rejected\"` — never treat it as work done). Pass `title` (call `get_session({session_id:\"self\"})` first and forward its `title` verbatim) so the dashboard shows the same name Claude does — this server cannot read it itself. The response's `reminders[]` (when present) carries the mantra — read and follow it.", {
     plan_id: z.number().int().positive().describe("The plan id, from the plans list (`danxbot_api` `GET /api/plans`)."),
     title: z
         .string()
@@ -468,6 +469,7 @@ async (args) => {
         ...result,
         ...recordSessionConnectionAfterConnect(result, {
             sessionId: config.session?.id,
+            projectKey: projectKeyOf(process.cwd()),
             dashboardUrl: connection.dashboardUrl,
             source: connection.source,
             fingerprint: connection.fingerprint,
@@ -534,9 +536,16 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             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 !== undefined) {
         console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BRIDGE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", "${ACTIVITY_SUBCOMMAND}", and "${EVENT_TEXT_SUBCOMMAND}")`);
+            `"${BRIDGE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", "${ACTIVITY_SUBCOMMAND}", "${EVENT_TEXT_SUBCOMMAND}", and "${RESTART_NOTICE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/restart-notice.js

@@ -0,0 +1,140 @@
+/**
+ * `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.
+ *
+ * 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 (`findPredecessorConnection`).
+ *
+ * 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, reason on stderr: the lookup itself failed (credential, network,
+ *     non-2xx, bad shape). Never silent: the hook prints a could-not-load notice.
+ *
+ * The credential is the PREDECESSOR's own record's source, resolved through the
+ * same resolver the bridge uses, so the lookup reaches the dashboard that
+ * connected it. READ-ONLY: it advances no cursor on the server.
+ */
+import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
+import { findPredecessorConnection, projectKeyOf } from "./session-connection.js";
+export const RESTART_NOTICE_SUBCOMMAND = "restart-notice";
+export const RESTART_NOTICE_REQUEST_TIMEOUT_MS = 5_000;
+/** 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`. */
+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);
+    }
+    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" };
+    }
+    if (typeof body !== "object" || body === null || !("restart" in body))
+        return { ok: false, reason: "bad_response" };
+    if (body.restart === null)
+        return { ok: true, text: null };
+    // A notice exists, so the registry row MUST have answered with its text: a
+    // missing one is a server/registry fault, reported rather than papered over.
+    const reminders = Array.isArray(body.reminders) ? body.reminders : [];
+    const notice = reminders.find((r) => r.key === RESTART_NOTICE_REMINDER_KEY);
+    if (typeof notice?.text !== "string" || notice.text === "")
+        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;
+    }
+    let predecessor;
+    try {
+        predecessor = findPredecessorConnection(projectKeyOf(cwd), sessionId, resolveFrom);
+    }
+    catch (err) {
+        process.stderr.write(`unreadable_records: ${err.message}\n`);
+        return 1;
+    }
+    if (predecessor === null)
+        return 0;
+    let options;
+    try {
+        options = resolveBridgeOptions({ sessionId: predecessor.sessionId, resumeIds: [] }, env, resolveFrom);
+    }
+    catch (err) {
+        const start = err;
+        process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
+        return 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) {
+        process.stderr.write(`${output.reason}: could not ask the dashboard what the previous session of this project was working\n`);
+        return 1;
+    }
+    if (output.text !== null)
+        process.stdout.write(output.text);
+    return 0;
+}

package/dist/session-connection.js

@@ -31,10 +31,17 @@
  */
 import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 /** One canonical shape (CLAUDE.md Core Principle 1) — a record of any other version is refused, never adapted. */
-export const SESSION_CONNECTION_SCHEMA_VERSION = 1;
+// DX-3928 — v2 adds `projectKey`, the directory the connecting session ran in, so a
+// restarted session (a NEW session id, no record of its own) can find which plan the
+// previous session of the same project was on (`findPredecessorConnection`).
+export const SESSION_CONNECTION_SCHEMA_VERSION = 2;
 export const STALE_RECORD_MS = 7 * 24 * 60 * 60 * 1000;
+/** DX-3928 — the one definition of "the same project": the resolved working directory. */
+export function projectKeyOf(cwd) {
+    return resolve(cwd);
+}
 export function sessionConnectionDir(home = homedir()) {
     return join(home, ".config", "danxbot", "plan-sessions");
 }
@@ -140,6 +147,7 @@ export function recordSessionConnectionAfterConnect(result, inputs, write = writ
     try {
         write({
             sessionId: inputs.sessionId,
+            projectKey: inputs.projectKey,
             dashboardUrl: inputs.dashboardUrl,
             source: inputs.source,
             fingerprint: inputs.fingerprint,
@@ -159,9 +167,10 @@ export function invalidRecordReason(value) {
         return "it is not an object";
     const r = value;
     if (r.schemaVersion !== SESSION_CONNECTION_SCHEMA_VERSION) {
-        return `schemaVersion is ${JSON.stringify(r.schemaVersion)}, not ${SESSION_CONNECTION_SCHEMA_VERSION}`;
+        return (`schemaVersion is ${JSON.stringify(r.schemaVersion)}, not ${SESSION_CONNECTION_SCHEMA_VERSION} — ` +
+            "a session connected by an older MCP server wrote it; call plan_connect again to rewrite it");
     }
-    for (const field of ["sessionId", "dashboardUrl", "fingerprint", "connectedAt"]) {
+    for (const field of ["sessionId", "projectKey", "dashboardUrl", "fingerprint", "connectedAt"]) {
         if (typeof r[field] !== "string" || r[field] === "")
             return `${field} is not a non-empty string`;
     }
@@ -174,3 +183,47 @@ export function invalidRecordReason(value) {
         return typeof source.name === "string" && source.name !== "" ? null : "source.name is not a variable name";
     return `source.kind is ${JSON.stringify(source.kind)}, which this version does not know`;
 }
+/**
+ * DX-3928 — the record of the session that ran in `projectKey` before
+ * `currentSessionId`: the newest record for that project, written by another
+ * session, within `STALE_RECORD_MS`. `null` when there is none.
+ *
+ * A record that cannot be understood (another schema version, not JSON) is
+ * SKIPPED here and nowhere else: this answers "was a plan being worked in this
+ * project", and a record from an older server cannot say. Every consumer of a
+ * session's OWN record (`readSessionConnection`) still fails loud.
+ */
+export function findPredecessorConnection(projectKey, currentSessionId, options = {}) {
+    const dir = sessionConnectionDir(options.home ?? homedir());
+    const now = options.now ?? Date.now();
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return null; // nothing written yet
+    }
+    let newest = null;
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(dir, name), "utf-8"));
+        }
+        catch {
+            continue;
+        }
+        if (invalidRecordReason(parsed) !== null)
+            continue;
+        const record = parsed;
+        if (record.projectKey !== projectKey || record.sessionId === currentSessionId)
+            continue;
+        const connectedAt = Date.parse(record.connectedAt);
+        if (!Number.isFinite(connectedAt) || now - connectedAt > STALE_RECORD_MS)
+            continue;
+        if (newest === null || connectedAt > Date.parse(newest.connectedAt))
+            newest = record;
+    }
+    return newest;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.201",
+  "version": "0.1.203",
   "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, danxbot_complete, and other per-dispatch lifecycle callbacks) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",