@thehammer/danx-dashboard-mcp 0.1.63 → 0.1.64

package/README.md

@@ -25,12 +25,13 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `issue_get` | `GET /api/issues/:id` or `GET /api/issues/batch` | Pass `id` for one card, or `ids[]` (DX-2727, at most 100) to resolve many across boards in ONE call — global, so `ids` with `board` throws; per-id `not_found` rather than a whole-call 404. Minimal scalars by default; `fields` opts in |
 | `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_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen. `block` is a dispatch hold only — it never marks the card as needing a human; use `issue_problem` + `issue_requires_human` for that |
+| `issue_problem` | `GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid]` | Actions list / add / edit / remove. A problem is one statement the operator must resolve (a question or a plan flaw) with its own solutions and answers; `add` takes `statement` + optional `solutions[]` in one transaction. Edit + remove are hash-guarded (`base_hash`, 409 `stale_problem`); removing the last open problem while `requires_human` is set is refused 409 `last_open_problem` |
+| `issue_solution` | `POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid]` | Actions add / edit / remove, `problem_id` required (list via `issue_problem list`). Edit + remove are hash-guarded (`base_hash`, 409 `stale_solution` with the current row); at most one live `recommended` per problem; a chosen option cannot be edited. No answer action on any tool — 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. A successful set also returns `solutions_reminder: {solution_count, instruction}` |
+| `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set REQUIRES an open problem (409 `no_open_problem` with the server's `fix` otherwise) and replaces step rows atomically; clear soft-deletes them. The gate clears itself when the last open problem is answered. A successful set also returns `problems_reminder: {open_problem_count, instruction}` |
 | `issue_retro` | `PUT /api/issues/:id/retro` | Requires terminal card; replace semantics |
 
 ## `plan_get` — cheap by default, opt-in for the rest (DX-2727)
@@ -48,7 +49,7 @@ npx -y @thehammer/danx-dashboard-mcp@<version> listen --stream <dashboard>/api/p
 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.
+- **Output.** Exactly one line per event on the connected plan's cards — `[DX-8 "Title" repo:board] newms87 answered "Which rollout order?": chose "Pause E2E" — note: "only this week"`, `… answered "…": "<free-form answer>"`, `… 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

package/dist/handlers.js

@@ -23,6 +23,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { basename, extname, isAbsolute } from "node:path";
+import { oneLine } from "./one-line.js";
 import { resolvePriority } from "./priority.js";
 /**
  * `filter`/`fields`/`sort` are JSON/CSV-encoded onto the query string (the
@@ -255,62 +256,92 @@ export async function issueEdit(client, args) {
 }
 export async function issueTransition(client, args) {
     const { id, board, ...body } = args;
-    const result = await client.request({
+    // DX-2735: no reminder on block. A block is a dispatch HOLD only — it never
+    // puts the card in front of a human — so there is no question to list
+    // options for. A card that needs a human uses issue_problem + issue_requires_human.
+    return client.request({
         method: "POST",
         path: `/${encodeURIComponent(id)}/transition`,
         body,
         board,
     });
-    return args.action === "block" ? withSolutionsReminder(client, id, board, result) : result;
+}
+/** How much of a problem statement the reminder quotes — enough to recognise it. */
+const REMINDER_STATEMENT_MAX = 120;
+function isReminderProblem(value) {
+    const p = value;
+    return (typeof p === "object" &&
+        p !== null &&
+        typeof p.id === "number" &&
+        typeof p.statement === "string" &&
+        typeof p.open === "boolean" &&
+        Array.isArray(p.solutions));
 }
 /**
- * Attach the solutions reminder to a SUCCESSFUL gating write.
+ * Attach the problems reminder to a SUCCESSFUL requires-human set.
  *
- * 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.
+ * DX-2735 — THE SERVER NOW ENFORCES THE QUESTION, THIS ENFORCES THE OPTIONS.
+ * The set route refuses 409 `no_open_problem` unless the card has an open
+ * problem, so a card can no longer be put in front of a human without saying
+ * what the human must decide. Whether each open problem lists its viable
+ * solutions is still feedback, not refusal: a problem with zero solutions is
+ * valid (the operator answers free-form), and refusing it would push the agent
+ * into inventing options. So the reminder rides the success response and names
+ * the STILL-OPEN problems only — an answered sibling needs nothing more.
  *
- * 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.
+ * The write's own envelope is returned untouched beside it. A refused write
+ * (including `no_open_problem`, whose `fix` text passes through verbatim) gets
+ * no reminder and no extra request. A failure READING the problems is reported
+ * inside the reminder rather than thrown: the set already succeeded, and
+ * throwing would tell the agent it failed when it did not.
  */
-export async function withSolutionsReminder(client, id, board, result) {
+export async function withProblemsReminder(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`,
+            path: `/${encodeURIComponent(id)}/problems`,
             board,
         });
     }
     catch (err) {
-        return { ...result, solutions_reminder: unreadableReminder(id, err instanceof Error ? err.message : String(err)) };
+        return { ...result, problems_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 problems = listed.ok ? listed.body?.problems : undefined;
+    if (!Array.isArray(problems) || !problems.every(isReminderProblem)) {
+        // A 2xx whose body is not the problem list is a contract break, not a refusal —
+        // say so, rather than leaving a bare "HTTP 200" that reads like success.
+        const detail = listed.ok ? `HTTP ${listed.status}, unexpected shape` : `HTTP ${listed.status}`;
+        return { ...result, problems_reminder: unreadableReminder(id, detail) };
+    }
+    const open = problems.filter((p) => p.open);
+    return { ...result, problems_reminder: { open_problem_count: open.length, instruction: openProblemsInstruction(id, open) } };
+}
+function openProblemsInstruction(id, open) {
+    if (open.length === 0) {
+        // Only reachable when every problem was answered between the set and this
+        // read — the gate has already released itself.
+        return `No problem on ${id} is open any more — each was answered after you set requires_human, which releases the gate. Re-read the card before you stop.`;
     }
-    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 } };
+    const listing = open
+        .map((p) => {
+        const statement = oneLine(p.statement, REMINDER_STATEMENT_MAX);
+        const count = p.solutions.length;
+        return `problem ${p.id} "${statement}" — ${count === 0 ? "NO SOLUTIONS LISTED" : `${count} solution${count === 1 ? "" : "s"}`}`;
+    })
+        .join("; ");
+    return (`${open.length} open problem${open.length === 1 ? "" : "s"} on ${id}: ${listing}. ` +
+        `Before you stop, list EVERY viable solution to each with issue_solution({id: "${id}", problem_id, action: "add", title, body, pro, con}) and mark the one you recommend with recommended: true, ` +
+        `and make every other question the operator must answer its own problem with issue_problem. The card needs a human until every open problem is answered.`);
 }
 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.`,
+        open_problem_count: null,
+        instruction: `Could not read the problems on ${id} (${detail}). Check with issue_problem({id: "${id}", action: "list"}) and make sure EVERY viable solution to each open problem is listed before you stop.`,
     };
 }
 export async function issueTriage(client, args) {
@@ -322,72 +353,104 @@ export async function issueTriage(client, args) {
         board,
     });
 }
