@thehammer/danx-dashboard-mcp 0.1.96 → 0.1.98

package/dist/bridge.js

@@ -568,14 +568,23 @@ function classifyAdmissionRefusal(refusal) {
     }
     return null;
 }
-const EXIT_NEVER_RESTART = new Set([
+// DX-3028 (code-review + architecture-review finding) — typed against
+// `ListenStopReason` (the closed union `scope_narrowed` aside — see that
+// type's own docblock), NOT bare `Set<string>`: a typo'd member here used to
+// have zero compile-time signal, silently falling into the generic
+// `degrade-server-fixable` default below — exactly the kind of drift this
+// safety-critical classification can least afford. `satisfies readonly
+// ListenStopReason[]` on each array is what makes a typo a build error.
+const EXIT_NEVER_RESTART_LIST = [
     "no_connection_record",
     "not_connected",
     "superseded",
     "replaced",
     "session_is_worker",
-]);
-const DEGRADE_NO_HEARTBEAT = new Set(["credential_unavailable", "credential_mismatch"]);
+];
+const EXIT_NEVER_RESTART = new Set(EXIT_NEVER_RESTART_LIST);
+const DEGRADE_NO_HEARTBEAT_LIST = ["credential_unavailable", "credential_mismatch"];
+const DEGRADE_NO_HEARTBEAT = new Set(DEGRADE_NO_HEARTBEAT_LIST);
 export function degradePolicyFor(reason) {
     if (EXIT_NEVER_RESTART.has(reason))
         return "exit";
@@ -796,6 +805,14 @@ export async function runBridge(options, deps) {
         if (!readyEmitted) {
             readyEmitted = true;
             const inventory = await fetchPlanInventory(options, deps);
+            // DX-3028 (AC1, code-review + architecture-review finding) — this is
+            // the ONE place `lastInventoryOk` is ever written; the 15s heartbeat
+            // reads it on every "streaming" tick (see `heartbeatTick` above). Must
+            // agree with the SAME `ready` record's own `degraded` decision below —
+            // a heartbeat reporting `inventory:"ok"` while the `ready` record just
+            // told the operator `degraded:true` would be exactly the untruthful
+            // state AC1 exists to prevent.
+            lastInventoryOk = inventory.kind === "ok";
             if (inventory.kind === "ok") {
                 deps.write({
                     type: "ready",
@@ -919,6 +936,18 @@ export async function runBridge(options, deps) {
         }
     }
 }
+/**
+ * DX-3028 — the ONE real `scheduleInterval` implementation, shared by
+ * `runBridge`'s deps AND `runBridgeCommand`'s own start-time
+ * `degrade-no-heartbeat` keep-alive (see the comment at that call site for
+ * why the latter needs one too). A single real `setInterval`/`clearInterval`
+ * pair, so the two call sites can never drift into two different ideas of
+ * what "the real process's interval" means.
+ */
+function realScheduleInterval(tick, ms) {
+    const timer = setInterval(tick, ms);
+    return { stop: () => clearInterval(timer) };
+}
 /** The bin's `bridge` subcommand, wired to the real process. */
 export async function runBridgeCommand(argv, env = process.env, 
 /** Test seam: the home the session's connection record is read from. */
@@ -950,14 +979,28 @@ resolveFrom = {}) {
         process.stderr.write(`${start.reason}: ${start.message}. Fix: ${start.fix}.\n`);
         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.
+        // DX-3028 (AC2, architecture-review finding) — `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 — but it MUST still
+        // genuinely idle until the plugin kills and restarts it fresh on a
+        // watched-path change, exactly like the runtime `settle()` path does.
+        // The runtime path stays alive because ITS heartbeat `setInterval` (in
+        // `runBridge`, started before its mint loop) is already registered with
+        // libuv by the time it degrades; THIS path is reached before `runBridge`
+        // (and its interval) ever exists, so a bare `return new Promise(() => {})`
+        // here registers no handle at all — Node has nothing left pending once
+        // the call stack unwinds and the process exits almost immediately,
+        // defeating the "idles forever" contract `BridgeOptions.watchedPaths`
+        // exists to serve (DX-2953's watchdog only ever gets a chance to act on
+        // a process that is actually still running). `realScheduleInterval()`
+        // gives it the same kind of keep-alive handle the runtime path gets for
+        // free, ticking a no-op (there is nothing truthful to heartbeat here).
+        realScheduleInterval(() => { }, HEARTBEAT_INTERVAL_MS);
+        // `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 */
         });
@@ -969,9 +1012,6 @@ 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) };
-        },
+        scheduleInterval: realScheduleInterval,
     });
 }

package/dist/index.js

@@ -811,7 +811,7 @@ async (args) => {
         }),
     });
 });
