@thehammer/danx-dashboard-mcp 0.1.148 → 0.1.150

package/README.md

@@ -22,12 +22,13 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | Tool | HTTP | Notes |
 |---|---|---|
 | `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` 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_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` (DX-3426) opts in via a recursive field TREE — `{"description": true, "problems": {"solutions": true}, "comments": {"limit": 10}}` — not a flat group list; a cursor-paged relation (today only `comments`) takes its page args (`limit`/`before`) inside its own nested object, so paging now works on the batch form too. See `resource_fields` |
+| `resource_fields` | `GET /api/resources/:resource/fields` | DX-3426 — what an `issue_get`-style field tree may name for one resource: `{resource, description, always, hashes, fields, relations}`. Install-global, no `board`. `resource: "issue"` is the root; a relation's own `resource` in the response is what to call this again with, one level deeper |
 | `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. `block` is a dispatch hold only — it never marks the card as needing a human; use `issue_problem` add 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 and IS what puts the card in front of a human (`open_problem_count > 0`) — a successful add also returns a `reminders: [{key, text}]` array (DX-3365 — the reminder registry's middleware, DB-driven and operator-overridable from the dashboard). Edit + remove are hash-guarded (`base_hash`, 409 `stale_problem`); removing the card's last open problem is always allowed — it just means the card no longer needs a human |
-| `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_problem` | `GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid]` + `POST .../answer`, `change-answer`, `unanswer` | Actions list / add / edit / remove / answer / change_answer / unanswer (DX-3471). 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 and IS what puts the card in front of a human (`open_problem_count > 0`) — a successful add also returns a `reminders: [{key, text}]` array (DX-3365 — the reminder registry's middleware, DB-driven and operator-overridable from the dashboard). Edit + remove are hash-guarded (`base_hash`, 409 `stale_problem`); removing the card's last open problem is always allowed — it just means the card no longer needs a human. `answer` `{solution_id, note?}` \| `{freeform}` and `change_answer` (same + `base_hash` naming the live DECISION) / `unanswer` (`{base_hash}`) record or retract an operator's decision — server-refused 403 for a dispatched agent's machine credential (DX-2830), reachable from an OPERATOR SESSION relaying an in-chat decision, which also durably records the relaying session (`relayed_by_session`) via the same session header every call already carries |
+| `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 THIS tool — see `issue_problem`'s answer / change_answer / unanswer actions |
 | `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 |

package/dist/entrypoint.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, writeFileSync, symlinkSync, rmSync, realpathSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isEntrypointModule } from "./entrypoint.js";
+describe("isEntrypointModule (DX-1647)", () => {
+    let dir;
+    let real;
+    let link;
+    beforeAll(() => {
+        dir = mkdtempSync(join(tmpdir(), "entrypoint-test-"));
+        real = join(dir, "index.js");
+        writeFileSync(real, "// stub entry\n");
+        link = join(dir, "danx-dashboard-mcp"); // mimics node_modules/.bin symlink
+        symlinkSync(real, link);
+    });
+    afterAll(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    // import.meta.url always reports the module REALPATH — model that here.
+    const moduleUrl = () => pathToFileURL(realpathSync(real)).href;
+    it("true when argv[1] is the real file (direct `node index.js`)", () => {
+        expect(isEntrypointModule(moduleUrl(), real)).toBe(true);
+    });
+    it("true when argv[1] is a SYMLINK to the file (npx / global bin) — the fleet regression", () => {
+        // The symlink path !== the realpath, but the entrypoint MUST still be
+        // detected, or npx imports the module and exits without booting the server.
+        expect(link).not.toBe(realpathSync(link));
+        expect(isEntrypointModule(moduleUrl(), link)).toBe(true);
+    });
+    it("false when argv[1] is undefined (module imported, not run as bin)", () => {
+        expect(isEntrypointModule(moduleUrl(), undefined)).toBe(false);
+    });
+    it("false when argv[1] is an empty string", () => {
+        expect(isEntrypointModule(moduleUrl(), "")).toBe(false);
+    });
+    it("false when argv[1] points at a different real file", () => {
+        const other = join(dir, "other.js");
+        writeFileSync(other, "// other\n");
+        expect(isEntrypointModule(moduleUrl(), other)).toBe(false);
+    });
+});

package/dist/field-tree.js

@@ -0,0 +1,35 @@
+/**
+ * DX-3426 — the shared recursive FIELD-TREE shape.
+ *
+ * The dashboard's single-card and batch card reads (`issue_get` today;
+ * `issue_list` / `plan_get` in later cards, per DX-3426's own follow-up scope)
+ * take a nested JSON tree instead of a flat field-GROUP list: each key names a
+ * field or relation of the resource at that level, and each value is either
+ * `true` (the field, or a relation's child with its default fields), a
+ * non-negative integer (a cursor-paged relation's own page ARGUMENT — e.g.
+ * `{"comments": {"limit": 10, "before": 812}}`, where `limit`/`before` are
+ * themselves plain integer values inside the nested object), or another
+ * field tree (a relation's child with a NAMED field selection). Example:
+ *
+ *   {"description": true, "ac": true, "problems": {"solutions": {"steps": true}, "decisions": true}, "comments": {"limit": 10}}
+ *
+ * One schema, one module — every tool that accepts a field tree imports THIS
+ * export rather than redeclaring the shape, so the recursion is defined once
+ * and every caller's JSON Schema serializes the same way. `z.lazy` is
+ * required because the schema refers to itself; `zod-to-json-schema` (the
+ * MCP SDK's own zod v3 → JSON Schema converter, see
+ * `@modelcontextprotocol/sdk`'s `zod-json-schema-compat.ts`) resolves that
+ * self-reference to a local `$ref` rather than unrolling it infinitely —
+ * verified directly against the listed tool schema in
+ * `__tests__/tool-defs.test.ts`, not assumed from reading the library's
+ * source. `issue_solution`'s pre-existing `steps` field (DX-3310) is the
+ * same `z.lazy` self-reference pattern already shipping on this server.
+ */
+import { z } from "zod";
+/**
+ * The shared schema. A record whose values are `true`, a non-negative
+ * integer, or the same schema recursively — generic on purpose (no
+ * issue-specific field names baked in here) so `issue_list` / `plan_get` can
+ * reuse it unchanged in their own later cards.
+ */
+export const fieldTreeSchema = z.lazy(() => z.record(z.union([z.literal(true), z.number().int().nonnegative(), fieldTreeSchema])));

package/dist/handlers.js

@@ -95,16 +95,15 @@ export async function issueGet(client, args) {
     if (args.ids !== undefined && args.board !== undefined) {
         throw new Error("issue_get: board does not apply to the ids batch form — it resolves every id globally; drop board");
     }
-    // DX-3321 — comments paging is a SINGLE-id-route feature
-    // (`GET /api/issues/:id?comments_limit=&comments_offset=`); the batch
-    // route has no per-card paging at all. Refuse rather than silently drop,
-    // same as the `ids` + `board` refusal just above.
-    if (args.ids !== undefined && (args.comments_limit !== undefined || args.comments_offset !== undefined)) {
-        throw new Error("issue_get: comments_limit/comments_offset do not apply to the ids batch form — it has no per-card comment paging; drop them or use the single-id form");
-    }
     const query = {};
-    if (args.fields !== undefined && args.fields.length > 0) {
-        query.fields = args.fields.join(",");
+    // DX-3426 — the tree travels as ONE JSON-encoded query param (mirrors how
+    // `issue_list`'s `filter`/`sort` envelopes already ride the wire above),
+    // rather than the old CSV-of-group-names. Sent on both the single and
+    // batch forms — comment paging (or any other relation argument) now lives
+    // INSIDE the tree, so there is nothing left for the old ids+comments_*
+    // refusal to guard against.
+    if (args.fields !== undefined && Object.keys(args.fields).length > 0) {
+        query.fields = JSON.stringify(args.fields);
     }
     if (args.ids !== undefined) {
         if (args.ids.length === 0) {
@@ -118,10 +117,6 @@ export async function issueGet(client, args) {
     if (args.id === undefined) {
         throw new Error("issue_get: pass exactly one of id or ids");
     }
-    if (args.comments_limit !== undefined)
-        query.comments_limit = args.comments_limit;
-    if (args.comments_offset !== undefined)
-        query.comments_offset = args.comments_offset;
     return client.request({
         method: "GET",
         path: `/${encodeURIComponent(args.id)}`,
@@ -568,7 +563,31 @@ export async function issueChecklist(client, args) {
  * `.describe()` in `index.ts` — that description, not this comment, is what
  * a calling agent actually reads.
  *
- * No answer action, for the reason `issueSolution` gives.
+ * DX-3471 — `answer` {solution_id, note?} | {freeform} → POST :pid/answer;
+ * `change_answer` {base_hash, solution_id, note?} | {base_hash, freeform} →
+ * POST :pid/change-answer (retracts the live decision and records a new one
+ * in ONE server transaction); `unanswer` {base_hash} → POST :pid/unanswer
+ * (retracts with no new answer, reopening the problem). `base_hash` on these
+ * two names the live DECISION (`decisionContentHash`), NOT the problem —
+ * read it off a problem's `decisions[].content_hash` (from `list`), never
+ * off the problem's own `content_hash`. A stale one → 409 `stale_decision`
+ * with `currentHash` + `currentProblem`: merge, then retry.
+ *
+ * ALL THREE ARE OPERATOR-SESSION ONLY. The server's route policy admits only
+ * a `human` principal on these three routes (`route-policies/index.ts`) — a
+ * dispatched agent's machine credential is refused before it ever reaches a
+ * handler, for the DX-2830 reason: an agent that could answer its own
+ * question could release the very human gate it set to stop and wait for.
+ * An operator-session agent (running under the OPERATOR's own dashboard
+ * token, human-authenticated) CAN call these — this is what turns "the
+ * operator decided in chat" into a durable, correctly-attributed decision
+ * instead of a comment or a raw curl call. The decision records the human
+ * decider (`decided_by`) and, when this call carries the session id
+ * `@thehammer/danx-dashboard-mcp` already stamps on every request
+ * (`x-danx-session-id`, DX-2683 — no separate parameter needed here),
+ * which working session relayed it (`relayed_by_session` on the resulting
+ * decision, DX-3471) — so a decision entered from the dashboard's own UI
+ * (no header) stays distinguishable from one an agent relayed in chat.
  */
 /**
  * DX-3310 (nit) — per-action allow-list for `refuseInapplicableFields`.
@@ -583,6 +602,9 @@ const PROBLEM_ACTION_FIELDS = {
     add: ["statement", "context", "type", "summary", "solutions"],
     edit: ["problem_id", "base_hash", "statement", "context", "summary", "type"],
     remove: ["problem_id", "base_hash"],
+    answer: ["problem_id", "solution_id", "note", "freeform"],
+    change_answer: ["problem_id", "base_hash", "solution_id", "note", "freeform"],
+    unanswer: ["problem_id", "base_hash"],
 };
 export async function issueProblem(client, args) {
     const idEnc = encodeURIComponent(args.id);
@@ -652,8 +674,66 @@ export async function issueProblem(client, args) {
                 board,
             });
         }
+        // DX-3471 — answer/change_answer share the exact-one-of solution_id/freeform
+        // shape the server's own `validateAnswer` enforces (`write/problem-answer.ts`);
+        // checked here too so a caller gets the same clear boundary error every
+        // OTHER missing/conflicting-arg case in this tool already gets, rather than
+        // a round trip to the server for a 400 the client could have caught.
+        case "answer": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            return client.request({
+                method: "POST",
+                path: `/${idEnc}/problems/${problemId}/answer`,
+                body: answerChoiceBody(args, "answer"),
+                board,
+            });
+        }
+        case "change_answer": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            return client.request({
+                method: "POST",
+                path: `/${idEnc}/problems/${problemId}/change-answer`,
+                body: { base_hash: baseHash, ...answerChoiceBody(args, "change_answer") },
+                board,
+            });
+        }
+        case "unanswer": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            return client.request({
+                method: "POST",
+                path: `/${idEnc}/problems/${problemId}/unanswer`,
+                body: { base_hash: baseHash },
+                board,
+            });
+        }
     }
 }
+/**
+ * DX-3471 — the either/or answer shape `answer`/`change_answer` both send:
+ * `{solution_id, note?}` XOR `{freeform}`, mirroring the server's own
+ * `validateAnswer` (`write/problem-answer.ts`) so a caller gets the SAME
+ * refusal at this client boundary that the server would otherwise 400 on,
+ * with no round trip.
+ */
+function answerChoiceBody(args, mode) {
+    const hasSolution = args.solution_id !== undefined;
+    const hasFreeform = args.freeform !== undefined;
+    if (hasSolution === hasFreeform) {
+        throw new Error(`issue_problem ${mode} requires either solution_id or freeform (never both, never neither)`);
+    }
+    if (hasFreeform) {
+        if (args.note !== undefined) {
+            throw new Error(`issue_problem ${mode}: note qualifies a chosen solution — it is not valid with freeform`);
+        }
+        return { freeform: args.freeform };
+    }
+    const body = { solution_id: args.solution_id };
+    if (args.note !== undefined)
+        body.note = args.note;
+    return body;
+}
 /**
  * One problem's candidate solutions, AND (DX-3310) one solution's individual
  * procedure steps, via `/api/issues/:id/problems/:pid/solutions[/:sid][/steps[/:stepId]]`
@@ -664,10 +744,13 @@ export async function issueProblem(client, args) {
  * solution/step id from the wrong scope → 404, nesting past depth 3 → 400)
  * pass through verbatim.
  *
- * 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.
+ * There is deliberately NO answer action on THIS tool — answering releases the
+ * human gate on a card, and this tool has no notion of "who is calling".
+ * `issue_problem`'s `answer` / `change_answer` / `unanswer` actions (DX-3471)
+ * are where that lives instead: server-side human-principal-only (a
+ * dispatched agent's machine credential is refused 403), so an operator
+ * session can record a decision but a dispatched worker cannot release its
+ * own gate.
  */
 const SOLUTION_ACTION_FIELDS = {
     add: ["title", "body", "pro", "con", "recommended", "steps"],
@@ -1635,3 +1718,20 @@ export async function dispatchTranscriptSearch(client, args) {
         },
     };
 }
+// ---------------- resource_fields (DX-3426) ----------------
+const RESOURCES_BASE_PATH = "/api/resources";
+/**
+ * `GET /api/resources/:resource/fields` — what a field TREE (`issue_get`'s
+ * `fields`, and any later tool built on the same shape) may name for ONE
+ * resource: `{resource, description, always, hashes, fields, relations}`.
+ * Install-global (no `board` — mirrors `failure_category_list`'s own
+ * board-less rationale just above: nothing server-side would read one).
+ * Unknown resource → 404 `unknown_resource`.
+ */
+export async function resourceFields(client, args) {
+    return client.request({
+        method: "GET",
+        path: `/${encodeURIComponent(args.resource)}/fields`,
+        basePath: RESOURCES_BASE_PATH,
+    });
+}

package/dist/index.js

@@ -12,7 +12,11 @@
  * through the workspace `mcp.template.json`):
  *
  *   - issue_list             GET    /api/issues
- *   - issue_get              GET    /api/issues/:id | /api/issues/batch (DX-2727 ids[] batch)
+ *   - issue_get              GET    /api/issues/:id | /api/issues/batch (DX-2727 ids[] batch;
+ *                            DX-3426 `fields` is a recursive field TREE, not a flat group list —
+ *                            see `resource_fields` below and `./field-tree.ts`)
+ *   - resource_fields        GET    /api/resources/:resource/fields (DX-3426 — what `fields` may
+ *                            name for a resource; install-global, no `board`)
  *   - issue_create           POST   /api/issues
  *   - issue_edit             PATCH  /api/issues/:id/edit
  *   - issue_transition       POST   /api/issues/:id/transition
@@ -106,8 +110,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
-import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, dispatchTranscriptSearch, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_EVENT_KINDS, PLAN_EVENT_ORIGINS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, PLAN_GET_EVENTS_DEFAULT_LIMIT, PLAN_GET_EVENTS_MAX_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, qualityGateInstruction, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, briefGetPage, briefList, briefSetPage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, dispatchTranscriptSearch, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_FIELD_GROUPS, PLAN_EVENT_KINDS, PLAN_EVENT_ORIGINS, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, PLAN_GET_CARDS_DEFAULT_LIMIT, PLAN_GET_EVENTS_DEFAULT_LIMIT, PLAN_GET_EVENTS_MAX_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, repoKnowledgeGet, repoKnowledgeSet, qualityGateInstruction, resourceFields, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
+import { fieldTreeSchema } from "./field-tree.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
     if (typeof v !== "string" || v === "") {
@@ -272,10 +277,11 @@ const EFFORT_VALUES = [
 // still be CREATED through this MCP.
 const ISSUE_TYPES = ["Epic", "Bug", "Feature", "Story", "Chore", "Task"];
 const NON_EPIC_TYPES = ["Bug", "Feature", "Story", "Chore", "Task"];
-// DX-935 / DX-937 — field-group taxonomy for the nested read envelope,
-// hand-copied from `src/issues/read/field-groups.ts` (LIST_GROUPS / GET_GROUPS
-// — this package cannot import server source). Drift surfaces at runtime as a
-// server 400, not silently.
+// DX-935 / DX-937 — field-group taxonomy for the LIST read envelope,
+// hand-copied from `src/issues/read/field-groups.ts` (`LIST_GROUPS` — this
+// package cannot import server source). Drift surfaces at runtime as a server
+// 400, not silently. DX-3426 moved `issue_get` to the field tree
+// (`field-tree.ts`); DX-3427 moves the list the same way and deletes this.
 const LIST_FIELD_GROUPS = [
     "description",
     // DX-2735: replaced the flat "solutions" group (hard cut, no alias).
@@ -290,13 +296,6 @@ const LIST_FIELD_GROUPS = [
     "children",
     "effort",
 ];
-const GET_FIELD_GROUPS = [
-    ...LIST_FIELD_GROUPS,
-    "mirrors",
-    "code_review_items",
-    // DX-2835 — every plan this card is on ({id, ref, name}[]), detail only.
-    "plans",
-];
 const SORT_ORDERS = ["asc", "desc"];
 const sortField = z
     .array(z.object({
@@ -393,33 +392,27 @@ strictTool("issue_list",
 }, async (args) => jsonResult(await issueList(client, args)));
 // ---------------- issue_get ----------------
 strictTool("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 (`id`) or many (`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[] — a card needs a human exactly when open_problem_count > 0), ac (acceptance criteria + checklists), comments (paged via `comments_limit`/`comments_offset` — see their own field descriptions, single-id form only), retro, dependencies (waiting_on/conflict_on/blocked), triage (history + ICE), 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, plans (every plan this card is on, `{id, ref, name}[]` via `plan_cards` — `ref` is the plan's `PLN-<id>`). Within a `comments` page, comments are ordered CHRONOLOGICALLY (oldest first) — only the requested WINDOW is anchored at the newest end, not the array itself; naming `comments_limit`/`comments_offset` alongside `ids` (the batch form) is refused. Single form: unknown id → 404. Batch form: `{issues: [...], not_found: [...ids]}` — an unknown or deleted id never fails the call.", {
+// DX-3426: field GROUPS replaced by a recursive field TREE (see
+// `./field-tree.ts`) — comment paging now lives INSIDE the tree (a
+// cursor-paged relation, today only `comments`, takes `limit`/`before` in
+// its own nested object) instead of top-level `comments_limit`/
+// `comments_offset`, which is also why the old "ids + comments_* refused"
+// rule is gone: paging is per-relation now, so it works on the batch form
+// too. Kept compact — call `resource_fields({resource:"issue"})` for the
+// full, current list of what `fields` may name, rather than enumerating it
+// here (it would drift the moment a field/relation is added or removed).
+"Fetch one card (`id`) or many (`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 THE ALWAYS-ON FIELDS ONLY — identity, lifecycle stamps, derived status/list/blocked, assigned_agent, and content_hash (the concurrency token issue_edit needs for title/description/checklists); every child hash is likewise always returned. `fields` opts into more, per card in a batch too: a JSON object tree — each key names a field or relation, each value is `true` (that field, or a relation's child with its default fields), a nested object (a relation's child with named fields), or on the cursor-paged `comments` relation the nested object may also carry `limit`/`before` (comment id) to page — e.g. `{\"description\": true, \"problems\": {\"solutions\": {\"steps\": true}}, \"comments\": {\"limit\": 10}}`; a paged response also carries `comments_page: {limit, total, next_cursor}` (`next_cursor` → pass back as `before` for the next older page, null = none). Call `resource_fields({resource:\"issue\"})` for exactly what may be requested (every field/relation name, each relation's own child resource, and its paging shape if any) — never guess a name. Unknown field/relation → 400 `unknown_field`; bad shape → 400 `invalid_fields`; bad `limit`/`before` → 400 `invalid_field_argument`; a field you lack permission for → 403 `forbidden_field`. 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("Field groups to add; absent = minimal scalars."),
-    comments_limit: z
-        .number()
-        .int()
-        .positive()
+    fields: fieldTreeSchema
         .optional()
-        .describe("Single-id form only. How many comments the page holds (server default 20), the window anchored at the " +
-        "NEWEST comment. An out-of-range value (server max 200) is refused by the server with its own 400, " +
-        "never silently clamped here. Requires `fields:[\"comments\"]`."),
-    comments_offset: z
-        .number()
-        .int()
-        .nonnegative()
-        .optional()
-        .describe("Single-id form only. Skip this many of the newest comments before the page starts (default 0) — page " +
-        "forward while comments_offset + comments.length < comments_total to reach older comments. Requires " +
-        "`fields` to include `comments`."),
+        .describe("A field tree (see tool description); absent/empty = minimal scalars. `resource_fields({resource:\"issue\"})` names every valid key."),
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
+// ---------------- resource_fields ----------------
+strictTool("resource_fields", "DX-3426: what a field TREE (`issue_get`'s `fields`, and any later tool that takes one) may name for one resource — `{resource, description, always: string[], hashes: string[], fields: [{name, description}], relations: [{name, description, resource, paging?: {default_limit, max_limit, page_field}}]}`. `always`/`hashes` ride every response regardless of `fields` (never request them). A relation's `resource` names what to call this same tool with next, to go one level deeper. Install-global, not board-scoped. `resource: \"issue\"` is the root; unknown resource → 404 `unknown_resource`.", {
+    resource: z.string().min(1).describe('Resource name, e.g. "issue", or a relation\'s own `resource` from a prior call.'),
+}, async (args) => jsonResult(await resourceFields(client, args)));
 // ---------------- issue_create ----------------
 strictTool("issue_create", '`plan` is REQUIRED on every create — no default, no inference; see its own field description for the two values and the refusal. This replaces the plan_add_card follow-up at creation time; plan_add_card remains for putting an EXISTING card on a plan. ' +
     'Create a card. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `quality_gates` adds gates beyond the board\'s type defaults (see its own field description); add one later with `issue_quality_gate`. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child (see its own field description).', {
@@ -657,11 +650,39 @@ const STEP_INPUT = z.lazy(() => z
     steps: z.array(STEP_INPUT).optional().describe("this step's own children, nested — refused past 3 levels total"),
 })
     .strict());
-strictTool("issue_problem", "A card's PROBLEMS: one statement the operator must resolve (a question, or a flaw in the plan) OR an action only a person can carry out, each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — adding a problem IS putting the card in front of a human, there is no separate flag. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]}; add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus a `reminders: [{key, text}]` array (DX-3365 — every MCP-response reminder rides this ONE field now, DB-registry-driven and operator-overridable from the dashboard) naming each still-open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard. `statement` is capped at 200 characters (400 names the actual length otherwise): one plain sentence, with any investigation detail in `context` (markdown, no cap) instead. Read `type`'s and `summary`'s own descriptions below before your first `add` — together they teach which type this is and the three-field split (`statement`/`summary`/`context`) an action needs.", {
+strictTool("issue_problem", "A card's PROBLEMS: one statement the operator must resolve (a question, or a flaw in the plan) OR an action only a person can carry out, each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — adding a problem IS putting the card in front of a human, there is no separate flag. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]} (each decision carries `relayed_by_session`, DX-3471 — the working session that recorded it, or null for one entered directly in the dashboard); add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus a `reminders: [{key, text}]` array (DX-3365 — every MCP-response reminder rides this ONE field now, DB-registry-driven and operator-overridable from the dashboard) naming each still-open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. " +
+    "DX-3471 — answer :pid {solution_id, note?} | {freeform} records the operator's decision on a LIVE problem (exactly one of solution_id/freeform; note only qualifies a chosen solution); change_answer :pid {base_hash, solution_id, note?} | {base_hash, freeform} retracts the current decision and records a new one in ONE server transaction; unanswer :pid {base_hash} retracts with no new answer, reopening the problem. `base_hash` on these two names the live DECISION (from that problem's `decisions[].content_hash` in `list`), NOT the problem's own hash — a stale one → 409 `stale_decision` with currentHash + currentDecision: merge, then retry. " +
+    "**These three are OPERATOR-SESSION ONLY** — the server refuses a dispatched agent's machine credential 403 (DX-2830: an agent that could answer its own question could release the very human gate it set to stop and wait for); call them only when relaying a decision the OPERATOR actually made in this chat, never a decision you are making yourself. Session attribution is automatic (the same `x-danx-session-id` every call already carries, DX-2683) — no session parameter to pass here. " +
+    "`statement` is capped at 200 characters (400 names the actual length otherwise): one plain sentence, with any investigation detail in `context` (markdown, no cap) instead. Read `type`'s and `summary`'s own descriptions below before your first `add` — together they teach which type this is and the three-field split (`statement`/`summary`/`context`) an action needs.", {
     id: z.string().min(1),
-    action: z.enum(["list", "add", "edit", "remove"]),
-    problem_id: z.number().int().positive().optional().describe("edit/remove"),
-    base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove"),
+    action: z.enum(["list", "add", "edit", "remove", "answer", "change_answer", "unanswer"]),
+    problem_id: z.number().int().positive().optional().describe("edit/remove/answer/change_answer/unanswer"),
+    base_hash: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("edit/remove: content_hash last read for the PROBLEM. change_answer/unanswer: content_hash last read for " +
+        "the live DECISION instead (that problem's `decisions[].content_hash` from `list`) — the two are never " +
+        "interchangeable."),
+    solution_id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("answer/change_answer only. The chosen option's id, from this problem's own solutions[]. Exactly one of " +
+        "solution_id / freeform — never both, never neither (refused before any request)."),
+    note: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("answer/change_answer only, solution_id answers only: an optional qualification (\"this, but…\"). Refused " +
+        "alongside freeform, which is already the operator's own words."),
+    freeform: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("answer/change_answer only. The operator's own words, when no listed solution fits. Exactly one of " +
+        "solution_id / freeform — never both, never neither."),
     statement: z
         .string()
         .min(1)

package/package.json

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