+/**
+ * DX-2735 — the ONE boundary check every action-dispatched handler uses for its
+ * required args. The MCP schema already validates, but a handler can be called
+ * without it (tests, the composition E2E, a future caller), so each required arg
+ * is checked by TYPE, not merely for presence: `null`, a number where text
+ * belongs, or a string where a row id belongs all throw here, before any request
+ * is built, as `<tool> <mode> requires <arg> (<what it must be>)`.
+ *
+ * Returns the checkers rather than checking anything itself. `mode` is the
+ * condition the args are required under — `action=<action>` for the
+ * action-dispatched tools, `set=true` for issue_requires_human — so every tool
+ * refuses in the same wording.
+ */
+function argCheckers(tool, mode) {
+    const fail = (name, expected) => {
+        throw new Error(`${tool} ${mode} requires ${name} (${expected})`);
+    };
+    return {
+        /** Text, a content hash, a name, an enum value. */
+        string(value, name) {
+            if (typeof value !== "string")
+                fail(name, "a string");
+            return value;
+        },
+        /** A database row id. */
+        id(value, name) {
+            if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+                fail(name, "a positive integer id");
+            return value;
+        },
+        /**
+         * A list of human-written lines (e.g. requires_human steps). DX-2735: every
+         * element must be a non-blank string, matching the server, which refuses a
+         * blank step — refused here before any request is built. An empty list is
+         * allowed, as the server allows it.
+         */
+        stringArray(value, name) {
+            const valid = Array.isArray(value) && value.every((item) => typeof item === "string" && item.trim() !== "");
+            if (!valid)
+                fail(name, "an array of non-blank strings");
+            return value;
+        },
+    };
+}
 export async function issueComment(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
+    const need = argCheckers("issue_comment", `action=${args.action}`);
     if (args.action === "add") {
-        if (typeof args.text !== "string") {
-            throw new Error("issue_comment action=add requires text");
-        }
+        const text = need.string(args.text, "text");
         return client.request({
             method: "POST",
             path: `/${idEnc}/comments`,
-            body: { text: args.text, ...(args.metadata !== undefined ? { metadata: args.metadata } : {}) },
+            body: { text, ...(args.metadata !== undefined ? { metadata: args.metadata } : {}) },
             board,
         });
     }
     if (args.action === "edit") {
-        if (args.comment_id === undefined) {
-            throw new Error("issue_comment action=edit requires comment_id");
-        }
-        if (typeof args.text !== "string") {
-            throw new Error("issue_comment action=edit requires text");
-        }
+        const commentId = need.id(args.comment_id, "comment_id");
+        const text = need.string(args.text, "text");
         return client.request({
             method: "PATCH",
-            path: `/${idEnc}/comments/${args.comment_id}`,
-            body: { text: args.text },
+            path: `/${idEnc}/comments/${commentId}`,
+            body: { text },
             board,
         });
     }
     // delete
-    if (args.comment_id === undefined) {
-        throw new Error("issue_comment action=delete requires comment_id");
-    }
+    const commentId = need.id(args.comment_id, "comment_id");
     return client.request({
         method: "DELETE",
-        path: `/${idEnc}/comments/${args.comment_id}`,
+        path: `/${idEnc}/comments/${commentId}`,
         board,
     });
 }
 export async function issueDependency(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
+    const need = argCheckers("issue_dependency", `action=${args.action}`);
     if (args.action === "add") {
-        if (args.kind === undefined) {
-            throw new Error("issue_dependency action=add requires kind");
-        }
-        if (args.target_id === undefined) {
-            throw new Error("issue_dependency action=add requires target_id");
-        }
+        const kind = need.string(args.kind, "kind");
+        const targetId = need.string(args.target_id, "target_id");
         return client.request({
             method: "POST",
             path: `/${idEnc}/dependencies`,
             body: {
-                kind: args.kind,
-                target_id: args.target_id,
+                kind,
+                target_id: targetId,
                 reason: args.reason ?? "",
             },
             board,
         });
     }
     // remove
-    if (args.dependency_id === undefined) {
-        throw new Error("issue_dependency action=remove requires dependency_id");
-    }
+    const dependencyId = need.id(args.dependency_id, "dependency_id");
     return client.request({
         method: "DELETE",
-        path: `/${idEnc}/dependencies/${args.dependency_id}`,
+        path: `/${idEnc}/dependencies/${dependencyId}`,
         // Server demands literal "recorded_in_error" — any other value is
         // a 400. The MCP boundary hardcodes it to remove a footgun: an
         // agent that types the wrong reason gets a refusal here at MCP
@@ -407,12 +470,10 @@ export async function issueDependency(client, args) {
 export async function issueChecklist(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
+    const need = argCheckers("issue_checklist", `action=${args.action}`);
     switch (args.action) {
         case "add_list": {
-            if (typeof args.name !== "string") {
-                throw new Error("issue_checklist action=add_list requires name");
-            }
-            const body = { name: args.name };
+            const body = { name: need.string(args.name, "name") };
             if (args.items !== undefined)
                 body.items = args.items;
             return client.request({
@@ -423,55 +484,40 @@ export async function issueChecklist(client, args) {
             });
         }
         case "update_list": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=update_list requires checklist_id");
-            }
-            if (typeof args.name !== "string") {
-                throw new Error("issue_checklist action=update_list requires name");
-            }
+            const checklistId = need.id(args.checklist_id, "checklist_id");
+            const name = need.string(args.name, "name");
             return client.request({
                 method: "PATCH",
-                path: `/${idEnc}/checklists/${args.checklist_id}`,
-                body: { name: args.name },
+                path: `/${idEnc}/checklists/${checklistId}`,
+                body: { name },
                 board,
             });
         }
         case "remove_list": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=remove_list requires checklist_id");
-            }
+            const checklistId = need.id(args.checklist_id, "checklist_id");
             return client.request({
                 method: "DELETE",
-                path: `/${idEnc}/checklists/${args.checklist_id}`,
+                path: `/${idEnc}/checklists/${checklistId}`,
                 board,
             });
         }
         case "add_item": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=add_item requires checklist_id");
-            }
-            if (typeof args.label !== "string") {
-                throw new Error("issue_checklist action=add_item requires label");
-            }
-            const body = { label: args.label };
+            const checklistId = need.id(args.checklist_id, "checklist_id");
+            const body = { label: need.string(args.label, "label") };
             if (args.detail !== undefined)
                 body.detail = args.detail;
             if (args.status !== undefined)
                 body.status = args.status;
             return client.request({
                 method: "POST",
-                path: `/${idEnc}/checklists/${args.checklist_id}/items`,
+                path: `/${idEnc}/checklists/${checklistId}/items`,
                 body,
                 board,
             });
         }
         case "update_item": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=update_item requires checklist_id");
-            }
-            if (args.item_id === undefined) {
-                throw new Error("issue_checklist action=update_item requires item_id");
-            }
+            const checklistId = need.id(args.checklist_id, "checklist_id");
+            const itemId = need.id(args.item_id, "item_id");
             const body = {};
             if (args.label !== undefined)
                 body.label = args.label;
