@thehammer/danx-dashboard-mcp 0.1.77 → 0.1.79

package/README.md

@@ -45,7 +45,7 @@ Every plan carries a `status`, computed fresh on every read and never stored —
 | Status | Meaning |
 |---|---|
 | `complete` | At least one card, and every card Done or Cancelled. Wins even with no session — a finished plan needs nobody. |
-| `awaiting-session` | Not complete, and no session is LIVE on the plan. A `plan_sessions` row is never released when a session merely ends (only when the plan itself is deleted), so this checks real liveness — an unrevoked/unexpired listener ticket, OR `last_active_at` within the same lease window — never just "has a session ever connected". |
+| `awaiting-session` | Not complete, and no session is LIVE on the plan. A `plan_sessions` row is never released when a session merely ends (only when the plan itself is deleted), so this checks real liveness — `last_active_at` within the last minute — never just "has a session ever connected". A working session's event stream stamps that activity every 15 seconds on its own, so an open, idle session stays live with no tool calls. |
 | `building` | Not complete, a live session is connected, and at least one card is ToDo/In Progress, or carries an unnamed active state (Blocked, Needs Help — i.e. an OPEN problem, DX-2830 — and, once it exists, Verify): work started and is either moving or stuck. |
 | `planning` | Everything else: no cards, or only Review/Backlog/terminal cards with at least one not Done/Cancelled. |
 
@@ -63,7 +63,7 @@ CLAUDE_CODE_SESSION_ID=<session> npx -y @thehammer/danx-dashboard-mcp@<version>
 - **Reach check.** After minting, `bridge` proves the credential can read every board the connected plan's cards live on (`GET /api/plans/mine?fields=cards`, then `GET /api/issues/:id/problems` for one card per board — the routes that run the same board-allowlist + `read` check the stream itself applies). A board it cannot read stops it with `board_unreadable` rather than streaming on and dropping that board's events. Then, once, `{"type":"ready","boards":[…]}`.
 - **Ticket.** `bridge` mints the session's listener ticket (`POST /api/plan-sessions/me/stream-ticket`, 10 s timeout) and keeps it in the process. A ticket authorizes reading that one session's event stream and nothing else, and is only issued while the session is connected to a plan. Minting a new one ends the previous listener.
 - **Output — JSON Lines.** One `{"type":"event","id":<id|null>,"text":"…"}` per event on the connected plan's cards, where `text` is `[DX-8 "Title" repo:board] newms87 answered "Which rollout order?": chose "Pause E2E" — note: "only this week"`, `… answered "…": "<free-form answer>"`, `… commented: "…"`, `… opened a problem: "…"`, `… blocked the card: "…"`, or `… unblocked the card`. An event it cannot read still produces one, with a `could not read event` text. Nothing for keep-alives, reconnects or re-mints. The session's own writes are never echoed back to it.
-- **Stopping.** Last, one `{"type":"stopped","reason":"…","detail":"…"}` and exit, only on a terminal outcome: `not_connected`, `unauthorized` (401/403), `mint_refused` (any other non-transient refusal), `mint_bad_response`, `superseded` / `replaced` (exit 0), `revoked`, or `refused` (two freshly minted tickets refused in a row). A transient mint failure (network, timeout, 408, 429, 5xx) backs off and retries; a lapsed ticket lease re-mints.
+- **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`, `unauthorized` (401/403), `mint_refused` (any other non-transient refusal), `mint_bad_response`, `board_unreadable` / `scope_check_failed` (the reach check above), `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). 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.
 
 ## Build + test

package/dist/bridge.js

