@thehammer/danx-dashboard-mcp 0.1.98 → 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/handlers.js

@@ -232,8 +232,8 @@ export async function issueCreate(client, args, defaultBoard) {
         body.effort_level = args.effort_level;
     if (args.list_id !== undefined)
         body.list_id = args.list_id;
-    if (args.gate_decisions !== undefined)
-        body.gate_decisions = args.gate_decisions;
+    if (args.quality_gates !== undefined)
+        body.quality_gates = args.quality_gates;
     // DX-1895 (explicit-only) — forward the caller's explicit auto-triage
     // decision; the server stamps false when absent (never auto-triaged).
     // Per-child flags ride along inside phase_children entries verbatim.
@@ -683,42 +683,41 @@ export async function issueSolution(client, args) {
     }
 }
 /**
- * Flip a single card's per-card quality-gate `required` flag via
- * POST /api/issues/:id/quality-gates/:gate {required} — the same write the
+ * Put ONE quality gate on a card, or take it off, via
+ * POST /api/issues/:id/quality-gates/:gate {action} — the same write the
  * dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY
- * post-create path to mark a gate required/not — `issue_create` carries
- * `gate_decisions` at birth, and `issue_edit` rejects gate keys; without
- * this tool an agent that created a card cannot turn a gate on afterward.
+ * post-create path to change a card's gates: `issue_create` names them at
+ * birth via `quality_gates`, and `issue_edit` rejects gate keys.
  *
  * `gate` is a registry name (`plan-dependency` | `plan-architecture` |
  * `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality`).
- * An unknown gate is a 400 from the server (never a silent no-op).
+ * An unknown gate is a 400 from the server (never a silent no-op), as is a
+ * card whose type is never gated (`Epic` / `Feature` / `Task`).
  *
- * Board requirement is TRI-STATE per gate, NOT a binary on/off
- * (`board_quality_gate_settings.default_state`): `required` = always runs
- * (this per-card flag is irrelevant); `optional` = ENABLED, runs WHEN this
- * per-card flag is true (per-card opt-in — `optional` is NOT "off");
- * `disabled` = never runs (this flag is inert). So flipping `required:true`
- * here launches the gate when the board state is `required` OR `optional`;
- * it is inert ONLY when the board state is `disabled`. Source of truth:
- * `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.
+ * DX-3015 — there is no board tri-state to reason about any more. A gate is on
+ * the card or it is not, and every gate on a card is required, so `add` always
+ * means "this gate now runs on this card" and `remove` always means it does
+ * not. What the board still owns is the DEFAULT SET a NEW card is born with;
+ * it has no say over a card that already exists.
  *
- * `effort_level` (DX-1760) is an independent sibling write: present (incl.
- * `null`) sets `card_quality_gates.effort_level`; omitted leaves it untouched.
+ * Because of that, the response is plain `{issue}`. The old body carried
+ * `{applied, effective, reason}` because the per-card flag was only one of
+ * three inputs and the board could silently make the write a no-op — with the
+ * tri-state gone, the write IS the outcome and those fields would be constants.
  *
- * **Effectiveness echo.** The server response body is `{issue, applied: true,
- * effective, reason}`, not just `{issue}` — `client.request()` passes it
- * through VERBATIM (see `http-client.ts`'s header doc: "the envelope
- * passthrough is load-bearing"), so no transform is needed here for the
- * calling agent to see `effective` (what `isGateEffectivelyRequired` resolves
- * to right after this write, per the tri-state rule above) and `reason`
- * (`null` when it matches the `required` value just sent, otherwise which
- * board state overrode it). This closes the gap where a 200 alone could not
- * tell a fully-honored write from one the board's `required`/`disabled`
- * state made a complete no-op.
+ * `note` records why the gate is on the card; `effort_level` (DX-1760) sets
+ * `card_quality_gates.effort_level` (`null` clears a prior override). Both are
+ * `add`-only — the server 400s either one alongside `remove`, since a removed
+ * gate has no row to carry them.
+ *
+ * Re-adding a gate the card already carries updates `note`/`effort_level` and
+ * leaves any recorded verdict untouched, so `add` is never a way to quietly
+ * clear a `fail`. `remove` DOES discard the row and its verdict.
  */
 export async function issueQualityGate(client, args) {
-    const body = { required: args.required };
+    const body = { action: args.action };
+    if (args.note !== undefined)
+        body.note = args.note;
     if (args.effort_level !== undefined)
         body.effort_level = args.effort_level;
     return client.request({

package/dist/index.js

@@ -363,7 +363,7 @@ server.tool("issue_get",
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
 server.tool("issue_create", '`plan` is REQUIRED on every create (DX-3006): pass "mine" to put the card on THIS session\'s connected plan, or null when it deliberately belongs to no plan. There is no default and no inference — a card that names no plan is one nobody following the work can see, which is why the answer has to be given rather than omitted. "mine" while this session is on no plan is refused (409 session_not_connected) and creates NO card; a plan id is not accepted (a card is only ever created onto your own connected plan). This replaces the plan_add_card follow-up at creation time; plan_add_card remains for putting an EXISTING card on a plan. ' +
-    'Create a card via POST /api/issues. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `gate_decisions` is REQUIRED when the board has an OPTIONAL quality gate for the card\'s type: a missing one fails closed with 400 `{error, required_gate_decisions:[...]}` naming each gate — retry with one `{gate, enabled, note}` per listed gate. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child: true only when it should enter automatic triage/dispatch without human review; absent → false.', {
+    'Create a card via POST /api/issues. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `quality_gates` names the gates this card carries BEYOND the board\'s default set for its type — one `{gate, note?}` each. Omit it for just the board defaults; a gate you do not name simply is not on the card (there is no optional gate and nothing fails closed for going unnamed). Add one later with `issue_quality_gate`. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child: true only when it should enter automatic triage/dispatch without human review; absent → false.', {
     type: z.enum(ISSUE_TYPES),
     title: z.string().min(1).describe(TITLE_DESCRIBE),
     summary: z.string().min(1).optional().describe(SUMMARY_DESCRIBE),
@@ -380,15 +380,14 @@ server.tool("issue_create", '`plan` is REQUIRED on every create (DX-3006): pass
     ac: z.array(z.object({ title: z.string().min(1) })).optional(),
     effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     list_id: z.string().min(1).nullable().optional(),
-    gate_decisions: z
+    quality_gates: z
         .array(z.object({
         gate: z.string().min(1),
-        enabled: z.boolean(),
-        note: z.string(),
+        note: z.string().optional(),
         effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     }))
         .optional()
-        .describe("One {gate, enabled, note} per board-OPTIONAL gate of the card's type: `enabled` = does it run on this card, `note` = why. Board `required` gates always run and `disabled` never do; neither takes a decision (naming one → 400). Optional `effort_level` overrides a `plan-*` gate's reviewer rung."),
+        .describe("The gates this card carries BEYOND the board's default set for its type — one {gate, note?} each, `note` = why it applies here. Every gate on a card is required; a gate you do not name is not on the card at all (not displayed, not counted, never run), and omitting this field entirely is normal. Optional `effort_level` overrides a `plan-*` gate's reviewer rung."),
     phase_children: z
         .array(z.object({
         type: z.enum(NON_EPIC_TYPES),
@@ -401,15 +400,14 @@ server.tool("issue_create", '`plan` is REQUIRED on every create (DX-3006): pass
         description: z.string().describe(DESCRIPTION_DESCRIBE),
         ac: z.array(z.object({ title: z.string().min(1) })).optional(),
         effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
-        gate_decisions: z
+        quality_gates: z
             .array(z.object({
             gate: z.string().min(1),
-            enabled: z.boolean(),
-            note: z.string(),
+            note: z.string().optional(),
             effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
         }))
             .optional()
-            .describe("Same as the root gate_decisions, resolved against THIS child's type."),
+            .describe("Same as the root quality_gates, resolved against THIS child's type."),
         triage_enabled: z
             .boolean()
             .optional()
@@ -602,7 +600,7 @@ server.tool("issue_retire_branch", "Mark a card's own `card/<id>` branch RETIRED
     ...boardField,
 }, async (args) => jsonResult(await issueRetireBranch(client, args)));
 // ---------------- issue_quality_gate ----------------
-server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the only post-create way (issue_create takes gate_decisions; issue_edit refuses gate keys). PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate → 400. The board state per gate is tri-state: `required` always runs, `optional` runs WHEN this flag is true (optional is NOT off), `disabled` never runs. Optional `effort_level` overrides a `plan-*` gate's reviewer rung (null clears it). The write always succeeds and returns `{issue, applied: true, effective, reason}` — read `effective` (does the gate now run) and `reason` (why the board overrode your value), not just the 200. Board-scoped; see `board`.", {
+server.tool("issue_quality_gate", "Put one quality gate ON a card, or take it OFF, via POST /api/issues/:id/quality-gates/:gate {action} — the only post-create way (issue_create names gates in quality_gates; issue_edit refuses gate keys). A gate is on the card or it does not exist for it; every gate on a card is required, so `add` means it now runs and `remove` means it is gone (not displayed, not counted). Adding a gate at any time is fully supported — that is what this tool is for. PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate → 400; a never-gated card type (Epic/Feature/Task) → 400. `note` (why it applies) and `effort_level` (overrides a `plan-*` gate's reviewer rung; null clears it) are `add`-only — passing either with `remove` → 400. Re-adding a gate the card already has updates note/effort and KEEPS its verdict; `remove` discards the row and any verdict on it. Board-scoped; see `board`.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",
@@ -612,12 +610,18 @@ server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via P
         "code-architecture",
         "code-quality",
     ]),
-    required: z.boolean(),
+    action: z
+        .enum(["add", "remove"])
+        .describe("add = put this gate on the card; remove = take it off."),
+    note: z
+        .string()
+        .optional()
+        .describe("Why this gate applies to this card. `add` only."),
     effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueQualityGate(client, args)));
 // ---------------- issue_quality_gate_verdict ----------------
-server.tool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate VERDICT via PATCH /api/issues/:id/quality-gates/:gate {status, message} — the same write the dashboard Gates-tab Pass / Fail / Revert controls perform (DX-1373). SIBLING of `issue_quality_gate`, not a replacement: that one flips the per-card `required` FLAG (does this gate run at all), THIS one records the VERDICT (did it pass) — POST vs PATCH on the same resource, neither substitutes for the other. **Use this to close out a card you picked up with `issue_transition pickup {manual:true}`** (DX-946 operator-session self-pickup): `issue_transition complete` REFUSES 409 (`failed_gate: \"quality_gate_post\"`, `failed_post_gates[]`) while any required POST gate (`code-quality` / `code-test-quality` / `code-architecture`) is not `pass`, so without a verdict a manually-claimed card can never reach Done — it strands In Progress and its `conflict_on` / `waiting_on` edges then stall OTHER cards' dispatch. `status`: `pass` | `fail` | `pending` (revert a prior verdict, clears the message). `message` is the accountability record for the override, REQUIRED at >= 20 characters for `pass`/`fail` (shorter → 400), ignored for `pending`. Record the REAL reviewer finding, not a rubber stamp — a human-attributed override, stamped with the operator actor, standing in for a reviewer dispatch. A manual verdict is a PURE row write: no side effects — a manual `fail` never blocks the card and a manual `pass` never releases a dispatch. Unknown gate → 400; bad status → 400; unknown card → 404. Board-scoped; see `board`.", {
+server.tool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate VERDICT via PATCH /api/issues/:id/quality-gates/:gate {status, message} — the same write the dashboard Gates-tab Pass / Fail / Revert controls perform (DX-1373). SIBLING of `issue_quality_gate`, not a replacement: that one puts a gate ON or OFF the card (does this gate apply at all), THIS one records the VERDICT (did it pass) — POST vs PATCH on the same resource, neither substitutes for the other. **Use this to close out a card you picked up with `issue_transition pickup {manual:true}`** (DX-946 operator-session self-pickup): `issue_transition complete` REFUSES 409 (`failed_gate: \"quality_gate_post\"`, `failed_post_gates[]`) while any required POST gate (`code-quality` / `code-test-quality` / `code-architecture`) is not `pass`, so without a verdict a manually-claimed card can never reach Done — it strands In Progress and its `conflict_on` / `waiting_on` edges then stall OTHER cards' dispatch. `status`: `pass` | `fail` | `pending` (revert a prior verdict, clears the message). `message` is the accountability record for the override, REQUIRED at >= 20 characters for `pass`/`fail` (shorter → 400), ignored for `pending`. Record the REAL reviewer finding, not a rubber stamp — a human-attributed override, stamped with the operator actor, standing in for a reviewer dispatch. A manual verdict is a PURE row write: no side effects — a manual `fail` never blocks the card and a manual `pass` never releases a dispatch. Unknown gate → 400; bad status → 400; unknown card → 404. Board-scoped; see `board`.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",

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.98",
+  "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",