@@ -481,39 +527,92 @@ export async function issueChecklist(client, args) {
                 body.status = args.status;
             return client.request({
                 method: "PATCH",
-                path: `/${idEnc}/checklists/${args.checklist_id}/items/${args.item_id}`,
+                path: `/${idEnc}/checklists/${checklistId}/items/${itemId}`,
                 body,
                 board,
             });
         }
         case "remove_item": {
-            if (args.checklist_id === undefined) {
-                throw new Error("issue_checklist action=remove_item requires checklist_id");
-            }
-            if (args.item_id === undefined) {
-                throw new Error("issue_checklist action=remove_item requires item_id");
-            }
+            const checklistId = need.id(args.checklist_id, "checklist_id");
+            const itemId = need.id(args.item_id, "item_id");
+            return client.request({
+                method: "DELETE",
+                path: `/${idEnc}/checklists/${checklistId}/items/${itemId}`,
+                board,
+            });
+        }
+    }
+}
+/**
+ * A card's PROBLEMS via `/api/issues/:id/problems[/:pid]` (DX-2735),
+ * action-dispatched like `issue_checklist`. A problem is one statement the
+ * operator must resolve — a question or a flaw in the plan — owning its own
+ * solutions and its own decisions. A missing required arg throws at this
+ * boundary (no round-trip); the server's refusals (`stale_problem` with the
+ * current row, `last_open_problem`) pass through verbatim.
+ *
+ * `add` carries `solutions[]` in the SAME request so a problem and its options
+ * land in one server transaction — never a problem briefly visible to the
+ * operator with none of the options it was created with.
+ *
+ * No answer action, for the reason `issueSolution` gives.
+ */
+export async function issueProblem(client, args) {
+    const idEnc = encodeURIComponent(args.id);
+    const board = args.board;
+    const need = argCheckers("issue_problem", `action=${args.action}`);
+    switch (args.action) {
+        case "list":
+            return client.request({ method: "GET", path: `/${idEnc}/problems`, board });
+        case "add": {
+            const body = { statement: need.string(args.statement, "statement") };
+            if (args.solutions !== undefined)
+                body.solutions = args.solutions;
+            return client.request({ method: "POST", path: `/${idEnc}/problems`, body, board });
+        }
+        case "edit": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            const statement = need.string(args.statement, "statement");
+            return client.request({
+                method: "PATCH",
+                path: `/${idEnc}/problems/${problemId}`,
+                body: { base_hash: baseHash, statement },
+                board,
+            });
+        }
+        case "remove": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
             return client.request({
                 method: "DELETE",
-                path: `/${idEnc}/checklists/${args.checklist_id}/items/${args.item_id}`,
+                path: `/${idEnc}/problems/${problemId}`,
+                body: { base_hash: baseHash },
                 board,
             });
         }
     }
 }
 /**
- * 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.
+ * One problem's candidate solutions via
+ * `/api/issues/:id/problems/:pid/solutions[/:sid]` (DX-2735), 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 on the same
+ * problem, editing a chosen option, a solution id from another problem → 404)
+ * 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.
+ * There is deliberately NO answer action, on this tool or any other. Answering
+ * releases the human gate on a card — 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 need = argCheckers("issue_solution", `action=${args.action}`);
+    // DX-2735: checked at runtime too, not only by the schema — a caller that skips
+    // the MCP boundary must never build `/problems/undefined/solutions`.
+    const problemId = need.id(args.problem_id, "problem_id");
+    const base = `/${encodeURIComponent(args.id)}/problems/${problemId}/solutions`;
     const board = args.board;
     const content = {};
     for (const key of ["title", "body", "pro", "con", "recommended"]) {
@@ -521,58 +620,49 @@ export async function issueSolution(client, args) {
             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");
-            }
+        case "add": {
+            // DX-2735: the POST carries the CHECKED title, not a re-read of args.title.
+            const title = need.string(args.title, "title");
+            return client.request({ method: "POST", path: base, body: { ...content, title }, board });
+        }
+        case "edit": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
             return client.request({
                 method: "PATCH",
-                path: `${base}/${args.solution_id}`,
-                body: { base_hash: args.base_hash, ...content },
+                path: `${base}/${solutionId}`,
+                body: { base_hash: baseHash, ...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");
-            }
+        }
+        case "remove": {
+            const solutionId = need.id(args.solution_id, "solution_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
             return client.request({
                 method: "DELETE",
-                path: `${base}/${args.solution_id}`,
-                body: { base_hash: args.base_hash },
+                path: `${base}/${solutionId}`,
+                body: { base_hash: baseHash },
                 board,
             });
+        }
     }
 }
 export async function issueRequiresHuman(client, args) {
     const idEnc = encodeURIComponent(args.id);
     const board = args.board;
     if (args.set) {
-        if (typeof args.reason !== "string") {
-            throw new Error("issue_requires_human set=true requires reason");
-        }
-        if (!Array.isArray(args.steps)) {
-            throw new Error("issue_requires_human set=true requires steps[]");
-        }
+        // DX-2735: the same checkers every action-dispatched tool uses, so the refusal
+        // wording and type checks match — `issue_requires_human set=true requires ...`.
+        const need = argCheckers("issue_requires_human", "set=true");
+        const reason = need.string(args.reason, "reason");
+        const steps = need.stringArray(args.steps, "steps");
         const result = await client.request({
             method: "POST",
             path: `/${idEnc}/requires-human`,
-            body: { reason: args.reason, steps: args.steps },
+            body: { reason, steps },
             board,
         });
-        return withSolutionsReminder(client, args.id, board, result);
+        return withProblemsReminder(client, args.id, board, result);
     }
     return client.request({
         method: "DELETE",

package/dist/index.js

@@ -19,7 +19,8 @@
  *   - 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_problem          GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid] (DX-2735)
+ *   - issue_solution         POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid] (DX-2735)
  *   - 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
@@ -88,7 +89,7 @@ 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, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, 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, issueRequiresHuman, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, planAddArchitectureSection, planAddCard, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, 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 { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -214,7 +215,8 @@ const NON_EPIC_TYPES = ["Bug", "Feature", "Story", "Chore", "Task"];
 // server 400, not silently.
 const LIST_FIELD_GROUPS = [
     "description",
-    "solutions",
+    // DX-2735: replaced the flat "solutions" group (hard cut, no alias).
+    "problems",
     "ac",
     "comments",
     "retro",
@@ -280,9 +282,12 @@ const boardField = {
 // 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.';
+const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, technical detail; markdown, collapsed by default. A question for the operator and its options go in issue_problem, not here.';
 // ---------------- 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, content_hash), 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.", {
+server.tool("issue_list", 
+// DX-2735: trimmed to pay for the problem tools inside the work-profile
+// injected-surface budget — same facts, no repeated prose.
+"List cards via GET /api/issues on this dispatch's board, or `board` (`<repo>:<slug>`; unknown → 404). `filter`: type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, q (free text over id+title+description). THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash), no joins; opt into heavy data with `fields` groups: description (+ summary), problems (open_problem_count), ac, comments, retro, dependencies, triage, requires_human, assignment, quality_gates, children, effort. `sort`: [{column, order}] over id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at; default priority desc, repo_name asc, numeric-id tiebreaker. `limit`/`offset` page (uncapped by default). issue_get reads one card in full.", {
     filter: z
         .object({
         q: z.string().optional(),
@@ -295,30 +300,27 @@ server.tool("issue_list", "List issues for the dispatch's board by default via G
         include_closed: z.boolean().optional(),
         include_deleted: z.boolean().optional(),
     })
-        .optional()
-        .describe("Nested list filters (DX-935) — the hard-cut replacement for the old flat top-level params, including the former standalone `q` (now `filter.q`). Omit entirely for no filtering."),
+        .optional(),
     fields: z
         .array(z.enum(LIST_FIELD_GROUPS))
         .optional()
-        .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."),
+        .describe("Field groups to add; absent = minimal scalars."),
     sort: sortField,
     limit: z.number().int().positive().max(LIST_PAGE_MAX_LIMIT).optional(),
     offset: z.number().int().nonnegative().optional(),
     ...boardField,
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
-server.tool("issue_get", "Fetch one card via GET /api/issues/:id, or MANY via GET /api/issues/batch?ids=... (DX-2727) — pass exactly one of `id` (single) or `ids` (batch, an array). Board-scoped for the single form; defaults to the dispatch's board. Issue ids are globally unique, so BOTH forms resolve from any dispatch regardless of `board`; the batch form is a global, cross-board read and REFUSES `board` (passing `ids` with `board` throws). The batch form takes at most " + ISSUE_BATCH_GET_MAX + " ids per call — split a larger set. 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, content_hash — DX-2741, the card's optimistic-concurrency token; pass it back as `content_hash` on an `issue_edit` touching title/description/checklists); no joined collections. Pass `fields` to opt into named field-GROUPS, applied per card in the batch form too: 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. Single form: 404 envelope on unknown id. Batch form: returns `{issues: [...found cards...], not_found: [...ids that didn't resolve...]}` — an unknown or soft-deleted id never fails the whole call, it just lands in `not_found` alongside every card that DID resolve.", {
-    id: z.string().min(1).optional().describe("A single card id. Mutually exclusive with `ids`."),
-    ids: z
-        .array(z.string().min(1))
-        .min(1)
-        .max(ISSUE_BATCH_GET_MAX)
-        .optional()
-        .describe(`Batch form (DX-2727): every requested id (at most ${ISSUE_BATCH_GET_MAX}), resolved globally in ONE call. Mutually exclusive with \`id\`, and never combined with \`board\` (the batch is global; passing both throws). Reports not_found per id rather than failing the whole call.`),
+server.tool("issue_get", 
+// DX-2735: trimmed to pay for the problem tools inside the work-profile
+// injected-surface budget — same facts, no repeated prose.
+"Fetch one card (GET /api/issues/:id, `id`) or many (GET /api/issues/batch, `ids`, at most " + ISSUE_BATCH_GET_MAX + " — split larger sets); pass exactly one. Ids are globally unique, so both resolve from any board; the batch form is global and throws with `board`. THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash: the concurrency token issue_edit needs for title/description/checklists). `fields` opts into groups, per card in a batch too: description (body + summary), problems (live problems in order, each {id, statement, content_hash, open} with its solutions[] and decisions[]), ac (acceptance criteria + checklists), comments, retro, dependencies (waiting_on/conflict_on/blocked), triage (history + ICE), requires_human (gate + steps), assignment (dispatch, assigned_agent, lifecycle timestamps), quality_gates (one row per gate {gate, required, status pending|pass|fail, completed_at, message}; a required PRE gate not `pass` pre-empts the work dispatch, and complete refuses while a required POST gate is not `pass`), children (ids + rollups), mirrors (external sync state), code_review_items. Single form: unknown id → 404. Batch form: `{issues: [...], not_found: [...ids]}` — an unknown or deleted id never fails the call.", {
+    id: z.string().min(1).optional(),
+    ids: z.array(z.string().min(1)).min(1).max(ISSUE_BATCH_GET_MAX).optional(),
     fields: z
         .array(z.enum(GET_FIELD_GROUPS))
         .optional()
-        .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."),
+        .describe("Field groups to add; absent = minimal scalars."),
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
@@ -436,7 +438,9 @@ server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED
     ...boardField,
 }, async (args) => jsonResult(await issueEdit(client, args)));
 // ---------------- issue_transition ----------------
-server.tool("issue_transition", "Move a card's lifecycle via POST /api/issues/:id/transition — the ONLY way to; `danxbot_complete` never moves a card, so call this BEFORE it. Actions: ready (Review→ToDo); pickup (ToDo→In Progress; checks every dispatch gate — ready, blocked, requires_human, depends_on terminal, conflict_on idle — and refuses 409 with failed_gate naming the cause; `manual:true` is an operator-session self-pickup that bypasses card-flow gates and is never auto-rolled-back: use it when the work happens in YOUR session); rollback_pickup; complete (your explicit decision; refuses 409 on an Epic with non-terminal children, non_terminal_phases[], or while a required POST quality gate is not pass, failed_gate 'quality_gate_post' + failed_post_gates[]); cancel (terminal); block (non-empty reason; the CARD needs a human — env faults use `danxbot_complete({status:'failed'})` instead); unblock; archive (to Backlog, clears ready_at); reopen (terminal→active). Terminal cards refuse everything but reopen; forward stamps never clear earlier ones. Every path into In Progress needs an identified claimer: a dispatched agent's manual pickup MUST pass `assigned_agent` = your agent/profile name (409 otherwise). A manual pickup that loses a race is refused 409 `failed_gate: \"dispatch_id\"` — re-read the card's assigned_agent/dispatch_id, never retry blindly. A successful block returns `solutions_reminder: {solution_count, instruction}`: before stopping, list EVERY viable solution with issue_solution; zero means you listed none.", {
+server.tool("issue_transition", 
+// DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
+"Move a card's lifecycle via POST /api/issues/:id/transition — the ONLY way; `danxbot_complete` never moves a card, so call this first. Actions: ready (Review→ToDo); pickup (ToDo→In Progress; checks every dispatch gate — ready, blocked, requires_human, depends_on terminal, conflict_on idle — and refuses 409 with failed_gate naming the cause; `manual:true` is a self-pickup for work in YOUR session: it bypasses card-flow gates and is never auto-rolled-back); rollback_pickup; complete (your explicit decision; 409 on an Epic with non-terminal children (non_terminal_phases[]) or while a required POST quality gate is not pass (failed_gate 'quality_gate_post' + failed_post_gates[])); cancel (terminal); block (non-empty reason; only holds dispatch, never asks a human — for that use issue_problem then issue_requires_human; env faults use `danxbot_complete({status:'failed'})`); unblock; archive (to Backlog, clears ready_at); reopen (terminal→active). Terminal cards refuse all but reopen; forward stamps never clear earlier ones. A dispatched agent's manual pickup MUST pass `assigned_agent` = your agent/profile name (409 otherwise); one that loses a race is refused 409 `failed_gate: \"dispatch_id\"` — re-read assigned_agent/dispatch_id, never retry blindly.", {
     id: z.string().min(1),
     action: z.enum(TRANSITION_ACTIONS),
     reason: z.string().optional(),
@@ -491,24 +495,37 @@ 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.", {
+// ---------------- issue_problem ----------------
+// DX-2735: the option fields, shared by `issue_problem` add's inline solutions[]
+// and `issue_solution`. Their meaning is stated ONCE, in issue_solution's
+// description — per-field describes repeated it on every call's context.
+const SOLUTION_FIELDS = {
+    body: z.string().optional(),
+    pro: z.string().optional(),
+    con: z.string().optional(),
+    recommended: z.boolean().optional(),
+};
+server.tool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: each is one statement the operator must resolve (a question, or a flaw in the plan) with its own solutions and answers — one problem per question. OPEN = not yet answered; the card needs a human until none is open, and issue_requires_human set is refused 409 `no_open_problem` until one is. 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); edit :pid {base_hash, statement}; remove :pid {base_hash} (409 `last_open_problem` while requires_human is set). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. 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()
+    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"),
+    solutions: z
+        .array(z.object({ title: z.string().min(1), ...SOLUTION_FIELDS }))
         .optional()
-        .describe("true on the single option you recommend. At most one live recommended solution per card."),
+        .describe("add only; fields as issue_solution add"),
+    ...boardField,
+}, async (args) => jsonResult(await issueProblem(client, args)));
+// ---------------- issue_solution ----------------
+server.tool("issue_solution", "One problem's options via /api/issues/:id/problems/:pid/solutions[/:sid]; `problem_id` is REQUIRED (from issue_problem list/add; another problem's solution id → 404). add {title, body?, pro?, con?, recommended?}: title names the option, body is its markdown detail, pro/con the case for and against; edit :sid {base_hash, ...only the changed fields}; remove :sid {base_hash}. A stale base_hash → 409 `stale_solution` with currentHash + currentSolution: merge, then retry. At most ONE live recommended per problem: a second → 409 naming `recommended_solution_id`. A chosen option cannot be edited (409 — add a new one) but can be removed.", {
+    id: z.string().min(1),
+    action: z.enum(["add", "edit", "remove"]),
+    problem_id: z.number().int().positive(),
+    solution_id: z.number().int().positive().optional().describe("edit/remove"),
+    base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove"),
+    title: z.string().min(1).optional().describe("add"),
+    ...SOLUTION_FIELDS,
     ...boardField,
 }, async (args) => jsonResult(await issueSolution(client, args)));
 // ---------------- issue_dependency ----------------
@@ -522,7 +539,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. **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.", {
+server.tool("issue_requires_human", "Set/clear the requires_human gate via /api/issues/:id/requires-human — the ONLY flag that puts a card in front of a human (block only holds dispatch). Escalate in order: 1) issue_problem add (statement + every viable solution, one recommended); 2) set=true {reason, steps[]} — refused 409 `no_open_problem` (with the server's `fix`) while no problem is open. Set stamps requires_human_reason (no pickup while non-null) and replaces the steps; it clears itself when the last open problem is answered. set=false → DELETE clears it and its steps. Terminal cards refuse 409. Success returns `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count.", {
     id: z.string().min(1),
     set: z.boolean(),
     reason: z.string().optional(),
@@ -677,7 +694,9 @@ server.tool("plan_get", "Read a plan via GET /api/plans (DX-2683). Pass `plan_id
 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 sections; 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. 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.", {
+server.tool("plan_connect", 
+// DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
+"Connect THIS session to a plan via POST /api/plan-sessions/me/plan — the same binding the operator's Connect action writes. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and the reply says which plan it left: `{session, movedFrom: {id, name} | null}` (null = no plan, or already this one). It binds only your OWN session, resolved from the session id this server forwards. Afterwards every plan WRITE tool acts on this plan and takes no plan id. THE REPLY ALSO CARRIES `listener: {command, persistent: true, instruction}` — arm it IMMEDIATELY with the Monitor tool (`persistent: true`): every comment, answer, requires_human change and block/unblock on this plan's cards then arrives as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<problem statement>\": chose \"Pause E2E\" — note: \"…\"`. Never poll for these. The command holds a narrow stream ticket, not a credential; calling plan_connect again (same plan is fine) issues a new one and ends the old listener — how you re-arm after a restart or a give-up. If no ticket can be issued the call fails `listener_not_armed`, though the connect happened.", {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
 }, 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 your connected plan (POST /api/plans/mine/records). A GOAL is an outcome the work is measured against. A RULE is a constraint that must hold while it is worked. A CAVEAT is a lasting trade-off or limitation of the ARCHITECTURE — never progress, status or a session note (those are comments on the card). `body` is ONE plain statement of at most 250 characters; the evidence, history and detail go in `context` (markdown). An overlong body is refused with a 400 naming its length. The server allocates a permanent reference (`G-1`, `R-4`, `CAV-12`). Takes no plan id; `session_not_connected` → `plan_connect` first. Returns the record plus that kind's list.", {

package/dist/listen.js

@@ -33,6 +33,7 @@
  * (`src/issues/db/issue-activity.ts`); this published package cannot import
  * danxbot source.
  */
