@thehammer/danx-dashboard-mcp 0.1.99 → 0.1.101

package/dist/bridge.js

@@ -184,6 +184,27 @@ export const MAX_REFUSED_TICKETS_IN_A_ROW = 2;
 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;
+/**
+ * DX-3099 — how many consecutive 15s heartbeat POSTs may fail to LAND
+ * (network error, timeout, 5xx, 408/429 — never an ordinary 401/403 answer,
+ * which proves the pipe itself still works) while this process still
+ * believes it is `"streaming"`, before that counts as evidence the current
+ * stream connection is dead without having errored — the exact "alive but
+ * not reporting" signature the investigation found: the SSE connection can
+ * read as established at the OS level and never trip `listen.ts`'s own
+ * read-idle timeout, while every outbound heartbeat silently never lands
+ * (the send call's own result used to be discarded entirely — see the
+ * card). `3 * HEARTBEAT_INTERVAL_MS` = 45s, deliberately UNDER
+ * `SESSION_LIVENESS_WINDOW_MS` (60s, `plan-session-heartbeat.ts`) so this
+ * process self-heals before, or right around, the moment the dashboard
+ * would itself start reporting the session `unattached` — never a shorter
+ * freshness window (that constant is untouched) and never a blind
+ * "restart more eagerly" (no external watchdog, no timer-driven kill): this
+ * fires only on repeated, OBSERVED delivery failure, self-diagnosed by the
+ * SAME process that is already streaming. Card: DX-3099 (AC3 forbids both
+ * of the obvious wrong fixes this constant is not).
+ */
+export const HEARTBEAT_SILENT_FAILURE_THRESHOLD = 3;
 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>...]]`;
@@ -616,13 +637,18 @@ async function sendHeartbeat(options, deps, connection) {
         body.reason = connection.reason;
     if (connection.inventory !== undefined)
         body.inventory = connection.inventory;
-    await request(options, deps, "heartbeat", `${options.dashboardUrl}${HEARTBEAT_PATH}`, {
+    const outcome = 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).
+    // DX-3099 — this is now the ONE place a heartbeat's own outcome is
+    // inspected. `request()` still never throws, and a 401/403 is still an
+    // ordinary answer this function does not retry for (the credential is
+    // whatever it is; there is nothing to redo about THIS request) — only a
+    // "transient" outcome (network error, timeout, 5xx, 408/429) means the
+    // request never landed at all, which is exactly the signal the silent-
+    // failure counter in `runBridge` below needs. Still never throws.
+    return outcome.kind === "answer";
 }
 /**
  * Mint, stream, re-mint — until a terminal outcome, which it writes as the one
@@ -642,6 +668,16 @@ export async function runBridge(options, deps) {
     let stoppedReason = null;
     let heartbeatSuppressed = false;
     let lastInventoryOk = true;
+    // DX-3099 — consecutive heartbeat POSTs that failed to LAND while this
+    // process still believed `connectionState === "streaming"`. Reset to 0 the
+    // moment a heartbeat lands, or the moment state leaves "streaming" for any
+    // other reason (a fresh connect cycle earns a clean slate — see the `for
+    // (;;)` loop below). `forceReconnect` is the CURRENT connectOnce attempt's
+    // own abort, supplied fresh by `listen.ts` on every attempt via
+    // `onConnectionAttempt` below; calling it after that attempt has already
+    // ended is a harmless no-op.
+    let heartbeatFailureStreak = 0;
+    let forceReconnect = null;
     const heartbeatTick = () => {
         if (heartbeatSuppressed)
             return;
@@ -649,7 +685,48 @@ export async function runBridge(options, deps) {
             ? { state: "streaming", inventory: lastInventoryOk ? "ok" : "unavailable" }
             : connectionState === "stopped"
                 ? { state: "stopped", reason: stoppedReason ?? undefined }
-                : { state: "reconnecting" });
+                : { state: "reconnecting" }).then((landed) => {
+            // DX-3099 — only counts while THIS process still believes it is
+            // streaming: that is the exact desync the card found (the client
+            // believes it is fine; the dashboard has nothing recent for it). A
+            // failure while reconnecting/degraded is not new information — the
+            // existing mint-backoff / degrade-retry machinery already owns
+            // recovery there.
+            if (connectionState !== "streaming" || landed) {
+                heartbeatFailureStreak = 0;
+                return;
+            }
+            heartbeatFailureStreak += 1;
+            if (heartbeatFailureStreak < HEARTBEAT_SILENT_FAILURE_THRESHOLD)
+                return;
+            heartbeatFailureStreak = 0;
+            // AC4 — the session finds out, rather than continuing to believe it is
+            // connected: an ordinary event line, delivered immediately (`origin:
+            // null` skips D4's agent/machine hold — see `routeEvent`'s docblock),
+            // which the plugin already relays into the session's inbox unchanged
+            // (see this module's own docblock).
+            routeEvent({
+                type: "event",
+                id: null,
+                text: oneLine(`${DIGEST_PREFIX} this session's listener stopped reaching the dashboard for ` +
+                    `${Math.round((HEARTBEAT_SILENT_FAILURE_THRESHOLD * HEARTBEAT_INTERVAL_MS) / 1000)}s while it still ` +
+                    `believed it was streaming — forcing a fresh connection now.`),
+                origin: null,
+            });
+            // AC2 — force the CURRENT connectOnce attempt to end now, rather than
+            // wait on listen.ts's own read-idle timeout (which this exact failure
+            // mode can outlive indefinitely — see the card: the connection reads
+            // as established and never stops producing keep-alive bytes on the
+            // read side, only the outbound heartbeat silently never lands). The
+            // new attempt reconnects with the SAME ticket; the dashboard's own
+            // "ONE OPEN STREAM PER TICKET" rule (`attachListener`,
+            // `plan-session-listeners.ts`) then tells the OLD, now-superseded
+            // registry entry to end (`"replaced"`) — which is what actually
+            // releases the exclusive claim, as a natural side effect of THIS SAME
+            // PROCESS reconnecting, never an external watchdog and never a second
+            // process racing the first.
+            forceReconnect?.();
+        });
     };
     const heartbeat = deps.scheduleInterval(heartbeatTick, HEARTBEAT_INTERVAL_MS);
     async function settle(reason, detail, code, extra) {
@@ -781,6 +858,11 @@ export async function runBridge(options, deps) {
     }
     for (;;) {
         connectionState = "reconnecting";
+        // DX-3099 — a fresh cycle earns a clean slate: any abort captured from a
+        // now-abandoned prior attempt is dropped (calling it would be a harmless
+        // no-op anyway) and the failure streak starts over at 0.
+        forceReconnect = null;
+        heartbeatFailureStreak = 0;
         const minted = await mintTicket(options, deps);
         if (minted.kind === "terminal") {
             const outcome = await settle(minted.reason, minted.detail, 1);
@@ -868,6 +950,12 @@ export async function runBridge(options, deps) {
             onState: (state) => {
                 connectionState = state;
             },
+            // DX-3099 — captures the CURRENT connectOnce attempt's own abort, so
+            // the heartbeat-failure self-heal above always targets exactly the
+            // in-flight connection, never a stale one from an earlier attempt.
+            onConnectionAttempt: (abort) => {
+                forceReconnect = abort;
+            },
         });
         const stopped = run.stopped;
         if (stopped === null)

package/dist/listen.js

@@ -499,6 +499,11 @@ export async function runListener(options, deps) {
     };
     const connectOnce = async () => {
         const controller = new AbortController();
+        // DX-3099 — hand THIS attempt's own abort to the caller before doing
+        // anything else, so a force-reconnect requested at any point during the
+        // attempt (including before the fetch even starts) targets exactly this
+        // controller, never a stale one from a previous attempt.
+        deps.onConnectionAttempt?.(() => controller.abort());
         let idle;
         const armIdle = () => {
             clearTimeout(idle);

package/package.json

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