@thehammer/danx-dashboard-mcp 0.1.51 → 0.1.53

package/README.md

@@ -23,15 +23,30 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 |---|---|---|
 | `issue_list` | `GET /api/issues` | filters: `type`, `parent_id` (null → root-only), `dispatchable_derived`, `assigned_agent`, `include_closed`, `limit`, `offset` |
 | `issue_get` | `GET /api/issues/:id` | Returns hydrated card + ancestor chain |
-| `issue_create` | `POST /api/issues` | Epic REQUIRES non-empty `phase_children[]` (atomic insert) |
-| `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `description`, `ac`, `checklists`, `effort_level`, `parent_id`, `priority`, `list_id`); semantic keys refused with 400 + pointer to dedicated handler. `priority` (DX-1532) takes a tier word (`low`/`high`/…) or a number in `[0,6)` — the ONLY way to set the numeric column the Trello label + dashboard badge read; never set priority via description prose |
-| `issue_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen |
+| `issue_create` | `POST /api/issues` | Epic REQUIRES non-empty `phase_children[]` (atomic insert). `title` = short domain-naming label; `summary` = 1–3 plain-language sentences, always shown; `description` = the collapsed "Context" body. Root and every phase child take their own `summary` |
+| `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `summary` (null clears), `description`, `ac`, `checklists`, `effort_level`, `parent_id`, `priority`, `list_id`); semantic keys refused with 400 + pointer to dedicated handler. `priority` (DX-1532) takes a tier word (`low`/`high`/…) or a number in `[0,6)` — the ONLY way to set the numeric column the Trello label + dashboard badge read; never set priority via description prose |
+| `issue_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen. A successful `block` also returns `solutions_reminder: {solution_count, instruction}` |
+| `issue_solution` | `GET/POST/PATCH/DELETE /api/issues/:id/solutions[/:sid]` | Actions list / add / edit / remove. Edit + remove are hash-guarded (`base_hash`, 409 `stale_solution` with the current row); at most one live `recommended`; a chosen option cannot be edited. No answer action — the operator answers in the dashboard |
 | `issue_triage` | `POST /api/issues/:id/triage` | Send `{confidence, reason}` — an integer 0-5 score; the server computes the verdict (approve/cancel/keep/defer) against the board's configured thresholds (DX-2086). `keep`/`defer` now block the card. None of these are a cross-card ordering gate; use `issue_dependency` to sequence cards |
 | `issue_comment` | `POST/PATCH/DELETE /api/issues/:id/comments[/:cid]` | Author server-stamped, soft-delete preserved |
 | `issue_dependency` | `POST/DELETE /api/issues/:id/dependencies[/:did]` | `depends_on` cycle-checked; remove hardcodes `reason: "recorded_in_error"`. The only mechanism the dispatch picker enforces to sequence one card after another — status alone is not a substitute |
-| `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set replaces step rows atomically; clear soft-deletes them |
+| `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set replaces step rows atomically; clear soft-deletes them. A successful set also returns `solutions_reminder: {solution_count, instruction}` |
 | `issue_retro` | `PUT /api/issues/:id/retro` | Requires terminal card; replace semantics |
 