+import { oneLine } from "./one-line.js";
 export const LISTEN_SUBCOMMAND = "listen";
 export const INITIAL_BACKOFF_MS = 1_000;
 export const MAX_BACKOFF_MS = 30_000;
@@ -66,17 +67,71 @@ export function parseListenArgs(argv) {
 function quoted(value) {
     return `"${value.text}${value.truncated ? "…" : ""}"`;
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCappedText(value) {
+    return isRecord(value) && typeof value.text === "string" && typeof value.truncated === "boolean";
+}
+/**
+ * DX-2735 — why an event cannot be described, or `null` when it can.
+ *
+ * Checked BEFORE describing, so a malformed event is reported by what is
+ * actually wrong with it — never by whichever TypeError a missing field happens
+ * to raise (whose wording is the JS engine's, not ours). The envelope is checked
+ * for every kind; the detail only for the kinds `describe` reads, so a kind newer
+ * than this listener still produces its generic line.
+ */
+export function invalidEventReason(value) {
+    if (!isRecord(value))
+        return "the event is not an object";
+    if (typeof value.id !== "number" || !Number.isSafeInteger(value.id))
+        return "id is not an integer";
+    for (const field of ["cardId", "cardTitle", "boardId", "actor", "kind"]) {
+        if (typeof value[field] !== "string")
+            return `${field} is not a string`;
+    }
+    const d = value.detail;
+    if (!isRecord(d))
+        return "detail is not an object";
+    switch (value.kind) {
+        case "comment_added":
+            return isCappedText(d.excerpt) ? null : "detail.excerpt is not capped text";
+        case "solution_answered": {
+            const problem = d.problem;
+            if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
+                return "detail.problem is not {id, statement}";
+            }
+            if (d.solution === null)
+                return isCappedText(d.freeform) ? null : "detail.freeform is not capped text";
+            if (!isRecord(d.solution) || typeof d.solution.title !== "string")
+                return "detail.solution is not {title, note}";
+            return d.solution.note === null || isCappedText(d.solution.note) ? null : "detail.solution.note is not capped text";
+        }
+        case "requires_human_set":
+        case "blocked":
+            return isCappedText(d.reason) ? null : "detail.reason is not capped text";
+        default:
+            return null;
+    }
+}
+/** Only ever called on an event `invalidEventReason` accepted, so its casts are checked. */
 function describe(event) {
     const d = event.detail;
     switch (event.kind) {
         case "comment_added":
             return `${event.actor} commented: ${quoted(d.excerpt)}`;
         case "solution_answered": {
+            // DX-2735: every answer answers ONE problem on a card that may carry several,
+            // so the line names the problem — otherwise the agent cannot tell which of its
+            // questions just closed.
+            const problem = d.problem;
+            const answered = `${event.actor} answered ${quoted(problem.statement)}:`;
             const solution = d.solution;
             if (solution === null)
-                return `${event.actor} answered: ${quoted(d.freeform)}`;
+                return `${answered} ${quoted(d.freeform)}`;
             const note = solution.note === null ? "" : ` — note: ${quoted(solution.note)}`;
-            return `${event.actor} answered: chose "${solution.title}"${note}`;
+            return `${answered} chose "${solution.title}"${note}`;
         }
         case "requires_human_set":
             return `${event.actor} set requires_human: ${quoted(d.reason)}`;
@@ -92,9 +147,12 @@ function describe(event) {
             return `${event.actor}: ${event.kind}`;
     }
 }
-/** The one notification line for an event. Always a single line; throws on a malformed event. */
+/** The one notification line for an event. Always a single line; throws, naming the fault, on a malformed event. */
 export function formatActivityLine(event) {
-    return `[${event.cardId} "${event.cardTitle}" ${event.boardId}] ${describe(event)}`.replace(/\s+/g, " ");
+    const invalid = invalidEventReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed activity event: ${invalid}`);
+    return oneLine(`[${event.cardId} "${event.cardTitle}" ${event.boardId}] ${describe(event)}`);
 }
 /**
  * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
@@ -165,14 +223,27 @@ export async function runListener(options, deps) {
         const id = Number(message.id);
         if (Number.isSafeInteger(id) && printed.has(id))
             return null;
+        // DX-2735: an event that is not JSON, or JSON of the wrong shape, is reported
+        // from an explicit check naming the fault — never from a TypeError thrown
+        // partway through describing it. Never silence, and never a reconnect loop on
+        // the same bad event: say so in one line and move past it.
+        let parsed;
+        let invalid;
         try {
-            deps.write(formatActivityLine(JSON.parse(message.data)));
+            parsed = JSON.parse(message.data);
+            invalid = invalidEventReason(parsed);
         }
         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, " "));
+            invalid = `not JSON: ${err.message}`;
+        }
+        if (invalid === null) {
+            deps.write(formatActivityLine(parsed));
+        }
+        else {
+            deps.write(`${LINE_PREFIX} could not read event ${message.id ?? "(no id)"} (${invalid}): ` +
+                // DX-2735: oneLine caps by code point, so a bad event carrying an emoji
+                // at the cut can never leave a lone surrogate in the line.
+                oneLine(message.data, 300));
         }
         if (Number.isSafeInteger(id))
             remember(id);
@@ -198,7 +269,7 @@ export async function runListener(options, deps) {
             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)}` };
+                return { kind: "refused", detail: `HTTP ${response.status} ${oneLine(await response.text(), 300)}` };
             }
             if (!response.ok || response.body === null) {
                 await response.body?.cancel();

package/dist/one-line.js

@@ -0,0 +1,18 @@
+/**
+ * DX-2735 — the ONE way this package renders human text into an agent-facing
+ * line: the listen notification line and the requires_human problems reminder
+ * both go through it, so they can never disagree about how a statement looks.
+ *
+ * Every whitespace run (newlines included) collapses to a single space, because
+ * a notification is one line and a reminder quotes statements inline. The
+ * optional cap counts CODE POINTS, never UTF-16 units: `String#slice` can cut
+ * an emoji or any astral character in half and leave a lone surrogate, which
+ * renders as garbage. A capped string ends with "…" so truncation is visible.
+ */
+export function oneLine(text, maxCodePoints) {
+    const collapsed = text.replace(/\s+/g, " ");
+    if (maxCodePoints === undefined)
+        return collapsed;
+    const points = Array.from(collapsed);
+    return points.length > maxCodePoints ? `${points.slice(0, maxCodePoints).join("")}…` : collapsed;
+}

package/package.json

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