@thehammer/danx-dashboard-mcp 0.1.93 → 0.1.95

package/dist/bridge.js

@@ -89,11 +89,12 @@
  * is the only argument and holds no secret; the credential is whatever this
  * session's own MCP server declared, resolved here from that declaration.
  */
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { errorCodeOf } from "./json-body.js";
 import { oneLine } from "./one-line.js";
 import { credentialFingerprint, describeCredentialSource, readCredential, } from "./credential.js";
-import { readSessionConnection } from "./session-connection.js";
+import { readSessionConnection, sessionConnectionPath } from "./session-connection.js";
 import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, READ_IDLE_TIMEOUT_MS, runListener, } from "./listen.js";
 /**
  * DX-2730 D4 — WHICH EVENTS WAKE THE SESSION, NOW THAT EVERY ONE OF THEM CAN.
@@ -169,12 +170,20 @@ export const STREAM_TICKET_PATH = "/api/plan-sessions/me/stream-ticket";
 // streaming, and is best-effort (one attempt, no retry/backoff).
 export const PLAN_MINE_PATH = "/api/plans/mine";
 export const SESSION_ID_HEADER = "x-danx-session-id";
+// DX-3028 (AC1) — `POST /api/plan-sessions/me/heartbeat` (DX-2952's server
+// route, `plan-sessions-routes.ts#handleHeartbeat`). Every 15s this process
+// reports its truthful streaming state; see `sendHeartbeat` below.
+export const HEARTBEAT_PATH = "/api/plan-sessions/me/heartbeat";
 /** How long one dashboard request may take before it counts as a transient failure. */
 export const REQUEST_TIMEOUT_MS = 10_000;
 export const MINT_INITIAL_BACKOFF_MS = 1_000;
 export const MINT_MAX_BACKOFF_MS = 60_000;
 /** A freshly minted ticket refused this many times in a row is a terminal outcome, not a loop. */
 export const MAX_REFUSED_TICKETS_IN_A_ROW = 2;
+/** DX-3028 (AC1) — the dashboard's own heartbeat cadence; see the card's AC1. */
+export const HEARTBEAT_INTERVAL_MS = 15_000;
+/** DX-3028 (AC2) — the server-fixable degraded reasons' own periodic retry cadence. */
+export const DEGRADED_RETRY_INTERVAL_MS = 5 * 60_000;
 const TRANSIENT_CLIENT_STATUSES = new Set([408, 429]);
 const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BRIDGE_SUBCOMMAND} ` +
     `[--resume-ids <event-id>[,<event-id>...]]`;
@@ -219,6 +228,9 @@ export const STOP_FIXES = {
     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",
+    // DX-3028 — this session id belongs to a worker dispatch, not an operator
+    // plan session; 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",
 };
 export const DEFAULT_STOP_FIX = "call plan_connect again in this session to restart the bridge";
 export function fixForStop(reason) {
@@ -250,11 +262,17 @@ export class BridgeStartError extends Error {
     // reason: start.reason, ...})` needs it to be.
     reason;
     fix;
-    constructor(reason, detail, fix) {
+    /** DX-3028 — see `BridgeOptions.instanceId`. Always populated: minted before any of the three start-time checks run. */
+    instanceId;
+    /** DX-3028 — see `BridgeOptions.watchedPaths`. Empty for `no_connection_record` (there is nothing to watch yet). */
+    paths;
+    constructor(reason, detail, fix, instanceId, paths) {
         super(detail);
         this.name = "BridgeStartError";
         this.reason = reason;
         this.fix = fix;
+        this.instanceId = instanceId;
+        this.paths = paths;
     }
 }
 /**
@@ -262,18 +280,48 @@ export class BridgeStartError extends Error {
  * that this process holds the SAME credential that server does. Never falls back
  * to an ambient `DANXBOT_DISPATCH_TOKEN`: that fallback is precisely DX-2862.
  */