+## `listen` — a working session's event listener
+
+`plan_connect` connects the session to a plan AND returns `listener: {command, persistent: true, instruction}`. The agent arms `command` with Claude Code's Monitor tool (`persistent: true`); every line the command prints becomes a notification that wakes the session.
+
+```bash
+npx -y @thehammer/danx-dashboard-mcp@<version> listen --stream <dashboard>/api/plan-sessions/stream --ticket <ticket> --lease-ms <ms>
+```
+
+All three flags come from the dashboard's own ticket response; `plan_connect` assembles the command, so never build it by hand.
+
+- **Credential.** `--ticket` is a listener ticket minted by `POST /api/plan-sessions/me/stream-ticket` for THIS session only. It authorizes reading that one session's event stream and nothing else, and stops the moment the credential that minted it is revoked — the MCP server's own token never appears in the command. Minting a new one (calling `plan_connect` again) ends the previous listener; a second connection with the same ticket replaces the first.
+- **Output.** Exactly one line per event on the connected plan's cards — `[DX-8 "Title" repo:board] newms87 answered: chose "Pause E2E" — note: "only this week"`, `… commented: "…"`, `… set requires_human: "…"`, `… cleared requires_human`, `… blocked the card: "…"`, `… unblocked the card`. Nothing for keep-alives or reconnects. The session's own writes are never echoed back to it. An event it cannot read still produces one `could not read event` line.
+- **Reconnect.** A read-idle timeout (three missed keep-alives) turns a silently dead connection into a drop. Capped exponential backoff (1s → 30s) that resets only after a healthy connection, with `Last-Event-ID`, so a dashboard restart replays what was missed and nothing is printed twice. One final `[danx-dashboard listen] …` line and exit when the ticket is refused or revoked (exit 1), when a newer listener takes over (exit 0), or after `--lease-ms` without a healthy connection (exit 1) — the remedy is always `plan_connect` again.
+
 ## Build + test
 
 ```bash

package/dist/handlers.js

@@ -158,6 +158,8 @@ export async function issueCreate(client, args, defaultBoard) {
         title: args.title,
         description: args.description,
     };
+    if (args.summary !== undefined)
+        body.summary = args.summary;
     if (args.parent_id !== undefined)
         body.parent_id = args.parent_id;
     if (args.ac !== undefined)
@@ -205,12 +207,63 @@ export async function issueEdit(client, args) {
 }
 export async function issueTransition(client, args) {
     const { id, board, ...body } = args;
-    return client.request({
+    const result = await client.request({
         method: "POST",
         path: `/${encodeURIComponent(id)}/transition`,
         body,
         board,
     });
+    return args.action === "block" ? withSolutionsReminder(client, id, board, result) : result;
+}
+/**
+ * Attach the solutions reminder to a SUCCESSFUL gating write.
+ *
+ * ENFORCED BY FEEDBACK, NOT BY REFUSAL. The server never rejects a block or a
+ * requires-human hold for lacking solutions: some holds legitimately have no
+ * options to list (a credential only the operator can supply), and a refusal
+ * there would push the agent into inventing solutions to get past the gate.
+ * What the operator needs is that an agent which CAN lay out options always
+ * does — so the reminder rides the success response, where it is read at the
+ * exact moment the agent is deciding whether it is done.
+ *
+ * The gating write's own envelope is returned untouched beside it. A refused
+ * write gets no reminder (there is no stop to remind about). A failure READING
+ * the solutions is reported inside the reminder rather than thrown: the gating
+ * write already succeeded, and throwing would tell the agent its block failed
+ * when it did not — the failure is surfaced, never swallowed.
+ */
+export async function withSolutionsReminder(client, id, board, result) {
+    if (!result.ok)
+        return result;
+    const nextStep = `issue_solution({id: "${id}", action: "add", title, body, pro, con})`;
+    let listed;
+    try {
+        listed = await client.request({
+            method: "GET",
+            path: `/${encodeURIComponent(id)}/solutions`,
+            board,
+        });
+    }
+    catch (err) {
+        return { ...result, solutions_reminder: unreadableReminder(id, err instanceof Error ? err.message : String(err)) };
+    }
+    // `body` is the server's JSON verbatim — `null` is valid JSON, so read it null-safely;
+    // a throw here would land OUTSIDE the try above and misreport the successful write.
+    const solutions = listed.ok ? listed.body?.solutions : undefined;
+    if (!Array.isArray(solutions)) {
+        return { ...result, solutions_reminder: unreadableReminder(id, `HTTP ${listed.status}`) };
+    }
+    const count = solutions.length;
+    const instruction = count === 0
+        ? `NO SOLUTIONS ARE LISTED ON ${id}. Before you stop, add EVERY viable solution with ${nextStep}, and mark the one you recommend with recommended: true. The operator answers a stopped card by picking a listed solution — with none listed, they have to reconstruct the options from the description.`
+        : `${count} solution${count === 1 ? " is" : "s are"} listed on ${id}. Before you stop, confirm EVERY viable solution is on the card and add any that are missing with ${nextStep}. The operator can only pick from what is listed.`;
+    return { ...result, solutions_reminder: { solution_count: count, instruction } };
+}
+function unreadableReminder(id, detail) {
+    return {
+        solution_count: null,
+        instruction: `Could not read the solutions on ${id} (${detail}). Check with issue_solution({id: "${id}", action: "list"}) and make sure EVERY viable solution is listed before you stop.`,
+    };
 }
 export async function issueTriage(client, args) {
     const { id, board, ...body } = args;
@@ -400,6 +453,61 @@ export async function issueChecklist(client, args) {
         }
     }
 }
+/**
+ * A card's candidate solutions via `/api/issues/:id/solutions[/:sid]`,
+ * action-dispatched like `issue_checklist`. A missing required arg for the
+ * chosen action throws at this boundary (no round-trip); the server's refusal
+ * envelopes (`stale_solution` with the current row, a second recommendation,
+ * editing a chosen option) pass through verbatim.
+ *
+ * There is deliberately NO answer action. Answering a card releases the human
+ * gates on it — an agent that could answer its own question could release the
+ * very stop it set to wait for a human. The operator answers in the dashboard.
+ */
+export async function issueSolution(client, args) {
+    const base = `/${encodeURIComponent(args.id)}/solutions`;
+    const board = args.board;
+    const content = {};
+    for (const key of ["title", "body", "pro", "con", "recommended"]) {
+        if (args[key] !== undefined)
+            content[key] = args[key];
+    }
+    switch (args.action) {
+        case "list":
+            return client.request({ method: "GET", path: base, board });
+        case "add":
+            if (typeof args.title !== "string") {
+                throw new Error("issue_solution action=add requires title");
+            }
+            return client.request({ method: "POST", path: base, body: content, board });
+        case "edit":
+            if (args.solution_id === undefined) {
+                throw new Error("issue_solution action=edit requires solution_id");
+            }
+            if (typeof args.base_hash !== "string") {
+                throw new Error("issue_solution action=edit requires base_hash");
+            }
+            return client.request({
+                method: "PATCH",
+                path: `${base}/${args.solution_id}`,
+                body: { base_hash: args.base_hash, ...content },
+                board,
+            });
+        case "remove":
+            if (args.solution_id === undefined) {
+                throw new Error("issue_solution action=remove requires solution_id");
+            }
+            if (typeof args.base_hash !== "string") {
+                throw new Error("issue_solution action=remove requires base_hash");
+            }
+            return client.request({
+                method: "DELETE",
+                path: `${base}/${args.solution_id}`,
+                body: { base_hash: args.base_hash },
+                board,
+            });
+    }
+}
 export async function issueRequiresHuman(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
@@ -410,12 +518,13 @@ export async function issueRequiresHuman(client, args) {
         if (!Array.isArray(args.steps)) {
             throw new Error("issue_requires_human set=true requires steps[]");
         }
-        return client.request({
+        const result = await client.request({
             method: "POST",
             path: `/${idEnc}/requires-human`,
             body: { reason: args.reason, steps: args.steps },
             board,
         });
+        return withSolutionsReminder(client, args.id, board, result);
     }
     return client.request({
         method: "DELETE",
@@ -612,6 +721,39 @@ export async function planGet(client, args = {}) {
         basePath: PLANS_BASE_PATH,
     });
 }
+function readIssuedTicket(body) {
+    const b = body;
+    return b !== null &&
+        typeof b.ticket === "string" &&
+        b.ticket !== "" &&
+        typeof b.streamPath === "string" &&
+        typeof b.leaseMs === "number"
+        ? { ticket: b.ticket, streamPath: b.streamPath, leaseMs: b.leaseMs }
+        : null;
+}
+/**
+ * The exact shell command a Monitor runs. The ticket is the only credential in
+ * it; the stream URL and lease come from the dashboard's own ticket response, so
+ * the listener carries no copy of either.
+ */
+export function listenCommand(target, issued) {
+    const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+    const streamUrl = `${target.baseUrl.replace(/\/+$/, "")}${issued.streamPath}`;
+    return (`npx -y ${target.packageSpec} listen --stream ${quote(streamUrl)} ` +
+        `--ticket ${quote(issued.ticket)} --lease-ms ${issued.leaseMs}`);
+}
+function listenerNotArmed(status, connected, ticketResponse) {
+    return {
+        ok: false,
+        status,
+        body: {
+            error: "listener_not_armed",
+            message: "This session IS now connected to the plan, but no listener ticket was issued, so no listener can be armed and this plan's events will NOT reach this session. Resolve the problem below and call plan_connect again.",
+            connected,
+            ticket_response: ticketResponse,
+        },
+    };
+}
 /**
  * Connect THIS session to a plan — the same write the operator's Connect
  * action performs, reaching the same server-side code path. `me` in the URL
@@ -620,14 +762,51 @@ export async function planGet(client, args = {}) {
  *
  * A session already on another plan is MOVED, and the response says which
  * plan it left (`movedFrom`).
+ *
+ * THEN IT ARMS THE LISTENER. A connected session must hear about its plan's
+ * cards the moment something happens, so the reply carries the exact Monitor
+ * command to run. The command holds a stream TICKET this server mints for the
+ * session — never this server's own long-lived token, which must not appear in
+ * a command line. Minting a ticket replaces the session's previous one, so
+ * re-connecting (after a restart, or to re-arm) leaves exactly one listener.
+ *
+ * A refused ticket is NOT reported as a successful connect: the binding did
+ * happen, but a session that believes it is listening when it is not would miss
+ * the operator's answer silently, so the whole call fails loud and says both.
  */
-export async function planConnect(client, args) {
-    return client.request({
+export async function planConnect(client, args, listener) {
+    const connected = await client.request({
         method: "POST",
         path: "/me/plan",
         basePath: PLAN_SESSIONS_BASE_PATH,
         body: { plan_id: args.plan_id },
     });
+    if (!connected.ok)
+        return connected;
+    let issued;
+    try {
+        issued = await client.request({
+            method: "POST",
+            path: "/me/stream-ticket",
+            basePath: PLAN_SESSIONS_BASE_PATH,
+        });
+    }
+    catch (err) {
+        // The binding already happened; a thrown ticket request must not erase that fact.
+        return listenerNotArmed(502, connected.body, { error: err instanceof Error ? err.message : String(err) });
+    }
+    const ticket = issued.ok ? readIssuedTicket(issued.body) : null;
+    if (ticket === null) {
+        return listenerNotArmed(issued.ok ? 502 : issued.status, connected.body, issued.body);
+    }
+    return {
+        ...connected,
+        listener: {
+            command: listenCommand(listener, ticket),
+            persistent: true,
+            instruction: "Arm this now with the Monitor tool (command above, persistent: true). Every comment, answer, requires_human change and block/unblock on this plan's cards will then arrive as a notification within seconds — do not poll for them. If the Monitor prints that it gave up or was ended, call plan_connect again and arm the new command.",
+        },
+    };
 }
 /** Add a goal, rule or caveat to the connected plan. */
 export async function planAddRecord(client, args) {

package/dist/index.js

@@ -19,6 +19,7 @@
  *   - issue_triage           POST   /api/issues/:id/triage
  *   - issue_comment          POST/PATCH/DELETE /api/issues/:id/comments[/:cid]
  *   - issue_checklist        POST/PATCH/DELETE /api/issues/:id/checklists[/:cid[/items[/:iid]]]
+ *   - issue_solution         GET/POST/PATCH/DELETE /api/issues/:id/solutions[/:sid]
  *   - issue_dependency       POST/DELETE /api/issues/:id/dependencies[/:did]
  *   - issue_requires_human   POST/DELETE /api/issues/:id/requires-human
  *   - issue_quality_gate     POST   /api/issues/:id/quality-gates/:gate
@@ -73,13 +74,15 @@
  * agent reads `body.error` + structured fields to decide next action.
  * 5xx and network failures throw — never silently swallowed.
  */
+import { createRequire } from "node:module";
 import { basename } from "node:path";
 import { isEntrypointModule } from "./entrypoint.js";
+import { LISTEN_SUBCOMMAND, runListenCommand } from "./listen.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, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddCard, planAddRecord, planConnect, planCreate, planDeleteRecord, planGet, planGetRecord, planList, planSetArchitecture, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddCard, planAddRecord, planConnect, planCreate, planDeleteRecord, planGet, planGetRecord, planList, planSetArchitecture, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -160,6 +163,16 @@ function readSessionConfig() {
     const fallback = cwdName === "" ? `session ${id.slice(0, 8)}` : cwdName;
     return { id, title: readEnvOptional("DANX_SESSION_TITLE") ?? fallback };
 }
+/**
+ * This build's own npm spec. `plan_connect` hands out a `listen` command pinned to
+ * it, so the listener that runs is always the one written for the stream this
+ * server's dashboard speaks — never whatever `npx` happens to have cached.
+ * `package.json` sits one level above both `src/` (tsx) and `dist/` (the bin).
+ */
+const PACKAGE_SPEC = (() => {
+    const pkg = createRequire(import.meta.url)("../package.json");
+    return `${pkg.name}@${pkg.version}`;
+})();
 export const server = new McpServer({
     name: "danx-dashboard-mcp",
     version: "0.1.0",
@@ -195,6 +208,7 @@ const NON_EPIC_TYPES = ["Bug", "Feature", "Story", "Chore", "Task"];
 // server 400, not silently.
 const LIST_FIELD_GROUPS = [
     "description",
+    "solutions",
     "ac",
     "comments",
     "retro",
@@ -255,6 +269,12 @@ const boardField = {
         .optional()
         .describe("Target another board by its qualified id `<repo>:<slug>` (e.g. `platform:the-supply-operations-hub`); omit to use this dispatch's board. Unknown board → 404."),
 };
+// The three prose fields of a card, each with ONE job. Shared by issue_create
+// (root + phase children) and issue_edit so the guidance an agent reads is
+// identical wherever it writes the field.
+const TITLE_DESCRIBE = 'Short, specific label that names the domain, so a reader recognises the card without opening it (e.g. "Guest checkout rejects carts holding a gift card"). Never a generic phrase like "2 real decisions needed", "Fix bug" or "Follow-up".';
+const SUMMARY_DESCRIBE = "1–3 plain-language sentences — no markdown, no jargon — for someone who has never seen this codebase: what the card is about and why it matters. Always shown, never collapsed. It must stand on its own: not a second title, not a teaser for the description.";
+const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, technical detail. Long and markdown is normal; UIs collapse it by default. Candidate answers to the question a card is stopped on do NOT go here — list each one with issue_solution.';
 // ---------------- issue_list ----------------
 server.tool("issue_list", "List issues for the dispatch's board by default via GET /api/issues. Board-scoped; defaults to the dispatch's board. Pass `board` (a qualified id `<repo>:<slug>`) to list another board instead (unknown board → 404). Nested envelope (DX-935 / DX-937 — hard-cut, no flat params): `filter` — the OLD flat filters, now nested (type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, and `q` — free-text over id+title+description, the former standalone `q` param now lives at `filter.q`). `fields` — opt-in named field-GROUPS (description, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort); THE DEFAULT RESPONSE (no `fields`) IS MINIMAL — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent), zero joins. Point any heavy read (full description, comments[], retro, ac items, dependency edges, triage history, quality-gate rows, children ids) at the matching `fields` entry rather than assuming it's already on the row. `sort` — ordered [{column, order}] (id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at); absent → default order (priority desc, repo_name asc) with an always-appended numeric-id tiebreaker (DX-10 follows DX-9). `limit`/`offset` — optional paging (no cap by default). Use issue_get for a single fully-detailed card.", {
     filter: z
@@ -274,26 +294,27 @@ server.tool("issue_list", "List issues for the dispatch's board by default via G
     fields: z
         .array(z.enum(LIST_FIELD_GROUPS))
         .optional()
-        .describe("Opt-in field-GROUPS to add to the minimal default row: description, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort. Absent/empty = minimal scalars only — no joins."),
+        .describe("Opt-in field-GROUPS to add to the minimal default row: description (description + summary), solutions (solutions_count), ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort. Absent/empty = minimal scalars only — no joins."),
     sort: sortField,
     limit: z.number().int().positive().max(1000).optional(),
     offset: z.number().int().nonnegative().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
-server.tool("issue_get", "Fetch a single issue via GET /api/issues/:id. Board-scoped; defaults to the dispatch's board. Issue ids are globally unique, so this resolves from any dispatch regardless of `board`. DEFAULT RESPONSE IS MINIMAL (DX-935 / DX-937) — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent); no joined collections. Pass `fields` to opt into named field-GROUPS: description (full description body), ac (acceptance-criteria + checklists model), comments (comments[]), retro (retro good/bad/action_items/commits), dependencies (waiting_on/conflict_on/blocked gate state), triage (triage history + ICE), requires_human (the requires_human gate + steps), assignment (dispatch/assigned_agent/lifecycle timestamps), quality_gates (DX-1177 — one row per registered gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not yet `pass` pre-empts the work dispatch, and `issue_transition complete` refuses while a required POST gate row != pass), children (child id list + rollups), mirrors (external mirror sync state), code_review_items (code-review findings). Point any heavy read at the matching `fields` entry rather than assuming it's already on the row. 404 envelope on unknown id.", {
+server.tool("issue_get", "Fetch a single issue via GET /api/issues/:id. Board-scoped; defaults to the dispatch's board. Issue ids are globally unique, so this resolves from any dispatch regardless of `board`. DEFAULT RESPONSE IS MINIMAL (DX-935 / DX-937) — only cheap scalar columns (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent); no joined collections. Pass `fields` to opt into named field-GROUPS: description (full description body + the plain-language summary), solutions (the card's live candidate solutions, each with its content_hash, + every operator answer in decisions[]), ac (acceptance-criteria + checklists model), comments (comments[]), retro (retro good/bad/action_items/commits), dependencies (waiting_on/conflict_on/blocked gate state), triage (triage history + ICE), requires_human (the requires_human gate + steps), assignment (dispatch/assigned_agent/lifecycle timestamps), quality_gates (DX-1177 — one row per registered gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not yet `pass` pre-empts the work dispatch, and `issue_transition complete` refuses while a required POST gate row != pass), children (child id list + rollups), mirrors (external mirror sync state), code_review_items (code-review findings). Point any heavy read at the matching `fields` entry rather than assuming it's already on the row. 404 envelope on unknown id.", {
     id: z.string().min(1),
     fields: z
         .array(z.enum(GET_FIELD_GROUPS))
         .optional()
-        .describe("Opt-in field-GROUPS to add to the minimal default row: description, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, mirrors, code_review_items. Absent/empty = minimal scalars only."),
+        .describe("Opt-in field-GROUPS to add to the minimal default row: description, solutions, ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, mirrors, code_review_items. Absent/empty = minimal scalars only."),
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
 server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-scoped; defaults to the dispatch\'s board. Pass `board` (a qualified id `<repo>:<slug>`) to create the card on another board (forwarded into body.board + ?board=; unknown board → 404). INVARIANT: type=Epic REQUIRES non-empty phase_children[] (epic-with-phases atomicity per DX-575) and the route atomically inserts the epic + every phase in ONE transaction. Non-Epic types REFUSE phase_children[] with 400. Status defaults to Review (no lifecycle timestamps stamped on create). parent_id optional. ac items take {title}; phase children inherit the new epic\'s id as parent_id. Optional list_id PLACES the card directly into a column in ONE call. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, emoji-tolerant — e.g. a queue name like "⚙️ Fulfillment Queue" or just "Fulfillment Queue") — the server resolves a name to its id.** The card lands DIRECTLY in that column with the matching lifecycle stamped automatically — a `ready`-type queue → ToDo, a `completed` list → Done, etc. **You do NOT need a separate issue_transition(ready) + issue_edit(list_id) afterward — just pass the queue name here and the card is created already in that column.** Omit list_id for the default (Review). NOT valid on type=Epic (Epic status derives from children) → 400. Unknown name/id → 400. **gate_decisions is REQUIRED whenever the board has any OPTIONAL quality gate for the card\'s type** (DX-1594): supply one `{gate, enabled, note}` per board-optional gate. The create FAILS CLOSED — a missing decision returns 400 `{error, required_gate_decisions:[...]}` enumerating exactly which gates to answer, so just retry with a decision for each listed gate. `required`/`disabled` board gates take no decision; a board with no optional gates needs no gate_decisions at all. **ALWAYS pass `triage_enabled` explicitly** (root card AND every phase_children[] entry): decide per card whether it should enter the automatic triage/dispatch pipeline — `true` only when auto-triage is expected without further human review; absent → false, the card is NEVER auto-triaged (explicit-only, reverting DX-1928 — auto-created cards must never silently enter the dispatch pipeline).', {
     type: z.enum(ISSUE_TYPES),
-    title: z.string().min(1),
-    description: z.string(),
+    title: z.string().min(1).describe(TITLE_DESCRIBE),
+    summary: z.string().min(1).optional().describe(SUMMARY_DESCRIBE),
+    description: z.string().describe(DESCRIPTION_DESCRIBE),
     parent_id: z.string().nullable().optional(),
     ac: z.array(z.object({ title: z.string().min(1) })).optional(),
     effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
@@ -310,8 +331,13 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
     phase_children: z
         .array(z.object({
         type: z.enum(NON_EPIC_TYPES),
-        title: z.string().min(1),
-        description: z.string(),
+        title: z.string().min(1).describe(TITLE_DESCRIBE),
+        summary: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(`${SUMMARY_DESCRIBE} This child's OWN summary — never inherited from the root card.`),
+        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
@@ -336,10 +362,16 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
     ...boardField,
 }, async (args) => jsonResult(await issueCreate(client, args, config.board)));
 // ---------------- issue_edit ----------------