@@ -76,9 +76,14 @@ const TAKEOVER_REASONS = new Set(["superseded", "replaced"]);
 const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BRIDGE_SUBCOMMAND} ` +
     `[--resume-ids <event-id>[,<event-id>...]]`;
 /**
- * The remedy per terminal reason. ONE map, so the message a session is shown and
- * the message a log carries can never drift, and a new reason without a remedy
- * is a compile-visible omission rather than a silent blank.
+ * The remedy per terminal reason THIS module knows about. ONE map, so the
+ * message a session is shown and the message a log carries can never drift.
+ * `satisfies` makes a reason missing its remedy a compile error here — but
+ * `reason` can also arrive at runtime from the dashboard's own SSE end event
+ * (`ListenStopped.reason` is an open string, not this union), so a build that
+ * predates a newer dashboard reason still needs an honest, generic fallback
+ * rather than an index miss: that is `DEFAULT_STOP_FIX`, reached only for a
+ * reason genuinely outside this list, never for one of the reasons above.
  */
 export const STOP_FIXES = {
     no_connection_record: "call plan_connect again in this session — its danx-dashboard MCP server records the connection the bridge needs " +
@@ -91,6 +96,11 @@ export const STOP_FIXES = {
     mint_bad_response: "check that DANXBOT_DASHBOARD_URL for this session's MCP server points at a danxbot dashboard",
     board_unreadable: "scope this session's dashboard credential to read that board, or connect a plan whose cards all live on boards it can read",
     scope_check_failed: "check the dashboard is reachable and this session is connected to a plan, then call plan_connect again",
+    // A newer ticket exists (superseded) or another connection is already using
+    // this one (replaced) — THIS process is ending because the session is
+    // already served elsewhere, not because anything is broken.
+    superseded: "no action needed — a newer ticket was minted for this session, and a fresh bridge is already using it",
+    replaced: "no action needed — another connection is already using this session's ticket; call plan_connect again only if that was unexpected",
     revoked: "call plan_connect again to mint a new listener ticket for this session",
     refused: "call plan_connect again to mint a new listener ticket for this session",
 };
@@ -149,7 +159,9 @@ export function resolveBridgeOptions(args, env, options = {}) {
     }
     catch (err) {
         const credentialError = err;
-        throw new BridgeStartError("credential_unavailable", `the credential this session's danx-dashboard MCP server declared cannot be resolved here: ${credentialError.message}`, credentialError.fix ?? fixForStop("credential_unavailable"));
+        throw new BridgeStartError("credential_unavailable", `the credential this session's danx-dashboard MCP server declared cannot be resolved here: ${credentialError.message}`, 
+        // CredentialError.fix is a required string, never absent — no fallback needed.
+        credentialError.fix);
     }
     const fingerprint = credentialFingerprint(token);
     if (fingerprint !== record.fingerprint) {
@@ -333,6 +345,9 @@ export async function verifyPlanBoardsReadable(options, deps) {
             break;
     }
     for (const [boardId, cardId] of firstCardPerBoard) {
+        // `?board=` is not read by this route's auth check (it derives the board from
+        // `cardId`'s own `board_id` — `resolveIssueBoardId`) — kept only so the URL and
+        // the `board read of ${boardId}` label above it name the same board at a glance.
         const url = `${options.dashboardUrl}${ISSUES_PATH}/${encodeURIComponent(cardId)}/problems?board=${encodeURIComponent(boardId)}`;
         const outcome = await request(options, deps, `board read of ${boardId}`, url);
         if (outcome.kind === "transient")

package/dist/index.js

@@ -882,10 +882,15 @@ async function main() {
 // spawns, not just a direct `node dist/index.js`.
 //
 // `bridge` is the one subcommand: the session event stream client the danxbot
-// plugin's plan event bridge runs. It never boots the MCP server; its whole
-// configuration is its environment (dashboard URL, credential, session id) plus
-// `--resume-ids`. Any OTHER argument is refused rather than ignored, so a typo
-// cannot silently start an MCP server on stdio where the bridge was meant to run.
+// plugin's plan event bridge runs. It never boots the MCP server; its only
+// input is `CLAUDE_CODE_SESSION_ID` (read from its environment) plus
+// `--resume-ids` — the dashboard URL, credential source, and credential itself
+// come from the session-connection record this server's own `plan_connect`
+// wrote (`session-connection.ts`), never from the bridge's own environment
+// (DX-2862: a bridge trusting its own ambient `DANXBOT_DISPATCH_TOKEN` is the
+// exact bug this repo fixed). Any OTHER argument is refused rather than
+// ignored, so a typo cannot silently start an MCP server on stdio where the
+// bridge was meant to run.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
     const [subcommand, ...rest] = process.argv.slice(2);
     if (subcommand === BRIDGE_SUBCOMMAND) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.77",
+  "version": "0.1.79",
   "description": "Stdio MCP server wrapping danxbot's dashboard /api/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
   "license": "MIT",
   "type": "module",