-server.tool("plan_add_record", "Add a goal, rule or caveat to your connected plan (POST /api/plans/mine/records). A GOAL is an outcome the work is measured against. A RULE is a constraint that must hold while it is worked. A CAVEAT is a lasting trade-off or limitation of the ARCHITECTURE — never progress, status or a session note (those are comments on the card). `body` is ONE plain statement of at most 250 characters; the evidence, history and detail go in `context` (markdown). An overlong body is refused with a 400 naming its length. The server allocates a permanent reference (`G-1`, `R-4`, `CAV-12`). Takes no plan id; `session_not_connected` → `plan_connect` first. Returns the record plus that kind's list.", {
+server.tool("plan_add_record", "Add a goal, rule or caveat to your connected plan (POST /api/plans/mine/records). A GOAL is an outcome the work is measured against. A RULE is a constraint that must hold while it is worked. A CAVEAT is a lasting trade-off or limitation of the ARCHITECTURE — never progress, status or a session note (those are comments on the card). `body` is ONE plain statement of at most 250 characters; the evidence, history and detail go in `context` (markdown). An overlong body is refused with a 400 naming its length. The server allocates a permanent reference (`G-1`, `R-4`, `CAV-12`). Takes no plan id; `session_not_connected` → `plan_connect` first. DX-3072 — returns the created record plus `records_count` (that kind's live count, not the whole list, which can grow unboundedly over a plan's life); read the list itself with `plan_get({fields:[\"records:<kind>\"]})` or the dedicated GET.", {
     kind: z.enum(["goal", "rule", "caveat"]).describe("goal = outcome, rule = constraint, caveat = architecture trade-off."),
     body: z.string().min(1).describe("One plain statement, at most 250 characters. Details go in `context`."),
     context: z.string().optional().describe("Markdown detail behind the statement: evidence, history, examples."),
@@ -819,7 +819,7 @@ server.tool("plan_add_record", "Add a goal, rule or caveat to your connected pla
 server.tool("plan_get_record", "Read one goal/rule/caveat of your connected plan (GET /api/plans/mine/records/:rid) without pulling the whole plan. Takes no plan id; an unknown or another plan's record id → 404. Returns `{record: {id, planId, kind, refNum, ref, body, context, contentHash, createdAt, updatedAt}}` — `context` is the markdown detail, or null.", {
     record_id: z.number().int().positive().describe("A record id, from `plan_add_record`, `plan_get` or `plan_get_record` itself."),
 }, async (args) => jsonResult(await planGetRecord(client, args)));
-server.tool("plan_update_record", 'Edit a goal/rule/caveat of your connected plan (PATCH /api/plans/mine/records/:rid). The reference never moves. `body` stays ONE plain statement of at most 250 characters (400 otherwise); detail belongs in markdown `context`. `content_hash` must be the record\'s `contentHash` from your last read, and covers body AND context. On a mismatch nothing is written and you get `{error: "stale_plan_record", currentHash, currentBody, currentContext}`: merge into those and retry with `content_hash: currentHash`, never blindly. Takes no plan id. Returns the record plus that kind\'s list.', {
+server.tool("plan_update_record", 'Edit a goal/rule/caveat of your connected plan (PATCH /api/plans/mine/records/:rid). The reference never moves. `body` stays ONE plain statement of at most 250 characters (400 otherwise); detail belongs in markdown `context`. `content_hash` must be the record\'s `contentHash` from your last read, and covers body AND context. On a mismatch nothing is written and you get `{error: "stale_plan_record", currentHash, currentBody, currentContext}`: merge into those and retry with `content_hash: currentHash`, never blindly. Takes no plan id. DX-3072 — returns the edited record plus `records_count` (that kind\'s live count, not the whole list — see `plan_add_record`).', {
     record_id: z.number().int().positive().describe("The record id to edit."),
     content_hash: z.string().describe("The record's `contentHash` from your last read. Required."),
     body: z.string().min(1).describe("The new statement, at most 250 characters. Plain text."),
@@ -829,11 +829,11 @@ server.tool("plan_update_record", 'Edit a goal/rule/caveat of your connected pla
         .optional()
         .describe("New markdown detail. Omit to keep the stored context; null clears it."),
 }, async (args) => jsonResult(await planUpdateRecord(client, args)));
-server.tool("plan_delete_record", 'Soft-delete a goal/rule/caveat of your connected plan (DELETE /api/plans/mine/records/:rid). Its reference is retired permanently, never reused. `content_hash` must be the record\'s `contentHash` from your last read; a stale hash deletes nothing and returns `{error: "stale_plan_record", currentHash, currentBody, currentContext}`. Takes no plan id. Unknown or already-deleted id → 404. Returns that kind\'s remaining list.', {
+server.tool("plan_delete_record", 'Soft-delete a goal/rule/caveat of your connected plan (DELETE /api/plans/mine/records/:rid). Its reference is retired permanently, never reused. `content_hash` must be the record\'s `contentHash` from your last read; a stale hash deletes nothing and returns `{error: "stale_plan_record", currentHash, currentBody, currentContext}`. Takes no plan id. Unknown or already-deleted id → 404. DX-3072 — returns `{records_count}`, that kind\'s remaining live count, not the whole list (see `plan_add_record`).', {
     record_id: z.number().int().positive().describe("The record id to delete."),
     content_hash: z.string().describe("The record's `contentHash` from your last read. Required."),
 }, async (args) => jsonResult(await planDeleteRecord(client, args)));
-server.tool("plan_add_note", "Write a milestone note to a plan's timeline, via POST /api/plans/:plan_id/notes (DX-2915). A note is a MILESTONE, not a log — write one for a card (or related group of cards) finishing, an important decision, or a meaningful goal/rule/caveat/architecture-section change; routine step progress stays a card comment, never a note. Terse tone: `title` at most 60 characters, `body` (the wrap-up) at most 250 (both 400 if too long, naming the limit and actual length). Links resolve on read into what they point at (a card's title, a record's ref+body, a section's title): an unknown card, an unparseable or foreign record ref, or an unknown or foreign section id is refused 400 naming exactly which one. A card link does NOT require the card to be a member of this plan; a record/section link MUST belong to THIS plan. `author` is stamped from your identity server-side — there is no field for it. TAKES AN EXPLICIT `plan_id` (like `plan_remove_card`/`plan_rename`), so a dispatched worker with no plan connection can still write. Unknown plan → 404. Returns the new note plus the plan's latest notes page.", {
+server.tool("plan_add_note", "Write a milestone note to a plan's timeline, via POST /api/plans/:plan_id/notes (DX-2915). A note is a MILESTONE, not a log — write one for a card (or related group of cards) finishing, an important decision, or a meaningful goal/rule/caveat/architecture-section change; routine step progress stays a card comment, never a note. Terse tone: `title` at most 60 characters, `body` (the wrap-up) at most 250 (both 400 if too long, naming the limit and actual length). Links resolve on read into what they point at (a card's title, a record's ref+body, a section's title): an unknown card, an unparseable or foreign record ref, or an unknown or foreign section id is refused 400 naming exactly which one. A card link does NOT require the card to be a member of this plan; a record/section link MUST belong to THIS plan. `author` is stamped from your identity server-side — there is no field for it. TAKES AN EXPLICIT `plan_id` (like `plan_remove_card`/`plan_rename`), so a dispatched worker with no plan connection can still write. Unknown plan → 404. DX-3072 — returns the new note plus `notes_count` (the plan's total live note count, not the latest page); read the timeline itself with `plan_get({fields:[\"notes\"]})` or the dedicated GET.", {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
     title: z.string().min(1).describe("At most 60 characters."),
     body: z.string().min(1).describe("The wrap-up, at most 250 characters."),
@@ -844,7 +844,7 @@ server.tool("plan_add_note", "Write a milestone note to a plan's timeline, via P
         .describe("Goal/rule/caveat references this note announces, e.g. `[\"G-1\", \"R-3\", \"CAV-2\"]`."),
     section_ids: z.array(z.number().int().positive()).optional().describe("Architecture section ids this note announces."),
 }, async (args) => jsonResult(await planAddNote(client, args)));
-server.tool("plan_update_note", 'Edit a plan note, via PATCH /api/plans/:plan_id/notes/:note_id (DX-2915). `content_hash` MUST be the note\'s `contentHash` from your last read; a mismatch writes NOTHING and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — merge into those and retry with `content_hash: currentHash`, never blindly. `title`/`body` are each optional and keep their stored value when omitted. The link fields (`card_ids`/`record_refs`/`section_ids`) are all-or-nothing AS A GROUP: omit all three to leave the stored link set untouched; send ANY one of them to REPLACE THE WHOLE SET — there is no per-link add/remove. The hash covers title, body AND the link set. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`. Unknown plan or note id → 404. Returns the edited note plus the plan\'s latest notes page.', {
+server.tool("plan_update_note", 'Edit a plan note, via PATCH /api/plans/:plan_id/notes/:note_id (DX-2915). `content_hash` MUST be the note\'s `contentHash` from your last read; a mismatch writes NOTHING and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — merge into those and retry with `content_hash: currentHash`, never blindly. `title`/`body` are each optional and keep their stored value when omitted. The link fields (`card_ids`/`record_refs`/`section_ids`) are all-or-nothing AS A GROUP: omit all three to leave the stored link set untouched; send ANY one of them to REPLACE THE WHOLE SET — there is no per-link add/remove. The hash covers title, body AND the link set. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`. Unknown plan or note id → 404. DX-3072 — returns the edited note plus `notes_count` (see `plan_add_note`), not the latest page.', {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
     note_id: z.number().int().positive().describe("The note id to edit."),
     content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
@@ -854,15 +854,15 @@ server.tool("plan_update_note", 'Edit a plan note, via PATCH /api/plans/:plan_id
     record_refs: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with card_ids/section_ids)."),
     section_ids: z.array(z.number().int().positive()).optional().describe("REPLACES the whole link set when sent (with card_ids/record_refs)."),
 }, async (args) => jsonResult(await planUpdateNote(client, args)));
-server.tool("plan_delete_note", 'Soft-delete a plan note, via DELETE /api/plans/:plan_id/notes/:note_id (DX-2915). `content_hash` must be the note\'s `contentHash` from your last read; a stale hash deletes nothing and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — the same shape `plan_update_note` uses. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`. Unknown plan, unknown note, or an already-deleted note → 404. Returns the plan\'s remaining latest notes page.', {
+server.tool("plan_delete_note", 'Soft-delete a plan note, via DELETE /api/plans/:plan_id/notes/:note_id (DX-2915). `content_hash` must be the note\'s `contentHash` from your last read; a stale hash deletes nothing and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — the same shape `plan_update_note` uses. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`. Unknown plan, unknown note, or an already-deleted note → 404. DX-3072 — returns `{notes_count}`, the plan\'s remaining live note count, not the latest page.', {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
     note_id: z.number().int().positive().describe("The note id to delete."),
     content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
 }, async (args) => jsonResult(await planDeleteNote(client, args)));
-server.tool("plan_add_card", "Add an existing card to the plan this session is connected to, via POST /api/plans/mine/cards (DX-2683). The card may live on ANY board — that is what a plan is for. Idempotent: re-adding a card already on the plan is a no-op, not an error, and a card may sit in several plans at once. This adds MEMBERSHIP only; it never edits the card. TAKES NO PLAN ID: the plan is resolved from your connected session. Not connected → `{error: \"session_not_connected\"}`. Unknown card → 404. Returns the plan's full member list.", {
+server.tool("plan_add_card", "Add an existing card to the plan this session is connected to, via POST /api/plans/mine/cards (DX-2683). The card may live on ANY board — that is what a plan is for. Idempotent: re-adding a card already on the plan is a no-op, not an error, and a card may sit in several plans at once. This adds MEMBERSHIP only; it never edits the card. TAKES NO PLAN ID: the plan is resolved from your connected session. Not connected → `{error: \"session_not_connected\"}`. Unknown card → 404. DX-3072 — returns `{card_id, member: true, cards_count}` (the attachment's own confirmation plus the plan's total member-card count), not the full member list — a plan can hold hundreds of cards, and the whole list was a ~500KB reply that a caller could not read. Read the list itself with `plan_get({fields:[\"cards\"]})` (paged) when you actually need it.", {
     card_id: z.string().min(1).describe("An existing card id, e.g. `DX-2683`."),
 }, async (args) => jsonResult(await planAddCard(client, args)));
-server.tool("plan_remove_card", "Remove a card from a plan via DELETE /api/plans/:plan_id/cards/:card_id (DX-2740) — the sibling of `plan_add_card`. The card may live on ANY board. Idempotent: removing a card that was never a member is a no-op, not an error — the same idempotent-toggle contract `issue_dependency` add/remove uses. This removes MEMBERSHIP only; it never edits or deletes the card itself, and its membership in every OTHER plan is untouched. Unlike `plan_add_card`, this takes an EXPLICIT `plan_id` rather than acting on your connected session's plan — you may remove a card from any plan you can name. Unknown plan → 404. Returns the plan's remaining member list.", {
+server.tool("plan_remove_card", "Remove a card from a plan via DELETE /api/plans/:plan_id/cards/:card_id (DX-2740) — the sibling of `plan_add_card`. The card may live on ANY board. Idempotent: removing a card that was never a member is a no-op, not an error — the same idempotent-toggle contract `issue_dependency` add/remove uses. This removes MEMBERSHIP only; it never edits or deletes the card itself, and its membership in every OTHER plan is untouched. Unlike `plan_add_card`, this takes an EXPLICIT `plan_id` rather than acting on your connected session's plan — you may remove a card from any plan you can name. Unknown plan → 404. DX-3072 — returns `{card_id, member: false, cards_count}`, the plan's remaining member-card count, not the full list (see `plan_add_card`).", {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
     card_id: z.string().min(1).describe("An existing card id, e.g. `DX-2683`."),
 }, async (args) => jsonResult(await planRemoveCard(client, args)));

package/package.json

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