-server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues/:id/edit. ALLOWED keys: title, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type. ANY OTHER KEY (lifecycle timestamps, triage state, dependencies, retro, requires_human, blocked/dispatch gates) returns 400 with offending_keys[] and a pointer to the dedicated semantic handler — use issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro instead. TYPE (DX-2484): change the card\'s `type` via the `type` key — the route recomputes `dispatchable_derived` immediately when it changes. Changing type TO `Story`, `Bug`, or `Chore` makes the card eligible for autonomous pickup (subject to every other dispatch gate); changing it TO `Task` or a container (`Epic`/`Feature`) REMOVES that eligibility — a planning record or container is never dispatched, in ANY status. This is the way to promote a planning item into real work. PRIORITY (DX-1532): set card priority via the `priority` key — a tier WORD ("lowest"/"low"/"medium"/"high"/"very_high"/"critical", resolved to the tier midpoint) OR a raw number in [0,6). This is the ONLY way to change priority: the numeric `issues.priority` column is what the Trello priority label AND the dashboard badge read — editing a "Priority: <x>" line in the DESCRIPTION changes nothing downstream (a silent false-positive). To honor a "set priority" request, write `priority` here, do NOT edit description prose. CHECKLISTS (DX-1290, extended DX-2653): a card carries 0..N named checklists, each item ONE status `incomplete|failing|passing|cancelled|deferred` (terminal = passing|cancelled|deferred). `deferred` is the honest disposition for a criterion whose work is done but names a real-world/post-deploy check still outstanding — REQUIRES a non-empty `detail`; a criterion marked with the `📡` post-deploy-evidence prefix can never be `passing` at all (refused 409 at completion, resolve to `deferred` instead). `ac` is the 2-state CONVENIENCE onto the default "Acceptance Criteria" checklist (checked:true ↔ passing, false ↔ incomplete BY DEFAULT — pass `status` alongside `checked` to reach `cancelled`/`failing`/`deferred` instead) — each incoming item is DIFFED against that checklist\'s current live items (matched by the optional `check_item_id`, else by exact title) so an unchanged item keeps its id; only changed items are updated in place, new titles are inserted, and items missing from the array are removed. `checklists` is the GENERIC wholesale write path: it REPLACES every named checklist on the card with full status control (each `{name, items:[{label, detail?, status}]}`) — use it to author named checklists like "Feature Tests". Send EITHER `ac` OR `checklists`, NOT both (400). list_id (DX-1192 / DX-1200) PINS the card to a specific board list. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, e.g. a queue name like "⚙️ Fulfillment Queue") — the server resolves a name to its id.** Its type MUST match the card\'s CURRENT derived-status list-type (so to route a ToDo card into a `ready`-type queue, ready it first; mismatch / unknown name or id → 400); pass null to clear the pin (back to default-for-type).', {
+server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues/:id/edit. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type. ANY OTHER KEY (lifecycle timestamps, triage state, dependencies, retro, requires_human, blocked/dispatch gates) returns 400 with offending_keys[] and a pointer to the dedicated semantic handler — use issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro instead. TYPE (DX-2484): change the card\'s `type` via the `type` key — the route recomputes `dispatchable_derived` immediately when it changes. Changing type TO `Story`, `Bug`, or `Chore` makes the card eligible for autonomous pickup (subject to every other dispatch gate); changing it TO `Task` or a container (`Epic`/`Feature`) REMOVES that eligibility — a planning record or container is never dispatched, in ANY status. This is the way to promote a planning item into real work. PRIORITY (DX-1532): set card priority via the `priority` key — a tier WORD ("lowest"/"low"/"medium"/"high"/"very_high"/"critical", resolved to the tier midpoint) OR a raw number in [0,6). This is the ONLY way to change priority: the numeric `issues.priority` column is what the Trello priority label AND the dashboard badge read — editing a "Priority: <x>" line in the DESCRIPTION changes nothing downstream (a silent false-positive). To honor a "set priority" request, write `priority` here, do NOT edit description prose. CHECKLISTS (DX-1290, extended DX-2653): a card carries 0..N named checklists, each item ONE status `incomplete|failing|passing|cancelled|deferred` (terminal = passing|cancelled|deferred). `deferred` is the honest disposition for a criterion whose work is done but names a real-world/post-deploy check still outstanding — REQUIRES a non-empty `detail`; a criterion marked with the `📡` post-deploy-evidence prefix can never be `passing` at all (refused 409 at completion, resolve to `deferred` instead). `ac` is the 2-state CONVENIENCE onto the default "Acceptance Criteria" checklist (checked:true ↔ passing, false ↔ incomplete BY DEFAULT — pass `status` alongside `checked` to reach `cancelled`/`failing`/`deferred` instead) — each incoming item is DIFFED against that checklist\'s current live items (matched by the optional `check_item_id`, else by exact title) so an unchanged item keeps its id; only changed items are updated in place, new titles are inserted, and items missing from the array are removed. `checklists` is the GENERIC wholesale write path: it REPLACES every named checklist on the card with full status control (each `{name, items:[{label, detail?, status}]}`) — use it to author named checklists like "Feature Tests". Send EITHER `ac` OR `checklists`, NOT both (400). list_id (DX-1192 / DX-1200) PINS the card to a specific board list. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, e.g. a queue name like "⚙️ Fulfillment Queue") — the server resolves a name to its id.** Its type MUST match the card\'s CURRENT derived-status list-type (so to route a ToDo card into a `ready`-type queue, ready it first; mismatch / unknown name or id → 400); pass null to clear the pin (back to default-for-type).', {
     id: z.string().min(1),
-    title: z.string().min(1).optional(),
-    description: z.string().optional(),
+    title: z.string().min(1).optional().describe(TITLE_DESCRIBE),
+    summary: z
+        .string()
+        .min(1)
+        .nullable()
+        .optional()
+        .describe(`${SUMMARY_DESCRIBE} Pass null to clear it.`),
+    description: z.string().optional().describe(DESCRIPTION_DESCRIBE),
     type: z
         .enum(ISSUE_TYPES)
         .optional()
@@ -387,7 +419,7 @@ server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues
     ...boardField,
 }, async (args) => jsonResult(await issueEdit(client, args)));
 // ---------------- issue_transition ----------------
