@thehammer/danx-dashboard-mcp 0.1.88 → 0.1.89

package/dist/handlers.js

@@ -392,7 +392,11 @@ export async function issueComment(client, args) {
         return client.request({
             method: "POST",
             path: `/${idEnc}/comments`,
-            body: { text, ...(args.metadata !== undefined ? { metadata: args.metadata } : {}) },
+            body: {
+                text,
+                ...(args.metadata !== undefined ? { metadata: args.metadata } : {}),
+                ...(args.problem_id !== undefined ? { problem_id: args.problem_id } : {}),
+            },
             board,
         });
     }
@@ -562,6 +566,12 @@ export async function issueChecklist(client, args) {
  * card is put in front of one; the reminder that used to ride the retired
  * `issue_requires_human({set: true})` now rides here instead.
  *
+ * DX-2942 — `statement` is capped at 100 characters server-side (a 400 names
+ * the actual length otherwise); `context` is the markdown detail behind it,
+ * sent only when given on `add`, and on `edit` `undefined` keeps the stored
+ * context while `null` clears it — the same omit/null semantics
+ * `plan_update_record` already gives a plan record's context.
+ *
  * No answer action, for the reason `issueSolution` gives.
  */
 export async function issueProblem(client, args) {
@@ -573,6 +583,8 @@ export async function issueProblem(client, args) {
             return client.request({ method: "GET", path: `/${idEnc}/problems`, board });
         case "add": {
             const body = { statement: need.string(args.statement, "statement") };
+            if (args.context !== undefined)
+                body.context = args.context;
             if (args.solutions !== undefined)
                 body.solutions = args.solutions;
             const result = await client.request({ method: "POST", path: `/${idEnc}/problems`, body, board });
@@ -585,7 +597,7 @@ export async function issueProblem(client, args) {
             return client.request({
                 method: "PATCH",
                 path: `/${idEnc}/problems/${problemId}`,
-                body: { base_hash: baseHash, statement },
+                body: { base_hash: baseHash, statement, ...(args.context === undefined ? {} : { context: args.context }) },
                 board,
             });
         }
@@ -844,6 +856,7 @@ export const PLAN_FIELD_GROUPS = [
     "records:caveat",
     "architecture",
     "sessions",
+    "notes",
 ];
 /**
  * DX-2834 — the plan-status taxonomy, mirroring `PLAN_FIELD_GROUPS` just
@@ -1147,6 +1160,85 @@ export async function planDeleteRecord(client, args) {
         body: { content_hash: args.content_hash },
     });
 }
+/**
+ * Write a milestone note to a plan, via `POST /api/plans/:plan_id/notes`.
+ * TAKES AN EXPLICIT `plan_id`, unlike `plan_add_record`/`plan_add_architecture_section`
+ * — mirrors `plan_add_card`'s sibling `plan_remove_card`/`plan_rename`: a
+ * dispatched worker has no plan connection when it finishes a card, and a
+ * card can sit on several plans, so the writer names which one the note
+ * belongs to. A note is a MILESTONE, not a log — write one when a card (or a
+ * related group of cards) finishes, an important decision lands, or a
+ * goal/rule/caveat/architecture section changes meaningfully; routine step
+ * progress stays a card comment. 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 id, 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 server-side from your identity,
+ * never sent by you. Unknown plan → 404. Returns the new note plus the
+ * plan's latest notes page.
+ */
+export async function planAddNote(client, args) {
+    return client.request({
+        method: "POST",
+        path: `/${args.plan_id}/notes`,
+        basePath: PLANS_BASE_PATH,
+        body: {
+            title: args.title,
+            body: args.body,
+            ...(args.card_ids === undefined ? {} : { card_ids: args.card_ids }),
+            ...(args.record_refs === undefined ? {} : { record_refs: args.record_refs }),
+            ...(args.section_ids === undefined ? {} : { section_ids: args.section_ids }),
+        },
+    });
+}
+/**
+ * Edit a plan note, via `PATCH /api/plans/:plan_id/notes/:note_id`.
+ * `content_hash` MUST be the note's `contentHash` from your last read; on a
+ * mismatch nothing is written and you get `{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 are all-or-nothing as a GROUP: omit all three to keep the stored
+ * link set untouched; send ANY one of them to REPLACE THE WHOLE SET (never a
+ * per-link add/remove — the set is the unit of change). The hash covers
+ * title, body AND the link set, so a stale read of any of the three is
+ * refused. 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.
+ */
+export async function planUpdateNote(client, args) {
+    return client.request({
+        method: "PATCH",
+        path: `/${args.plan_id}/notes/${args.note_id}`,
+        basePath: PLANS_BASE_PATH,
+        body: {
+            content_hash: args.content_hash,
+            ...(args.title === undefined ? {} : { title: args.title }),
+            ...(args.body === undefined ? {} : { body: args.body }),
+            ...(args.card_ids === undefined ? {} : { card_ids: args.card_ids }),
+            ...(args.record_refs === undefined ? {} : { record_refs: args.record_refs }),
+            ...(args.section_ids === undefined ? {} : { section_ids: args.section_ids }),
+        },
+    });
+}
+/**
+ * Soft-delete a plan note, via `DELETE /api/plans/:plan_id/notes/:note_id`.
+ * `content_hash` MUST be the note's `contentHash` from your last read; a
+ * stale hash deletes nothing and returns the same `{error:
+ * "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}`
+ * 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.
+ */
+export async function planDeleteNote(client, args) {
+    return client.request({
+        method: "DELETE",
+        path: `/${args.plan_id}/notes/${args.note_id}`,
+        basePath: PLANS_BASE_PATH,
+        body: { content_hash: args.content_hash },
+    });
+}
 // ---------------- failure_category_list / _create / _update (DX-2792) ----------------
 /**
  * DX-2792 (Failure evaluation 3/4) — wraps `src/dashboard/failure-categories-routes.ts`,

package/dist/index.js

@@ -94,13 +94,14 @@
  */
 import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
+import { PLAN_STATE_SUBCOMMAND, runPlanStateCommand } from "./plan-state.js";
 import { resolveDeclaredCredential } from "./credential.js";
 import { recordSessionConnectionAfterConnect } from "./session-connection.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
-import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -503,12 +504,13 @@ server.tool("issue_triage", "Record a triage confidence score via POST /api/issu
     ...boardField,
 }, async (args) => jsonResult(await issueTriage(client, args)));
 // ---------------- issue_comment ----------------
-server.tool("issue_comment", "Comment CRUD via /api/issues/:id/comments[/:cid]. action=add → POST {text, metadata?} (server stamps author from bearer + auto-incrementing ordinal); action=edit → PATCH /:cid {text}; action=delete → DELETE /:cid (soft-delete, audit trail preserved — comments are NEVER hard-deleted). Client-supplied author is IGNORED (server-stamped to prevent impersonation). `metadata` (DX-2157, action=add only) is an OPTIONAL opaque JSON object a calling app attaches to the comment — e.g. a generated `{sql, explanation}` packet its own UI renders specially. danxbot stores + returns it verbatim and enforces NO shape on its contents; omit for a plain markdown-only comment (unaffected either way).", {
+server.tool("issue_comment", "Comment CRUD via /api/issues/:id/comments[/:cid]. action=add → POST {text, metadata?, problem_id?} (server stamps author from bearer + auto-incrementing ordinal); action=edit → PATCH /:cid {text}; action=delete → DELETE /:cid (soft-delete, audit trail preserved — comments are NEVER hard-deleted). Client-supplied author is IGNORED (server-stamped to prevent impersonation). `metadata` (DX-2157, action=add only) is an OPTIONAL opaque JSON object a calling app attaches to the comment — e.g. a generated `{sql, explanation}` packet its own UI renders specially. danxbot stores + returns it verbatim and enforces NO shape on its contents; omit for a plain markdown-only comment (unaffected either way). `problem_id` (DX-2906, action=add only) OPTIONALLY threads the comment as a follow-up question under one of this SAME card's problems (from `issue_problem` list/add) WITHOUT answering it — commenting never changes open_problem_count, blocked, or records a decision; use issue_problem's answer route for that. An unknown id, another card's id, or a removed problem's id all 404 naming the problem id — an ANSWERED (but not removed) problem still accepts a follow-up comment, since the thread continues after a decision.", {
     id: z.string().min(1),
     action: z.enum(["add", "edit", "delete"]),
     comment_id: z.number().int().positive().optional(),
     text: z.string().min(1).optional(),
     metadata: z.record(z.unknown()).optional(),
+    problem_id: z.number().int().positive().optional().describe("action=add only — thread this comment as a follow-up under a LIVE problem of this same card, without answering it"),
     ...boardField,
 }, async (args) => jsonResult(await issueComment(client, args)));
 // ---------------- issue_checklist ----------------
@@ -546,12 +548,17 @@ const SOLUTION_FIELDS = {
     con: z.string().optional(),
     recommended: z.boolean().optional(),
 };
-server.tool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: one statement the operator must resolve (a question, or a flaw in the plan), each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — there is no separate flag to set, adding a problem IS putting the card in front of a human. list → live problems in order, each {id, statement, content_hash, open, solutions[], decisions[]}; add {statement, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count; edit :pid {base_hash, statement}; remove :pid {base_hash} — always allowed, even as the card's last open problem (DX-2830: removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard.", {
+server.tool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: one statement the operator must resolve (a question, or a flaw in the plan), each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — there is no separate flag to set, adding a problem IS putting the card in front of a human. list → live problems in order, each {id, statement, context, content_hash, open, solutions[], decisions[]}; add {statement, context?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count; edit :pid {base_hash, statement, context?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (DX-2830: removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard. DX-2942 — `statement` is capped at 100 characters (a 400 names the actual length otherwise): write it as ONE plain question, and put any investigation detail in `context` (markdown, no cap) instead of running it on. Good: statement \"Which cache should we use?\", context \"Redis fits the read-heavy path; see benchmark in #123. Memcached is simpler ops but no persistence.\" Bad: statement \"We looked at Redis vs Memcached, ran benchmarks showing Redis 3x faster on reads, but Memcached has simpler ops and we're not sure persistence matters here since the cache is fully rebuildable from Postgres...\" (too long, refused — move it to context).", {
     id: z.string().min(1),
     action: z.enum(["list", "add", "edit", "remove"]),
     problem_id: z.number().int().positive().optional().describe("edit/remove"),
     base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove"),
-    statement: z.string().min(1).optional().describe("add/edit"),
+    statement: z.string().min(1).optional().describe("add/edit; ONE plain question, at most 100 characters"),
+    context: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("add/edit; markdown detail behind statement — file:line refs, code excerpts, root-cause writeups. add: sent only when given (null/omit means none). edit: omit to keep the stored context, null to clear it."),
     solutions: z
         .array(z.object({ title: z.string().min(1), ...SOLUTION_FIELDS }))
         .optional()
@@ -652,7 +659,7 @@ server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retr
 // route's MAX_DECODED_BYTES (src/issues/write/attachments.ts). This package is
 // a separate published artifact and cannot import that constant, so the number
 // is restated here as prose — keep the two in sync if the backend ceiling moves.
-server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/issues/:id/attachments. Pass `id` (the card) and `file_path` (an ABSOLUTE path to a file on the dispatch's shared filesystem — e.g. a screenshot, exported CSV, or diagram you wrote). This MCP server reads the bytes, infers the MIME type from the extension, and uploads through the dashboard, which: stores the bytes in S3, inserts ONE danxbot-origin issue_attachments row, and auto-mirrors the file to the card's linked Trello card AND its Slack card-view thread (DX-1122 outbound projection) — no extra step needed. Board-scoped; see `board`. Fail-loud: a relative/empty path is rejected at the MCP boundary, and a missing/unreadable file throws BEFORE any upload (no partial S3 object, no row). 25 MB decoded ceiling (413). Returns the hydrated issue plus the new attachment id.", {
+server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/issues/:id/attachments. Pass `id` (the card) and `file_path` (an ABSOLUTE path to a file on the dispatch's shared filesystem — e.g. a screenshot, exported CSV, or diagram you wrote). This MCP server reads the bytes, infers the MIME type from the extension, and uploads through the dashboard, which: stores the bytes in S3, inserts ONE danxbot-origin issue_attachments row, and auto-mirrors the file to the card's linked Trello card AND its Slack card-view thread (DX-1122 outbound projection) — no extra step needed. Board-scoped; see `board`. Fail-loud: a relative/empty path is rejected at the MCP boundary, and a missing/unreadable file throws BEFORE any upload (no partial S3 object, no row). 25 MB decoded ceiling (413). Returns `{issue, attachment_id, s3_key}` — find the new attachment in `issue.attachments` by `attachment_id` to read its public, long-lived `url` (no expiry — never a presigned link). EMBEDDING: that `url` is not only a card-level attachment — paste it into ANY markdown-bearing field (a problem's `statement`/`context` via `issue_problem`, a comment via `issue_comment`, a plan record's `context`, a solution's `body`) as `![description](url)` and the dashboard renders it inline, capped to a compact thumbnail with click-to-enlarge. Use this whenever a screenshot would let a human judge something faster than prose — a UI bug, a before/after, a broken layout. Example: after uploading and reading the attachment's url (say `https://dx-issues.s3.us-east-1.amazonaws.com/abc123.png`), call `issue_comment` with text `Before the fix, the sidebar overlapped the header:\\n\\n![sidebar overlapping header](https://dx-issues.s3.us-east-1.amazonaws.com/abc123.png)`.", {
     id: z.string().min(1),
     file_path: z
         .string()
@@ -792,6 +799,32 @@ server.tool("plan_delete_record", 'Soft-delete a goal/rule/caveat of your connec
     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.", {
+    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."),
+    card_ids: z.array(z.string().min(1)).optional().describe("Card ids this note concerns, e.g. `[\"DX-2894\"]`."),
+    record_refs: z
+        .array(z.string().min(1))
+        .optional()
+        .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.', {
+    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."),
+    title: z.string().min(1).optional().describe("New title, at most 60 characters. Omit to keep the stored title."),
+    body: z.string().min(1).optional().describe("New wrap-up, at most 250 characters. Omit to keep the stored body."),
+    card_ids: z.array(z.string().min(1)).optional().describe("REPLACES the whole link set when sent (with record_refs/section_ids)."),
+    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.', {
+    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.", {
     card_id: z.string().min(1).describe("An existing card id, e.g. `DX-2683`."),
 }, async (args) => jsonResult(await planAddCard(client, args)));
@@ -881,16 +914,25 @@ async function main() {
 // symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
 // 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 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.
+// `bridge` and `plan-state` are the two subcommands. `bridge` is the session
+// event stream client the danxbot 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).
+//
+// `plan-state` (DX-2921) is the ONE-SHOT client of
+// `GET /api/plan-sessions/me/turn-state`, run by the DX-2888 plugin's
+// turn-start / turn-end hooks — see `plan-state.ts`'s own doc comment for the
+// full contract. It ALWAYS exits 0 (success or failure alike: the hook must
+// stay silent), so even an unexpected rejection here is caught and reported
+// the same `{ok:false, reason}` way rather than propagating a non-zero exit
+// or an uncaught stack trace into the hook.
+//
+// Any OTHER argument is refused rather than ignored, so a typo cannot
+// silently start an MCP server on stdio where a subcommand was meant to run.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
     const [subcommand, ...rest] = process.argv.slice(2);
     if (subcommand === BRIDGE_SUBCOMMAND) {
@@ -899,8 +941,16 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(1);
         });
     }
+    else if (subcommand === PLAN_STATE_SUBCOMMAND) {
+        runPlanStateCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] plan-state fatal: ${err.message}`);
+            process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
+            process.exit(0);
+        });
+    }
     else if (subcommand !== undefined) {
-        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is "${BRIDGE_SUBCOMMAND}")`);
+        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
+            `"${BRIDGE_SUBCOMMAND}" and "${PLAN_STATE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/json-body.js

@@ -0,0 +1,23 @@
+/**
+ * DX-2920 — the ONE place that reads a JSON body's top-level `.error` string.
+ *
+ * WHY THIS EXISTS. `bridge.ts` (classifying a mint refusal) and `listen.ts`
+ * (classifying a stream admission refusal) both need to answer "what error
+ * code did this JSON body carry", and before this card each answered it a
+ * different way: `bridge.ts` parsed the body directly, `listen.ts` never
+ * looked past a flattened, human-readable detail string at all — a caller
+ * that wanted to react to a SPECIFIC refusal (the admission-time 409 the
+ * mint route also uses) had to regex-scrape that flattened string back apart,
+ * a second, fragile source of truth for the same fact. This module is generic
+ * — it knows nothing about "session_not_connected" or "issuer_cannot_read_plan_boards",
+ * only that a JSON object may carry a top-level string field named `error` —
+ * so it can live in BOTH the domain-aware `bridge.ts` and the deliberately
+ * generic `listen.ts` (whose own docblock states it carries no domain
+ * knowledge of the dashboard's specific error shapes) without either one
+ * importing the other.
+ */
+export function errorCodeOf(body) {
+    return typeof body === "object" && body !== null && typeof body.error === "string"
+        ? body.error
+        : null;
+}