+const INSTANCE_ID_ENV = "DANX_BRIDGE_INSTANCE_ID";
+/**
+ * DX-3028 — this process's own instance id: read from `DANX_BRIDGE_INSTANCE_ID`
+ * (minted by the plugin's `start()` before it spawns the run process, and
+ * carried down to this subcommand's env unchanged), or freshly minted for a
+ * manual/hand run that has no plugin supplying one. Every stop record and
+ * every heartbeat names this same id for the life of the process.
+ */
+function resolveInstanceId(env) {
+    const declared = env[INSTANCE_ID_ENV];
+    return typeof declared === "string" && declared.trim() !== "" ? declared.trim() : randomUUID();
+}
+/**
+ * DX-3028 — the on-disk paths this bridge's authentication depends on, for
+ * `BridgeOptions.watchedPaths` (see its docblock). A `file`-sourced
+ * credential adds its own path; an `env`-sourced one has no file
+ * (`credential.ts` ~47-48, ~90-95).
+ */
+function watchedPathsFor(record, home) {
+    const paths = [sessionConnectionPath(record.sessionId, home)];
+    if (record.source.kind === "file")
+        paths.push(record.source.path);
+    return paths;
+}
 export function resolveBridgeOptions(args, env, options = {}) {
     const home = options.home ?? homedir();
+    const instanceId = resolveInstanceId(env);
     let record;
     try {
         record = readSessionConnection(args.sessionId, { home });
     }
     catch (err) {
-        throw new BridgeStartError("no_connection_record", err.message, fixForStop("no_connection_record"));
+        throw new BridgeStartError("no_connection_record", err.message, fixForStop("no_connection_record"), instanceId, []);
     }
     if (record === null) {
-        throw new BridgeStartError("no_connection_record", `session ${args.sessionId} has no dashboard connection record — no danx-dashboard MCP server has connected it to a plan`, fixForStop("no_connection_record"));
+        throw new BridgeStartError("no_connection_record", `session ${args.sessionId} has no dashboard connection record — no danx-dashboard MCP server has connected it to a plan`, fixForStop("no_connection_record"), instanceId, []);
     }
+    // DX-3028 — computed as soon as a connection record exists, even if the
+    // credential itself later fails to resolve: `credential_unavailable`'s own
+    // stop record still needs `paths` (the connection record path, at least)
+    // so the plugin has something to watch for a retry.
+    const watchedPaths = watchedPathsFor(record, home);
     let token;
     try {
         token = readCredential(record.source, env);
@@ -282,18 +330,20 @@ export function resolveBridgeOptions(args, env, options = {}) {
         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 is a required string, never absent — no fallback needed.
-        credentialError.fix);
+        credentialError.fix, instanceId, watchedPaths);
     }
     const fingerprint = credentialFingerprint(token);
     if (fingerprint !== record.fingerprint) {
         throw new BridgeStartError("credential_mismatch", `${describeCredentialSource(record.source)} now yields credential ${fingerprint}, but this session's ` +
-            `danx-dashboard MCP server is using ${record.fingerprint} — the bridge would authenticate as somebody else`, fixForStop("credential_mismatch"));
+            `danx-dashboard MCP server is using ${record.fingerprint} — the bridge would authenticate as somebody else`, fixForStop("credential_mismatch"), instanceId, watchedPaths);
     }
     return {
         dashboardUrl: record.dashboardUrl.replace(/\/+$/, ""),
         token,
         sessionId: args.sessionId,
         resumeIds: args.resumeIds,
+        instanceId,
+        watchedPaths,
     };
 }
 /**
@@ -408,6 +458,13 @@ export async function mintTicket(options, deps) {
     if (status === 409 && errorCodeOf(body) === "session_not_connected") {
         return { kind: "terminal", reason: "not_connected", detail: "the session is not connected to a plan" };
     }
+    // DX-3028 (AC2) — matched BEFORE the generic mint_refused fallback below,
+    // which every other 409 falls into: this session id belongs to a worker
+    // dispatch (`SessionIsWorkerError`, the same shape the heartbeat route
+    // already gives it, DX-2952).
+    if (status === 409 && errorCodeOf(body) === "session_is_worker") {
+        return { kind: "terminal", reason: "session_is_worker", detail: "this session id belongs to a worker dispatch, not an operator plan session" };
+    }
     // DX-2920 (AC 30660) — this credential IS accepted; it just cannot read every
     // board the connected plan covers (`unreadableBoardsRefusal`, dashboard
     // `plan-scope.ts`). Calling that `unauthorized` told the session to fix its
@@ -511,36 +568,133 @@ function classifyAdmissionRefusal(refusal) {
     }
     return null;
 }
+const EXIT_NEVER_RESTART = new Set([
+    "no_connection_record",
+    "not_connected",
+    "superseded",
+    "replaced",
+    "session_is_worker",
+]);
+const DEGRADE_NO_HEARTBEAT = new Set(["credential_unavailable", "credential_mismatch"]);
+export function degradePolicyFor(reason) {
+    if (EXIT_NEVER_RESTART.has(reason))
+        return "exit";
+    if (DEGRADE_NO_HEARTBEAT.has(reason))
+        return "degrade-no-heartbeat";
+    return "degrade-server-fixable";
+}
+/**
+ * One heartbeat POST. NEVER throws and NEVER stops the bridge on failure
+ * (card AC1 — "a failed heartbeat never stops the bridge"): `request()`
+ * itself already classifies every network/timeout/5xx failure as
+ * `{kind:"transient"}` rather than throwing, and a 401/403 (a revoked
+ * credential) simply comes back as an ordinary non-2xx answer this function
+ * discards — there is nothing meaningful to retry a heartbeat POST for, and
+ * the NEXT tick will just try again. A heartbeat refused with 401/403 cannot
+ * report itself, so `computeListenerHealth`'s staleness fallback
+ * (`heartbeatIsFresh`) is what eventually reflects it: the row's
+ * `last_heartbeat_at` stops advancing, and once it falls outside
+ * `SESSION_LIVENESS_WINDOW_MS` the badge reads `unattached`, NOT
+ * `credential_mismatch` — `credential_mismatch` is computed only from a
+ * heartbeat that DID land with `state:"streaming"` and a live ticket whose
+ * issuer hash differs from the caller's; it has no way to represent "the
+ * heartbeat call itself was rejected". This gap is real and is recorded on
+ * the card rather than silently papered over.
+ */
+async function sendHeartbeat(options, deps, connection) {
+    const body = { state: connection.state };
+    if (connection.reason !== undefined)
+        body.reason = connection.reason;
+    if (connection.inventory !== undefined)
+        body.inventory = connection.inventory;
+    await request(options, deps, "heartbeat", `${options.dashboardUrl}${HEARTBEAT_PATH}`, {
+        method: "POST",
+        body: JSON.stringify({ connection: body }),
+    });
+    // Deliberately no error handling beyond this: `request()` never throws, and
+    // this function does not even inspect the answer — a heartbeat is
+    // fire-and-forget by design (see the docblock above).
+}
 /**
  * Mint, stream, re-mint — until a terminal outcome, which it writes as the one
  * `stopped` record. Returns 0 when another listener took over, 1 otherwise.
  */
 export async function runBridge(options, deps) {
     const delivered = capResumeIds(options.resumeIds);
-    function stop(reason, detail, code, extra) {
-        // DX-2730 D4 — every terminal return goes through here, so this is the ONE
-        // place that cancels a pending digest timer. CANCELLED, never flushed: for
+    // DX-3028 (AC1) — this process's own truthful state, reported every
+    // HEARTBEAT_INTERVAL_MS regardless of what the mint/stream loop is doing.
+    // `onState` (threaded into `runListener` below) is the ONLY thing that ever
+    // sets "streaming"; everything else (mint backoff, degraded idling) is
+    // "reconnecting" or "stopped". `heartbeatSuppressed` covers the two
+    // start-time-unauthenticatable degrade reasons (card AC2): the process has
+    // no credential it can report WITH, so it sends nothing at all rather than
+    // an unauthenticated POST that would just be refused.
+    let connectionState = "reconnecting";
+    let stoppedReason = null;
+    let heartbeatSuppressed = false;
+    let lastInventoryOk = true;
+    const heartbeatTick = () => {
+        if (heartbeatSuppressed)
+            return;
+        void sendHeartbeat(options, deps, connectionState === "streaming"
+            ? { state: "streaming", inventory: lastInventoryOk ? "ok" : "unavailable" }
+            : connectionState === "stopped"
+                ? { state: "stopped", reason: stoppedReason ?? undefined }
+                : { state: "reconnecting" });
+    };
+    const heartbeat = deps.scheduleInterval(heartbeatTick, HEARTBEAT_INTERVAL_MS);
+    async function settle(reason, detail, code, extra) {
+        // DX-2730 D4 — every settle goes through here, so this is the ONE place
+        // that cancels a pending digest timer. CANCELLED, never flushed: for
         // `superseded`/`replaced` a newer process is already streaming this same
         // session and will receive (and hold, and eventually flush) these same
         // held events itself via the dashboard's replay — flushing here too would
-        // double-deliver the digest. For every other terminal reason, whatever is
-        // still held was never marked delivered (see `emitNow`), so a future
-        // process picks it up the same way — a live, un-fired `setTimeout` would
-        // otherwise also keep this process's event loop alive for up to
-        // `DIGEST_INTERVAL_MS` after it should have exited.
+        // double-deliver the digest. For every other reason, whatever is still
+        // held was never marked delivered (see `emitNow`), so a future process
+        // (or this same one, after a degrade retry) picks it up the same way — a
+        // live, un-fired `setTimeout` would otherwise also keep this process's
+        // event loop alive on top of the heartbeat interval, for no reason.
         if (digestTimer !== null) {
             clearTimeout(digestTimer);
             digestTimer = null;
         }
+        const policy = degradePolicyFor(reason);
+        const degraded = policy !== "exit";
+        const fix = reason === "scope_narrowed" ? scopeNarrowedFix(extra?.boards ?? []) : (extra?.fix ?? fixForStop(reason));
         if (reason === "scope_narrowed") {
             if (extra?.boards === undefined) {
-                throw new Error('stop("scope_narrowed", ...) requires boards — unreachable through the exported overloads above');
+                throw new Error('settle("scope_narrowed", ...) requires boards — unreachable through the exported overloads above');
             }
-            deps.write({ type: "stopped", reason, detail, boards: extra.boards, fix: scopeNarrowedFix(extra.boards) });
-            return code;
+            deps.write({ type: "stopped", reason, detail, boards: extra.boards, fix, instanceId: options.instanceId, paths: options.watchedPaths, degraded });
+        }
+        else {
+            deps.write({ type: "stopped", reason, detail, refusal: extra?.refusal, fix, instanceId: options.instanceId, paths: options.watchedPaths, degraded });
         }
-        deps.write({ type: "stopped", reason, detail, refusal: extra?.refusal, fix: extra?.fix ?? fixForStop(reason) });
-        return code;
+        if (policy === "exit") {
+            heartbeat.stop();
+            return { kind: "exit", code };
+        }
+        stoppedReason = reason;
+        connectionState = "stopped";
+        if (policy === "degrade-no-heartbeat") {
+            // DX-3028 (AC2) — "Three of these cannot report anything": this process
+            // has no credential it can authenticate a heartbeat WITH, so it sends
+            // none (`heartbeatSuppressed`) and has no basis to retry the mint
+            // itself either — it idles until the plugin, watching `watchedPaths`
+            // for a change, kills and restarts it fresh (a new process re-reads
+            // the credential from scratch). Never resolves on its own.
+            heartbeatSuppressed = true;
+            await new Promise(() => {
+                /* deliberately never settles — see the comment above */
+            });
+        }
+        // degrade-server-fixable: keep heartbeating `stopped`, and retry the
+        // mint/stream on our own after DEGRADED_RETRY_INTERVAL_MS, on top of the
+        // plugin's own watched-path restart (harmless overlap — whichever fires
+        // first wins; a restarted process just re-enters this same loop clean).
+        heartbeatSuppressed = false;
+        await deps.sleep(DEGRADED_RETRY_INTERVAL_MS);
+        return { kind: "retry" };
     }
     let backoff = MINT_INITIAL_BACKOFF_MS;
     let refusedInRow = 0;
@@ -617,9 +771,15 @@ export async function runBridge(options, deps) {
         emitNow(output);
     }
     for (;;) {
+        connectionState = "reconnecting";
         const minted = await mintTicket(options, deps);
-        if (minted.kind === "terminal")
-            return stop(minted.reason, minted.detail, 1);
+        if (minted.kind === "terminal") {
+            const outcome = await settle(minted.reason, minted.detail, 1);
+            if (outcome.kind === "exit")
+                return outcome.code;
+            refusedInRow = 0;
+            continue;
+        }
         if (minted.kind === "transient") {
             await deps.sleep(backoff);
             backoff = Math.min(MINT_MAX_BACKOFF_MS, backoff * 2);
@@ -684,6 +844,13 @@ export async function runBridge(options, deps) {
                 run.emitted = true;
                 routeEvent(output);
             },
+            // DX-3028 (AC1) — the only place `connectionState` ever becomes
+            // "streaming": `listen.ts`'s `connectOnce` calls this the moment the
+            // SSE connection is actually open, and the outer `for(;;)` above
+            // already resets it to "reconnecting" before every mint attempt.
+            onState: (state) => {
+                connectionState = state;
+            },
         });
         const stopped = run.stopped;
         if (stopped === null)
@@ -692,10 +859,15 @@ export async function runBridge(options, deps) {
         // `Set.has()` is a runtime check only, so it cannot narrow `stopped.reason`
         // for the compiler — leaving it a `Set` lookup here would keep every
         // downstream branch's exhaustive narrowing (which is what makes the final
-        // fallthrough's `stop(stopped.reason, ...)` call type-check against the
+        // fallthrough's `settle(stopped.reason, ...)` call type-check against the
         // closed `ListenStopReason` overload) from working.
-        if (stopped.reason === "superseded" || stopped.reason === "replaced")
-            return stop(stopped.reason, stopped.detail, 0);
+        if (stopped.reason === "superseded" || stopped.reason === "replaced") {
+            const outcome = await settle(stopped.reason, stopped.detail, 0);
+            if (outcome.kind === "exit")
+                return outcome.code;
+            refusedInRow = 0;
+            continue;
+        }
         if (stopped.reason === "lease_expired") {
             refusedInRow = 0;
             continue;
@@ -707,14 +879,21 @@ export async function runBridge(options, deps) {
                 // like its mint-time counterpart — never counted toward the generic
                 // refused-ticket retry budget below, which exists for an admission
                 // refusal with no more specific explanation than "not admitted".
-                return stop(classified.reason, classified.detail, 1);
+                const outcome = await settle(classified.reason, classified.detail, 1);
+                if (outcome.kind === "exit")
+                    return outcome.code;
+                refusedInRow = 0;
+                continue;
             }
         }
         if (stopped.reason === "refused") {
             const provedHealthy = run.emitted || deps.now() - startedAt >= HEALTHY_CONNECTION_MS;
             refusedInRow = provedHealthy ? 1 : refusedInRow + 1;
             if (refusedInRow >= MAX_REFUSED_TICKETS_IN_A_ROW) {
-                return stop("refused", `${stopped.detail} (a freshly minted ticket was refused ${refusedInRow} times in a row)`, 1);
+                const outcome = await settle("refused", `${stopped.detail} (a freshly minted ticket was refused ${refusedInRow} times in a row)`, 1);
+                if (outcome.kind === "exit")
+                    return outcome.code;
+                refusedInRow = 0;
             }
             continue;
         }
@@ -725,9 +904,19 @@ export async function runBridge(options, deps) {
             // `detail`) — no `?? []`, no optional check, `stopped.boards` IS
             // `string[]` once narrowed to this branch.
             const boards = stopped.boards;
-            return stop("scope_narrowed", boardUnreadableDetail(boards, stopped.detail), 1, { boards });
+            const outcome = await settle("scope_narrowed", boardUnreadableDetail(boards, stopped.detail), 1, { boards });
+            if (outcome.kind === "exit")
+                return outcome.code;
+            refusedInRow = 0;
+            continue;
+        }
+        {
+            const outcome = await settle(stopped.reason, stopped.detail, 1);
+            if (outcome.kind === "exit")
+                return outcome.code;
+            refusedInRow = 0;
+            continue;
         }
-        return stop(stopped.reason, stopped.detail, 1);
     }
 }
 /** The bin's `bridge` subcommand, wired to the real process. */
@@ -751,13 +940,27 @@ resolveFrom = {}) {
     }
     catch (err) {
         const start = err;
-        // A start that never happened still reports itself the way every other
-        // terminal outcome does — one stop record the plugin relays into the
-        // session — AND on stderr, for the case where there is no session to relay
-        // into (a hand run).
-        write({ type: "stopped", reason: start.reason, detail: start.message, fix: start.fix });
+        // DX-3028 (AC2) — a start-time failure still reports itself the way every
+        // other stop does — one stop record the plugin relays into the session
+        // (now carrying `paths`/`instanceId`/`degraded`) — AND on stderr, for the
+        // case where there is no session to relay into (a hand run).
+        const policy = degradePolicyFor(start.reason);
+        const degraded = policy !== "exit";
+        write({ type: "stopped", reason: start.reason, detail: start.message, fix: start.fix, instanceId: start.instanceId, paths: start.paths, degraded });
         process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
-        return 1;
+        if (!degraded)
+            return 1;
+        // DX-3028 (AC2) — `credential_unavailable` / `credential_mismatch`:
+        // this process has no credential it can authenticate a heartbeat with
+        // (see `settle`'s identical `degrade-no-heartbeat` branch), so it sends
+        // none and idles until the plugin kills and restarts it fresh on a
+        // watched-path change. `return`ed directly (never `await`ed then fallen
+        // through) so TypeScript's definite-assignment check for `options` below
+        // sees this branch as never reaching that line, which is also true at
+        // runtime — this promise never settles.
+        return new Promise(() => {
+            /* deliberately never settles */
+        });
     }
     return runBridge(options, {
         fetch: (input, init) => fetch(input, init),
@@ -766,5 +969,9 @@ resolveFrom = {}) {
         now: Date.now,
         readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
         requestTimeoutMs: REQUEST_TIMEOUT_MS,
+        scheduleInterval: (tick, ms) => {
+            const timer = setInterval(tick, ms);
+            return { stop: () => clearInterval(timer) };
+        },
     });
 }

package/dist/listen.js

@@ -541,6 +541,9 @@ export async function runListener(options, deps) {
                 await response.body?.cancel();
                 return { kind: "dropped", healthy: false, detail: `HTTP ${response.status} with no readable body` };
             }
+            // DX-3028 — the connection is genuinely open and readable now; see
+            // `ListenDeps.onState`'s docblock for exactly what this reports.
+            deps.onState?.("streaming");
             const parser = new SseParser();
             const decoder = new TextDecoder();
             for await (const chunk of response.body) {

package/package.json

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