-server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issues/:id/transition. **THIS IS THE ONLY WAY TO MOVE A CARD'S LIFECYCLE STATE** — DX-835 separated card lifecycle (this tool) from dispatch finalization (`mcp__danxbot__danxbot_complete`). The worker no longer infers card moves from `danxbot_complete.status`; agents that want the card to move MUST call this tool BEFORE calling `danxbot_complete`. Actions: ready (Review→ToDo), pickup (ToDo→In Progress — server checks every dispatch gate: ready_at, blocked_at, requires_human_reason, depends_on partners terminal, conflict_on partners idle; refuses 409 with failed_gate naming the cause; pass manual:true for OPERATOR-SESSION self-pickup — stamps dispatch_kind 'manual', bypasses every card-flow gate except terminal/deleted/already-dispatched, and the worker NEVER auto-transitions the card: no orphan-heal rollback, no Epic auto-rollup — use this whenever the work happens in YOUR current session rather than a worker dispatch, DX-946), rollback_pickup, **complete** (stamps completed_at — moves card to Done; this is YOUR explicit decision, not a side effect of danxbot_complete; REFUSES 409 on Epic if any phase child non-terminal — see non_terminal_phases[]; ALSO refuses 409 with failed_gate 'quality_gate_post' + failed_post_gates[] while any required POST quality gate row != pass — DX-1177), cancel (stamps cancelled_at — terminal), **block** (requires non-empty reason — stamps blocked_at + blocked_reason + clears dispatch; USE THIS when the CARD itself cannot proceed without human intervention; distinct from env-fault dispatch failures which use `danxbot_complete({status:'failed'})`), unblock, archive (parks to Backlog, clears ready_at), reopen (terminal→active, clears completed_at/cancelled_at/archived_at). Terminal cards refuse every action except reopen. Ladder timestamps preserved — forward stamps never clear earlier ones (CLAUDE.md Core Principle 2). **DX-2282 — every path into In Progress now requires an identified claimer.** For `manual:true` pickup called from a DISPATCHED-AGENT session (this MCP tool, bearer = your dispatch token): you MUST pass `assigned_agent` set to YOUR resolved agent/profile name — omitting it, or passing the shared dispatch-token identity itself, is refused 409 `assigned_agent (required, distinguishing)`. A genuine human dashboard session may omit it (auto-resolved from the real logged-in user). Every pickup flavor (work/gate/manual) is refused 409 `assigned_agent (required)` if it would otherwise leave the card with no owner at all. **A manual pickup can now also be refused 409 `failed_gate: \"dispatch_id\"` — \"pickup refused — card claimed by another actor between read and write\" — when it loses a genuine race against a concurrent manual pickup of the same idle card.** Before this, two overlapping manual pickups of the same card could both return 200: the second write silently overwrote the first winner's claim with no error and no distinguishing status code. The claiming write is now atomic (fenced on `dispatch_id IS NULL`), so the loser gets this 409 instead of a false success — on this response, do NOT retry blindly; re-check the card's current `assigned_agent`/`dispatch_id` first, since another actor already has it.", {
+server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issues/:id/transition. **THIS IS THE ONLY WAY TO MOVE A CARD'S LIFECYCLE STATE** — DX-835 separated card lifecycle (this tool) from dispatch finalization (`mcp__danxbot__danxbot_complete`). The worker no longer infers card moves from `danxbot_complete.status`; agents that want the card to move MUST call this tool BEFORE calling `danxbot_complete`. Actions: ready (Review→ToDo), pickup (ToDo→In Progress — server checks every dispatch gate: ready_at, blocked_at, requires_human_reason, depends_on partners terminal, conflict_on partners idle; refuses 409 with failed_gate naming the cause; pass manual:true for OPERATOR-SESSION self-pickup — stamps dispatch_kind 'manual', bypasses every card-flow gate except terminal/deleted/already-dispatched, and the worker NEVER auto-transitions the card: no orphan-heal rollback, no Epic auto-rollup — use this whenever the work happens in YOUR current session rather than a worker dispatch, DX-946), rollback_pickup, **complete** (stamps completed_at — moves card to Done; this is YOUR explicit decision, not a side effect of danxbot_complete; REFUSES 409 on Epic if any phase child non-terminal — see non_terminal_phases[]; ALSO refuses 409 with failed_gate 'quality_gate_post' + failed_post_gates[] while any required POST quality gate row != pass — DX-1177), cancel (stamps cancelled_at — terminal), **block** (requires non-empty reason — stamps blocked_at + blocked_reason + clears dispatch; USE THIS when the CARD itself cannot proceed without human intervention; distinct from env-fault dispatch failures which use `danxbot_complete({status:'failed'})`), unblock, archive (parks to Backlog, clears ready_at), reopen (terminal→active, clears completed_at/cancelled_at/archived_at). Terminal cards refuse every action except reopen. Ladder timestamps preserved — forward stamps never clear earlier ones (CLAUDE.md Core Principle 2). **DX-2282 — every path into In Progress now requires an identified claimer.** For `manual:true` pickup called from a DISPATCHED-AGENT session (this MCP tool, bearer = your dispatch token): you MUST pass `assigned_agent` set to YOUR resolved agent/profile name — omitting it, or passing the shared dispatch-token identity itself, is refused 409 `assigned_agent (required, distinguishing)`. A genuine human dashboard session may omit it (auto-resolved from the real logged-in user). Every pickup flavor (work/gate/manual) is refused 409 `assigned_agent (required)` if it would otherwise leave the card with no owner at all. **A manual pickup can now also be refused 409 `failed_gate: \"dispatch_id\"` — \"pickup refused — card claimed by another actor between read and write\" — when it loses a genuine race against a concurrent manual pickup of the same idle card.** Before this, two overlapping manual pickups of the same card could both return 200: the second write silently overwrote the first winner's claim with no error and no distinguishing status code. The claiming write is now atomic (fenced on `dispatch_id IS NULL`), so the loser gets this 409 instead of a false success — on this response, do NOT retry blindly; re-check the card's current `assigned_agent`/`dispatch_id` first, since another actor already has it. **A successful `block` returns a `solutions_reminder` beside the envelope** — `{solution_count, instruction}` — because blocking stops the card for a human: before you stop, EVERY viable solution must be listed on the card with issue_solution (the operator answers by picking one). A count of zero means you have listed none.", {
     id: z.string().min(1),
     action: z.enum(TRANSITION_ACTIONS),
     reason: z.string().optional(),
@@ -442,6 +474,26 @@ server.tool("issue_checklist", "Targeted checklist CUD via /api/issues/:id/check
     status: z.enum(CHECKLIST_ITEM_STATUSES).optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueChecklist(client, args)));
+// ---------------- issue_solution ----------------
+server.tool("issue_solution", "A card's candidate SOLUTIONS — the options the operator picks from when a card is stopped for a human decision — via /api/issues/:id/solutions[/:sid]. Whenever you block a card or set requires_human, list EVERY viable solution here first, and mark the one you recommend. Action-dispatched: list (GET) — the live solutions (each with its `id` and `content_hash`) plus every operator answer recorded so far (`decisions[]`, oldest first); add (POST {title, body?, pro?, con?, recommended?}) — append one option; edit (PATCH :sid {base_hash, title?, body?, pro?, con?, recommended?}) — change ONLY the fields you pass; remove (DELETE :sid {base_hash}) — soft-remove an option. `title` is a short name for the option, `body` the markdown detail of what it actually does, `pro` / `con` the case for and against. HASH-GUARDED: edit and remove REQUIRE `base_hash` = the `content_hash` you last read; a stale one is refused 409 `stale_solution` carrying `currentHash` + `currentSolution` — merge against that and retry, never re-send blindly. A card recommends AT MOST ONE live solution: a second `recommended: true` is refused 409 naming `recommended_solution_id` (edit that one to recommended:false first). An option the operator has already CHOSEN cannot be edited (409) — add a new solution instead; it can still be removed, and the answer keeps its title. There is no answer action: the operator answers in the dashboard.", {
+    id: z.string().min(1),
+    action: z.enum(["list", "add", "edit", "remove"]),
+    solution_id: z.number().int().positive().optional().describe("Target solution id — required for edit / remove."),
+    base_hash: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("The solution's content_hash from your last read — required for edit / remove."),
+    title: z.string().min(1).optional().describe("Short name for the option — required for add."),
+    body: z.string().optional().describe("Markdown detail of what this option actually does."),
+    pro: z.string().optional().describe("The case FOR this option."),
+    con: z.string().optional().describe("The case AGAINST this option."),
+    recommended: z
+        .boolean()
+        .optional()
+        .describe("true on the single option you recommend. At most one live recommended solution per card."),
+    ...boardField,
+}, async (args) => jsonResult(await issueSolution(client, args)));
 // ---------------- issue_dependency ----------------
 server.tool("issue_dependency", 'Dependency CRUD via /api/issues/:id/dependencies[/:did]. action=add → POST {kind, target_id, reason} where kind ∈ {depends_on, conflict_on}. depends_on adds are CYCLE-CHECKED (BFS from target back to source — 409 if loop). Idempotent: re-adding a live triple returns the existing id. Self-loops refuse 409. action=remove → DELETE /:did. The server REQUIRES the literal reason="recorded_in_error" on removal (encodes "removal means NOT related, never satisfied") — this MCP boundary hardcodes it, so callers do not pass reason on remove. This is the ONLY mechanism the dispatch picker enforces to sequence one card after another — leaving a card at a Review/held status (e.g. an issue_triage "keep" verdict) is NOT a substitute and provides no cross-card ordering protection.', {
     id: z.string().min(1),
@@ -453,7 +505,7 @@ server.tool("issue_dependency", 'Dependency CRUD via /api/issues/:id/dependencie
     ...boardField,
 }, async (args) => jsonResult(await issueDependency(client, args)));
 // ---------------- issue_requires_human ----------------
-server.tool("issue_requires_human", "Set or clear the requires_human dispatch gate via /api/issues/:id/requires-human. set=true → POST {reason, steps[]} — sets requires_human_reason (the dispatch gate per DX-704 — poller refuses pickup while non-null), set_by from bearer, set_at NOW(), REPLACES the step rows (prior soft-deleted, fresh ordinals). set=false → DELETE — clears the columns and soft-deletes every live step. Terminal cards refuse 409 on set.", {
+server.tool("issue_requires_human", "Set or clear the requires_human dispatch gate via /api/issues/:id/requires-human. set=true → POST {reason, steps[]} — sets requires_human_reason (the dispatch gate per DX-704 — poller refuses pickup while non-null), set_by from bearer, set_at NOW(), REPLACES the step rows (prior soft-deleted, fresh ordinals). set=false → DELETE — clears the columns and soft-deletes every live step. Terminal cards refuse 409 on set. **A successful set=true returns a `solutions_reminder` beside the envelope** — `{solution_count, instruction}`: before you stop, EVERY viable solution to the question you are asking must be listed on the card with issue_solution, so the operator can answer by picking one. A count of zero means you have listed none.", {
     id: z.string().min(1),
     set: z.boolean(),
     reason: z.string().optional(),
@@ -579,8 +631,8 @@ server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug
 // plan id — and it can only ever bind the caller's own session. `plan_create`
 // also takes no plan id, but for a different reason: it MAKES a plan rather
 // than acting on one, so there is no existing plan for an id to name yet.
-server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped: a plan is a named, dated set of cards an operator assembled by hand, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). NOTE this is NOT the board Brief (`brief_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
-server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture document, the sessions working on it, and your own session state. One call, not five. Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. Returns `{plan, cards, boards, records: {goal: [], rule: [], caveat: []}, architecture: {content, contentHash, updatedAt, updatedBy}, sessions, session}`. ALWAYS `plan_get` immediately before `plan_set_architecture` and pass the returned `architecture.contentHash` back as `base_hash`.", {
+server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped: a plan is a named, dated set of cards an operator assembled by hand, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session, sessionListenerAttached}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). `sessionListenerAttached` says whether your event listener is running: `false` while connected to a plan means you will NOT hear about its cards — call `plan_connect` again and arm the Monitor it returns. NOTE this is NOT the board Brief (`brief_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
+server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture document, the sessions working on it, and your own session state. One call, not five. Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. Returns `{plan, cards, boards, records: {goal: [], rule: [], caveat: []}, architecture: {content, contentHash, updatedAt, updatedBy}, sessions, session, sessionListenerAttached}` — `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. ALWAYS `plan_get` immediately before `plan_set_architecture` and pass the returned `architecture.contentHash` back as `base_hash`.", {
     plan_id: z
         .number()
         .int()
@@ -591,9 +643,9 @@ server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — it
 server.tool("plan_create", "Create a new, empty plan via POST /api/plans (DX-2531). GLOBAL — a plan is not board-scoped, and this call adds no cards, no records, and no architecture document; it does NOT connect any session to the new plan (call `plan_connect` separately, exactly as adding a card to a plan is its own separate step). Returns `{ok, status, body: {plan: {id, name, createdAt}}}`. Use the returned `plan.id` with `plan_connect` to start working on it, or with `plan_get({plan_id})` to browse it.", {
     name: z.string().min(1).describe("The plan's name — shown in the Plans list."),
 }, async (args) => jsonResult(await planCreate(client, args)));
-server.tool("plan_connect", "Connect THIS session to a plan via POST /api/plan-sessions/me/plan (DX-2683) — the same binding the operator's Connect action writes, through the same server-side path. A session is connected to AT MOST ONE plan (enforced by the schema, not by convention); connecting while already on another plan MOVES you, and the response says which plan you left: `{ok, status, body: {session, movedFrom: {id, name} | null}}`. `movedFrom: null` means you were on no plan, or already on this one. It can only ever bind your OWN session — `me` is resolved from the session id this server forwards, never from anything you pass. After this, every plan WRITE tool acts on this plan, and no plan id is accepted anywhere.", {
+server.tool("plan_connect", "Connect THIS session to a plan via POST /api/plan-sessions/me/plan (DX-2683) — the same binding the operator's Connect action writes, through the same server-side path. A session is connected to AT MOST ONE plan (enforced by the schema, not by convention); connecting while already on another plan MOVES you, and the response says which plan you left: `{ok, status, body: {session, movedFrom: {id, name} | null}}`. `movedFrom: null` means you were on no plan, or already on this one. It can only ever bind your OWN session — `me` is resolved from the session id this server forwards, never from anything you pass. After this, every plan WRITE tool acts on this plan, and no plan id is accepted anywhere. THE REPLY ALSO CARRIES `listener: {command, persistent: true, instruction}` — arm it IMMEDIATELY with the Monitor tool (`command` as given, `persistent: true`): from then on every comment, answer, requires_human change and block/unblock on this plan's cards arrives as a notification line like `[DX-8 \"Title\" repo:board] newms87 answered: chose \"Pause E2E\" — note: \"…\"`. Never poll for these. The command carries a narrow stream ticket, not a credential; calling plan_connect again (same plan is fine) issues a new one and ends the old listener, which is how you re-arm after a session restart or after the Monitor reports it gave up. If the ticket cannot be issued the call fails with `listener_not_armed` even though the connect itself happened.", {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
-}, async (args) => jsonResult(await planConnect(client, args)));
+}, async (args) => jsonResult(await planConnect(client, args, { baseUrl: config.baseUrl, packageSpec: PACKAGE_SPEC })));
 server.tool("plan_add_record", "Add a GOAL, RULE or CAVEAT to the plan this session is connected to, via POST /api/plans/mine/records (DX-2683). A goal is what the plan is FOR (the outcome the work is measured against — not a task). A rule is what must HOLD while it is worked. A caveat is what is known to be AWKWARD — the fact that will surprise the next person. Each gets a permanent short reference within the plan (`G-1`, `R-4`, `CAV-12`) allocated by the server, which is how a person cites it in a card or a commit. TAKES NO PLAN ID: the plan is resolved from your connected session, so you cannot write a plan you are not connected to. Not connected → `{error: \"session_not_connected\"}`; call `plan_connect` first. Returns the new record plus that kind's full list.", {
     kind: z
         .enum(["goal", "rule", "caveat"])
@@ -638,9 +690,28 @@ async function main() {
 // schemas can be introspected without spawning a dispatch. The check is
 // symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
 // spawns, not just a direct `node dist/index.js`.
+//
+// `listen` is the one subcommand: the session event listener `plan_connect`
+// tells the agent to arm as a Monitor. It never boots the MCP server and reads
+// none of the MCP env — its whole configuration is its two flags. Any OTHER
+// argument is refused rather than ignored, so a typo cannot silently start an
+// MCP server on stdio where a listener was meant to run.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
-    main().catch((err) => {
-        console.error(`[danx-dashboard-mcp] fatal: ${err.message}`);
-        process.exit(1);
-    });
+    const [subcommand, ...rest] = process.argv.slice(2);
+    if (subcommand === LISTEN_SUBCOMMAND) {
+        runListenCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] listen fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
+    else if (subcommand !== undefined) {
+        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is "${LISTEN_SUBCOMMAND}")`);
+        process.exit(2);
+    }
+    else {
+        main().catch((err) => {
+            console.error(`[danx-dashboard-mcp] fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
 }

package/dist/listen.js

@@ -0,0 +1,278 @@
+/**
+ * `danx-dashboard-mcp listen --stream <url> --ticket <ticket> --lease-ms <ms>` —
+ * a working session's event listener.
+ *
+ * WHY IT EXISTS. A Claude Code session cannot be interrupted from outside, but
+ * its Monitor tool runs a background command and turns every line that command
+ * prints into a notification that wakes the session. This command is that
+ * background process: it holds the dashboard's session event stream open and
+ * prints ONE line per event on the plan the session is connected to — a comment,
+ * an answer, a `requires_human` change, a block — so the operator's answer
+ * reaches the agent within seconds, with no polling anywhere.
+ *
+ * THE OUTPUT CONTRACT, BECAUSE EVERY LINE WAKES THE AGENT:
+ *   - exactly one line per event, written the moment it arrives;
+ *   - nothing for keep-alives, the connect marker, or a successful reconnect;
+ *   - one line for an event it cannot read (never silence);
+ *   - one final line, and exit, only when it gives up or the dashboard ends it.
+ *
+ * RECONNECT. The stream drops whenever the dashboard restarts, and can also die
+ * silently (sleep, NAT, proxy). A read-idle timeout of three missed keep-alives
+ * turns silent death into a drop. Retries use capped exponential backoff and send
+ * `Last-Event-ID`; the dashboard replays what was missed (with a small overlap)
+ * and an id already printed is never printed twice. The backoff only resets once
+ * a connection proves healthy — it delivered an event, or stayed up past one
+ * keep-alive — so a dashboard that admits and immediately drops is not hammered.
+ * The listener gives up once it has gone `--lease-ms` without a healthy
+ * connection (past that the ticket cannot be admitted anyway), or at once when
+ * the ticket is refused.
+ *
+ * Everything server-specific — the stream URL and the lease — arrives as flags
+ * from `plan_connect`, which read them off the dashboard's own ticket response.
+ * Only the event shape is hand-copied from the dashboard's `IssueActivityEvent`
+ * (`src/issues/db/issue-activity.ts`); this published package cannot import
+ * danxbot source.
+ */
+export const LISTEN_SUBCOMMAND = "listen";
+export const INITIAL_BACKOFF_MS = 1_000;
+export const MAX_BACKOFF_MS = 30_000;
+/** Three of the dashboard's 15 s keep-alives without a byte means the connection is dead. */
+export const READ_IDLE_TIMEOUT_MS = 45_000;
+/** A connection that stays up this long has proven the dashboard healthy. */
+export const HEALTHY_CONNECTION_MS = 20_000;
+/** How many printed event ids the duplicate guard remembers — well past the replay overlap. */
+const PRINTED_ID_MEMORY = 1_000;
+const LINE_PREFIX = "[danx-dashboard listen]";
+const REARM = "Call plan_connect again and arm the Monitor it returns to keep receiving this plan's events.";
+const USAGE = `usage: danx-dashboard-mcp ${LISTEN_SUBCOMMAND} --stream <stream-url> --ticket <ticket> --lease-ms <ms>`;
+/** Parse the three required flags; anything else is refused. */
+export function parseListenArgs(argv) {
+    const values = new Map();
+    for (let i = 0; i < argv.length; i += 2) {
+        const flag = argv[i];
+        const value = argv[i + 1];
+        if (!["--stream", "--ticket", "--lease-ms"].includes(flag) || value === undefined || value === "") {
+            throw new Error(USAGE);
+        }
+        values.set(flag, value);
+    }
+    const streamUrl = values.get("--stream");
+    const ticket = values.get("--ticket");
+    const leaseMs = Number(values.get("--lease-ms"));
+    if (!streamUrl || !ticket || !Number.isSafeInteger(leaseMs) || leaseMs <= 0)
+        throw new Error(USAGE);
+    return { streamUrl, ticket, leaseMs };
+}
+function quoted(value) {
+    return `"${value.text}${value.truncated ? "…" : ""}"`;
+}
+function describe(event) {
+    const d = event.detail;
+    switch (event.kind) {
+        case "comment_added":
+            return `${event.actor} commented: ${quoted(d.excerpt)}`;
+        case "solution_answered": {
+            const solution = d.solution;
+            if (solution === null)
+                return `${event.actor} answered: ${quoted(d.freeform)}`;
+            const note = solution.note === null ? "" : ` — note: ${quoted(solution.note)}`;
+            return `${event.actor} answered: chose "${solution.title}"${note}`;
+        }
+        case "requires_human_set":
+            return `${event.actor} set requires_human: ${quoted(d.reason)}`;
+        case "requires_human_cleared":
+            return `${event.actor} cleared requires_human`;
+        case "blocked":
+            return `${event.actor} blocked the card: ${quoted(d.reason)}`;
+        case "unblocked":
+            return `${event.actor} unblocked the card`;
+        default:
+            // A kind newer than this listener still produces a line: an event the
+            // agent is never told about is exactly the failure this command prevents.
+            return `${event.actor}: ${event.kind}`;
+    }
+}
+/** The one notification line for an event. Always a single line; throws on a malformed event. */
+export function formatActivityLine(event) {
+    return `[${event.cardId} "${event.cardTitle}" ${event.boardId}] ${describe(event)}`.replace(/\s+/g, " ");
+}
+/**
+ * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
+ * field-less blocks produce no message, which is what keeps them off stdout.
+ */
+export class SseParser {
+    buffer = "";
+    push(chunk) {
+        this.buffer += chunk.replace(/\r\n?/g, "\n");
+        const messages = [];
+        let boundary = this.buffer.indexOf("\n\n");
+        while (boundary !== -1) {
+            const message = parseBlock(this.buffer.slice(0, boundary));
+            this.buffer = this.buffer.slice(boundary + 2);
+            if (message !== null)
+                messages.push(message);
+            boundary = this.buffer.indexOf("\n\n");
+        }
+        return messages;
+    }
+}
+function parseBlock(block) {
+    let id = null;
+    let event = "message";
+    const data = [];
+    let sawField = false;
+    for (const line of block.split("\n")) {
+        if (line === "" || line.startsWith(":"))
+            continue;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        const value = colon === -1 ? "" : line.slice(colon + 1).replace(/^ /, "");
+        sawField = true;
+        if (field === "id")
+            id = value;
+        else if (field === "event")
+            event = value;
+        else if (field === "data")
+            data.push(value);
+    }
+    return sawField ? { id, event, data: data.join("\n") } : null;
+}
+/** Statuses that describe the moment, not the ticket — retry them. */
+const RETRYABLE_CLIENT_STATUSES = new Set([408, 429]);
+/**
+ * Run until the dashboard ends the stream or the listener gives up. Returns the
+ * exit code: 0 when a newer listener took over, 1 when revoked, refused, or
+ * given up.
+ */
+export async function runListener(options, deps) {
+    const printed = new Set();
+    let lastEventId = null;
+    let unhealthySince = null;
+    let attempt = 0;
+    const remember = (id) => {
+        printed.add(id);
+        if (printed.size > PRINTED_ID_MEMORY)
+            printed.delete(printed.values().next().value);
+        lastEventId = lastEventId === null ? id : Math.max(lastEventId, id);
+    };
+    const handle = (message) => {
+        if (message.event === "end") {
+            const reason = JSON.parse(message.data).reason;
+            return { kind: "ended", reason: typeof reason === "string" ? reason : "unknown" };
+        }
+        if (message.event !== "activity")
+            return null;
+        const id = Number(message.id);
+        if (Number.isSafeInteger(id) && printed.has(id))
+            return null;
+        try {
+            deps.write(formatActivityLine(JSON.parse(message.data)));
+        }
+        catch (err) {
+            // Never silence, and never a reconnect loop on the same bad event: say so
+            // in one line and move past it.
+            deps.write(`${LINE_PREFIX} could not read event ${message.id ?? "(no id)"} (${err.message}): ` +
+                `${message.data.slice(0, 300)}`.replace(/\s+/g, " "));
+        }
+        if (Number.isSafeInteger(id))
+            remember(id);
+        return null;
+    };
+    const connectOnce = async () => {
+        const controller = new AbortController();
+        let idle;
+        const armIdle = () => {
+            clearTimeout(idle);
+            idle = setTimeout(() => controller.abort(), deps.readIdleTimeoutMs);
+        };
+        const headers = {
+            Authorization: `Bearer ${options.ticket}`,
+            Accept: "text/event-stream",
+        };
+        if (lastEventId !== null)
+            headers["Last-Event-ID"] = String(lastEventId);
+        const openedAt = deps.now();
+        let delivered = false;
+        const healthy = () => delivered || deps.now() - openedAt >= HEALTHY_CONNECTION_MS;
+        try {
+            armIdle();
+            const response = await deps.fetch(options.streamUrl, { headers, signal: controller.signal });
+            if (response.status >= 400 && response.status < 500 && !RETRYABLE_CLIENT_STATUSES.has(response.status)) {
+                return { kind: "refused", detail: `HTTP ${response.status} ${(await response.text()).slice(0, 300)}` };
+            }
+            if (!response.ok || response.body === null) {
+                await response.body?.cancel();
+                return { kind: "dropped", healthy: false };
+            }
+            const parser = new SseParser();
+            const decoder = new TextDecoder();
+            for await (const chunk of response.body) {
+                armIdle();
+                for (const message of parser.push(decoder.decode(chunk, { stream: true }))) {
+                    const outcome = handle(message);
+                    if (outcome !== null)
+                        return outcome;
+                    if (message.event === "activity")
+                        delivered = true;
+                }
+            }
+            return { kind: "dropped", healthy: healthy() };
+        }
+        catch {
+            return { kind: "dropped", healthy: healthy() };
+        }
+        finally {
+            clearTimeout(idle);
+            controller.abort();
+        }
+    };
+    for (;;) {
+        const outcome = await connectOnce();
+        if (outcome.kind === "ended") {
+            if (outcome.reason === "superseded" || outcome.reason === "replaced") {
+                deps.write(`${LINE_PREFIX} stopped: another listener for this session took over (${outcome.reason}). ` +
+                    `If you did not just call plan_connect, something else did — ${REARM}`);
+                return 0;
+            }
+            deps.write(`${LINE_PREFIX} stopped: the dashboard ended this listener (${outcome.reason}). ${REARM}`);
+            return 1;
+        }
+        if (outcome.kind === "refused") {
+            deps.write(`${LINE_PREFIX} gave up: the dashboard refused the listener ticket (${outcome.detail}). ${REARM}`);
+            return 1;
+        }
+        if (outcome.healthy) {
+            unhealthySince = null;
+            attempt = 0;
+        }
+        const now = deps.now();
+        unhealthySince ??= now;
+        if (now - unhealthySince >= options.leaseMs) {
+            deps.write(`${LINE_PREFIX} gave up: no healthy connection to ${options.streamUrl} for ` +
+                `${Math.round((now - unhealthySince) / 60_000)} minutes, past the ticket's lease. ${REARM}`);
+            return 1;
+        }
+        await deps.sleep(Math.min(MAX_BACKOFF_MS, INITIAL_BACKOFF_MS * 2 ** attempt));
+        attempt += 1;
+    }
+}
+/** The bin's `listen` subcommand, wired to the real process. */
+export async function runListenCommand(argv) {
+    let options;
+    try {
+        options = parseListenArgs(argv);
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n`);
+        return 2;
+    }
+    return runListener(options, {
+        fetch,
+        write: (line) => {
+            process.stdout.write(`${line}\n`);
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: Date.now,
+        readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
+    });
+}

package/package.json

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