@thehammer/danx-dashboard-mcp 0.1.162 → 0.1.164

package/dist/handlers.js

@@ -21,886 +21,169 @@
  * decide its next move; swallowing any of it would force the agent to
  * guess.
  */
-import { readFile } from "node:fs/promises";
 import { basename, extname, isAbsolute } from "node:path";
-import { resolvePriority } from "./priority.js";
-/**
- * `filter`/`fields`/`sort` are JSON-encoded onto the query string (the route
- * parses `?filter=<JSON>`, `?fields=<JSON>`, `?sort=<JSON>` — see
- * `src/issues/read/reader.ts#parseEnvelope` + `handleGetIssues`); each is
- * omitted entirely when empty so the wire carries no `{}`/`[]` noise. `board`
- * stays a flat top-level param, resolved by the HTTP client exactly as
- * before.
- */
-export async function issueList(client, args) {
-    const query = {};
-    if (args.filter !== undefined && Object.keys(args.filter).length > 0) {
-        query.filter = JSON.stringify(args.filter);
-    }
-    // DX-3427 — a JSON-encoded field tree, mirroring `issue_get` below.
-    if (args.fields !== undefined && Object.keys(args.fields).length > 0) {
-        query.fields = JSON.stringify(args.fields);
-    }
-    if (args.sort !== undefined && args.sort.length > 0) {
-        query.sort = JSON.stringify(args.sort);
-    }
-    if (args.limit !== undefined)
-        query.limit = args.limit;
-    if (args.offset !== undefined)
-        query.offset = args.offset;
-    // DX-1171 — board-only: forward the qualified board id, no repo.
-    return client.request({ method: "GET", path: "", query, board: args.board });
-}
-// ---------------- issue_get ----------------
-/**
- * The most distinct ids one batch `issue_get` may name — mirrors the server's
- * `src/issues/list-page.ts#ISSUE_BATCH_GET_MAX` (the batch route 400s above it);
- * `__tests__/handlers.test.ts` asserts the two agree.
- */
-export const ISSUE_BATCH_GET_MAX = 100;
-/**
- * The largest page any paged list read accepts (`issue_list`'s `limit`,
- * `plan_get`'s `cards_limit`) — mirrors the server's
- * `src/issues/list-page.ts#MAX_LIMIT` (it 400s above it);
- * `__tests__/handlers.test.ts` asserts the two agree.
- */
-export const LIST_PAGE_MAX_LIMIT = 1000;
+import { readFile } from "node:fs/promises";
+// ---------------- plan_connect (DX-2683) ----------------
+// DX-3465 (PLN-11 R-25) — every other per-operation handler that used to
+// live in this file (issue_*, plan_* except plan_connect, brief_*,
+// repo_knowledge_*, failure_category_*, dispatch_transcript_search,
+// quality_gate_instruction) is deleted: `danxbotApi`/`danxbotApiSpec` below
+// are the generic replacement. `plan_connect` stays a dedicated tool because
+// it is session-bound (see `index.ts`'s own comment on this).
+const PLAN_SESSIONS_BASE_PATH = "/api/plan-sessions";
 /**
- * Fetch one card via `GET /api/issues/:id`, or many via
- * `GET /api/issues/batch?ids=...` (DX-2727) — a real batch read that keeps
- * the single-id route's global, cross-board resolution rather than routing
- * through `issue_list` (board-scoped per call, and its filter has no `id`
- * property). Exactly one of `id` / `ids` must be given; the batch form
- * reports a per-id `not_found` list rather than failing the whole call. The
- * batch form is a global read with no board scope, so `ids` together with
- * `board` is REFUSED here rather than `board` being silently dropped.
+ * Connect THIS session to a plan — the same write the operator's Connect
+ * action performs, reaching the same server-side code path. `me` in the URL
+ * is resolved from the forwarded session id, so this can only ever bind the
+ * caller's own session.
+ *
+ * A session already on another plan is MOVED, and the response says which
+ * plan it left (`movedFrom`).
+ *
+ * IT DOES NOTHING ABOUT HEARING THE PLAN'S EVENTS, deliberately. Delivery belongs
+ * to the danxbot Claude Code plugin's plan event bridge, a background process
+ * that holds the session's ONE listener ticket and starts when this tool
+ * succeeds. The dashboard keeps one ticket per session, so a ticket minted here
+ * would end the bridge's stream.
+ *
+ * `title` (DX-2816) rides here, not on a header, because the AGENT — not this
+ * server — is the one thing able to read Claude's own session title (via a
+ * Desktop-side `get_session` tool no MCP server subprocess can call). Sent
+ * only when the caller supplied one; the server leaves an unset title alone.
  */
-export async function issueGet(client, args) {
-    if (args.id !== undefined && args.ids !== undefined) {
-        throw new Error("issue_get: pass exactly one of id or ids, not both");
-    }
-    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");
-    }
-    const query = {};
-    // 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) {
-            throw new Error("issue_get: ids must be a non-empty array");
-        }
-        query.ids = args.ids.join(",");
-        // DX-2727 — the batch route resolves globally, exactly like the
-        // single-id path (see its own doc comment): no `board` is forwarded.
-        return client.request({ method: "GET", path: "/batch", query });
-    }
-    if (args.id === undefined) {
-        throw new Error("issue_get: pass exactly one of id or ids");
-    }
-    return client.request({
-        method: "GET",
-        path: `/${encodeURIComponent(args.id)}`,
-        query,
-        board: args.board,
-    });
-}
-export async function issueCreate(client, args, defaultBoard) {
-    // Resolve the target board ONCE: per-call `args.board` override (a
-    // qualified `<repo>:<slug>` id) wins, else the dispatch's env-derived
-    // board. `board` lives in BOTH the query string (via http-client) AND
-    // the body (the create route reads it from the JSON envelope, as
-    // `repo` did pre-DX-1171). Sending only one fails-loud — the
-    // duplication is intentional. The dashboard owns board→repo and 404s
-    // an unknown board.
-    const board = args.board ?? defaultBoard;
-    const body = {
-        board,
-        type: args.type,
-        title: args.title,
-        description: args.description,
-        // DX-3006 — forwarded UNCONDITIONALLY, alongside the other required
-        // fields, never behind an `if (… !== undefined)` like the optional ones
-        // below. Zod has already refused a call that omitted it, so there is
-        // nothing to coalesce here: whatever the caller decided, including an
-        // explicit null, is what the route receives.
-        plan: args.plan,
-    };
-    if (args.summary !== undefined)
-        body.summary = args.summary;
-    if (args.parent_id !== undefined)
-        body.parent_id = args.parent_id;
-    if (args.ac !== undefined)
-        body.ac = args.ac;
-    if (args.effort_level !== undefined)
-        body.effort_level = args.effort_level;
-    // DX-3238 — same tier-word → numeric midpoint resolution `issueEdit` does;
-    // the route only ever accepts a number (`parsePriority`, `create.ts:545`).
-    if (args.priority !== undefined)
-        body.priority = resolvePriority(args.priority);
-    if (args.list_id !== undefined)
-        body.list_id = args.list_id;
-    if (args.quality_gates !== undefined)
-        body.quality_gates = args.quality_gates;
-    // DX-1895 (explicit-only) — forward the caller's explicit auto-triage
-    // decision; the server stamps false when absent (never auto-triaged).
-    // Per-child flags ride along inside phase_children entries verbatim.
-    if (args.triage_enabled !== undefined)
-        body.triage_enabled = args.triage_enabled;
-    if (args.phase_children !== undefined)
-        body.phase_children = args.phase_children;
-    return client.request({ method: "POST", path: "", body, board });
-}
-export async function issueEdit(client, args) {
-    // `board` is a transport concern (query), NOT a patch field — pull it
-    // out of `rest` so it never leaks into the `/edit` body (the server
-    // 400s on non-allowlisted keys). `priority` is pulled out separately so it
-    // can be resolved (tier word → numeric) before it reaches the body.
-    const { id, board, priority, ...rest } = args;
-    // Strip undefined so we don't send `{title: undefined}` — JSON.stringify
-    // drops them anyway but explicit is clearer.
-    const body = {};
-    for (const [k, v] of Object.entries(rest)) {
-        if (v !== undefined)
-            body[k] = v;
-    }
-    // DX-1532 — resolve a tier WORD to its numeric midpoint (inverse of
-    // priorityTier); a raw number passes through for the route to range-validate.
-    // Omitted (undefined) → never sent, so a prose-only edit is unchanged.
-    if (priority !== undefined) {
-        body.priority = resolvePriority(priority);
-    }
-    return client.request({
-        method: "PATCH",
-        path: `/${encodeURIComponent(id)}/edit`,
-        body,
-        board,
-    });
-}
-export async function issueTransition(client, args) {
-    const { id, board, ...body } = args;
-    // DX-2735 / DX-2830: 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 add, which
-    // carries its own reminder.
-    return client.request({
-        method: "POST",
-        path: `/${encodeURIComponent(id)}/transition`,
-        body,
-        board,
-    });
-}
-export async function issueTriage(client, args) {
-    const { id, board, ...body } = args;
+export async function planConnect(client, args) {
     return client.request({
         method: "POST",
-        path: `/${encodeURIComponent(id)}/triage`,
-        body,
-        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 — 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;
+        path: "/me/plan",
+        basePath: PLAN_SESSIONS_BASE_PATH,
+        body: {
+            plan_id: args.plan_id,
+            ...(args.title === undefined ? {} : { title: args.title }),
         },
-    };
-}
-/**
- * Every action-dispatched tool's args carry these three regardless of
- * `action` — never action-specific, so every per-action allow-list passed to
- * `refuseInapplicableFields` is unioned with this rather than repeating it.
- */
-const STRUCTURAL_ACTION_FIELDS = ["id", "action", "board"];
-/**
- * DX-3310 (code-review nit) — a field the caller sent that means nothing for
- * the chosen `action` used to be silently ignored: `issue_solution`'s `add`
- * built its `content` object from `title`/`body`/`pro`/`con`/`recommended`
- * regardless of action, then simply never read it on `remove`/`add_step`/etc,
- * and `issue_problem`'s `remove` never looked at `statement`/`context`/
- * `solutions` at all. Either way the caller got a 200 with the field quietly
- * discarded — no different from a typo. Refused loud instead, mirroring
- * `argCheckers`' own wording: every ACTUALLY-SUPPLIED (`!== undefined`) key
- * outside the action's own allow-list (plus `STRUCTURAL_ACTION_FIELDS`,
- * always allowed) is named in one error, so a caller fixes every offending
- * field in one round trip rather than one at a time.
- */
-// A9 (code-review fix) — takes `object` rather than `Record<string, unknown>`
-// so every caller (each with its own specific `*Args` interface, no index
-// signature) passes `args` directly, with no `as unknown as Record<...>`
-// bridge cast at the call site. `Object.entries` reads the key/value pairs
-// without needing an index signature on the input type either.
-function refuseInapplicableFields(tool, mode, args, allowed) {
-    const offending = Object.entries(args)
-        .filter(([key, value]) => value !== undefined && !STRUCTURAL_ACTION_FIELDS.includes(key) && !allowed.has(key))
-        .map(([key]) => key)
-        .sort();
-    if (offending.length > 0) {
-        throw new Error(`${tool} ${mode} refuses fields that do not apply to this action: ${offending.join(", ")}`);
-    }
-}
-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") {
-        const text = need.string(args.text, "text");
-        return client.request({
-            method: "POST",
-            path: `/${idEnc}/comments`,
-            body: {
-                text,
-                ...(args.metadata !== undefined ? { metadata: args.metadata } : {}),
-                ...(args.problem_id !== undefined ? { problem_id: args.problem_id } : {}),
-            },
-            board,
-        });
-    }
-    if (args.action === "edit") {
-        const commentId = need.id(args.comment_id, "comment_id");
-        const text = need.string(args.text, "text");
-        return client.request({
-            method: "PATCH",
-            path: `/${idEnc}/comments/${commentId}`,
-            body: { text },
-            board,
-        });
-    }
-    // delete
-    const commentId = need.id(args.comment_id, "comment_id");
-    return client.request({
-        method: "DELETE",
-        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") {
-        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,
-                target_id: targetId,
-                reason: args.reason ?? "",
-            },
-            board,
-        });
-    }
-    // remove
-    const dependencyId = need.id(args.dependency_id, "dependency_id");
-    return client.request({
-        method: "DELETE",
-        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
-        // arg-validation, not a confusing 400 envelope.
-        body: { reason: "recorded_in_error" },
-        board,
     });
 }
+// ---------------- resource_fields (DX-3426) ----------------
+const RESOURCES_BASE_PATH = "/api/resources";
 /**
- * DX-2845 — mark a card's own `card/<id>` branch RETIRED (unsafe to merge)
- * via POST /api/issues/:id/card-branch-retire {reason}. NO status/terminal
- * gate on the server side — settable the moment a branch is judged unsafe,
- * whether the card is ToDo, In Progress, or anything else (see
- * `retireCardBranch`'s doc comment, `src/issues/write/card-branch-retire.ts`).
- * `by` is server-stamped from the resolved writing identity, never
- * client-supplied. Idempotent: retiring an already-retired branch just
- * re-stamps reason/actor/timestamp.
+ * `GET /api/resources/:resource/fields` — what a field TREE (the `fields`
+ * arg on `GET /api/issues/:id`, and any later route built on the same shape)
+ * may name for ONE resource: `{resource, description, always, hashes,
+ * fields, relations}`. Install-global (no `board` — the failure-category
+ * list route is board-less the same way: nothing server-side would read one).
+ * Unknown resource → 404 `unknown_resource`.
  */
-export async function issueRetireBranch(client, args) {
+export async function resourceFields(client, args) {
     return client.request({
-        method: "POST",
-        path: `/${encodeURIComponent(args.id)}/card-branch-retire`,
-        body: { reason: args.reason },
-        board: args.board,
+        method: "GET",
+        path: `/${encodeURIComponent(args.resource)}/fields`,
+        basePath: RESOURCES_BASE_PATH,
     });
 }
-/**
- * DX-1362 — targeted checklist CUD. Action-dispatched onto the
- * `/api/issues/:id/checklists[/:cid[/items[/:iid]]]` route family so an agent
- * mutates ONE checklist or item without the wholesale `issue_edit({checklists})`
- * replace (which silently drops any omitted checklist + churns every item id).
- * A missing required arg for the chosen action throws at this boundary (no
- * round-trip). The dashboard's structured error envelope passes through verbatim.
- */
-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": {
-            const body = { name: need.string(args.name, "name") };
-            if (args.items !== undefined)
-                body.items = args.items;
-            return client.request({
-                method: "POST",
-                path: `/${idEnc}/checklists`,
-                body,
-                board,
-            });
-        }
-        case "update_list": {
-            const checklistId = need.id(args.checklist_id, "checklist_id");
-            const name = need.string(args.name, "name");
-            return client.request({
-                method: "PATCH",
-                path: `/${idEnc}/checklists/${checklistId}`,
-                body: { name },
-                board,
-            });
-        }
-        case "remove_list": {
-            const checklistId = need.id(args.checklist_id, "checklist_id");
-            return client.request({
-                method: "DELETE",
-                path: `/${idEnc}/checklists/${checklistId}`,
-                board,
-            });
-        }
-        case "add_item": {
-            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/${checklistId}/items`,
-                body,
-                board,
-            });
-        }
-        case "update_item": {
-            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;
-            if (args.detail !== undefined)
-                body.detail = args.detail;
-            if (args.status !== undefined)
-                body.status = args.status;
-            return client.request({
-                method: "PATCH",
-                path: `/${idEnc}/checklists/${checklistId}/items/${itemId}`,
-                body,
-                board,
-            });
-        }
-        case "remove_item": {
-            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) 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. DX-2830 — a card
- * needs a human exactly when it has an open problem, so `add` IS the moment a
- * card is put in front of one; the reminder that used to ride the retired
- * `issue_requires_human({set: true})` now rides here instead.
- *
- * DX-2942 — `statement` is capped at 200 characters server-side (a 400 names
- * the actual length otherwise); `context` is the markdown detail behind it,
- * sent only when given on `add`, and on `edit` `undefined` keeps the stored
- * context while `null` clears it — the same omit/null semantics
- * `plan_update_record` already gives a plan record's context.
- *
- * DX-3309 — `add` also takes `type`: `question` (the operator decides) or
- * `action` (only a person can carry it out). Sent only when given — the
- * server itself defaults an omitted value to `question`, so a caller that
- * predates this field keeps creating exactly what it always created. It is
- * set once, at creation, and never editable afterward. The FULL teaching
- * text (the could-I-do-this-myself test, and what `statement`/`context`/
- * `solutions[]` mean under each type) lives on the tool's own `type` field
- * `.describe()` in `index.ts` — that description, not this comment, is what
- * a calling agent actually reads.
- *
- * 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`.
- * `id`/`action`/`board` are structural and never listed (every action takes
- * them). `type` is listed under `edit` even though it can never actually be
- * SENT there (see the dedicated throw below) — that keeps the generic
- * refusal from firing first with a less specific message than the one that
- * already names the real reason.
- */
-const PROBLEM_ACTION_FIELDS = {
-    list: [],
-    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);
-    const board = args.board;
-    const need = argCheckers("issue_problem", `action=${args.action}`);
-    refuseInapplicableFields("issue_problem", `action=${args.action}`, args, new Set(PROBLEM_ACTION_FIELDS[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.context !== undefined)
-                body.context = args.context;
-            // DX-3309 — sent only when given; the server itself defaults an omitted
-            // value to "question" (today's behavior, unchanged for any caller that
-            // doesn't yet know about this field).
-            if (args.type !== undefined)
-                body.type = args.type;
-            // DX-3309 (follow-up) — sent only when given; the server itself refuses
-            // an `action` add with no summary (400 naming the field), and defaults
-            // an omitted `question` summary to absent (`null`).
-            if (args.summary !== undefined)
-                body.summary = args.summary;
-            if (args.solutions !== undefined)
-                body.solutions = args.solutions;
-            // DX-3365 — the server's own response now carries the reminder (a
-            // `reminders: [{key, text}]` field appended by the registry
-            // middleware, `src/issues/reminders/middleware.ts`); this used to be an
-            // EXTRA client-side GET (`withProblemsReminder`, deleted) computing the
-            // identical text a request round-trip later. Passed through verbatim —
-            // no dual path.
-            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");
-            // DX-3309 (test-review follow-up) — `type` is set once, at creation,
-            // and never editable afterward; the HTTP edit route already refuses it
-            // as an unknown key. This call used to silently DROP `type` on edit
-            // (it was never read from `args` here at all), so an agent
-            // "changing" question -> action got a 200 back with the type
-            // unchanged, no error, no signal anything was ignored. Fail loud
-            // instead: the fix for a wrong type is remove + re-add, never edit.
-            if (args.type !== undefined) {
-                throw new Error("issue_problem edit: type cannot be changed after creation — remove this problem and add a new one with the correct type");
-            }
-            return client.request({
-                method: "PATCH",
-                path: `/${idEnc}/problems/${problemId}`,
-                body: {
-                    base_hash: baseHash,
-                    statement,
-                    ...(args.context === undefined ? {} : { context: args.context }),
-                    ...(args.summary === undefined ? {} : { summary: args.summary }),
-                },
-                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}/problems/${problemId}`,
-                body: { base_hash: baseHash },
-                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]]`
- * — 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`/`stale_step` with the current row, a
- * second recommendation on the same problem, editing a chosen option, a
- * 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 — 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"],
-    edit: ["solution_id", "base_hash", "title", "body", "pro", "con", "recommended", "steps", "steps_base_hash"],
-    remove: ["solution_id", "base_hash"],
-    add_step: ["solution_id", "title", "description", "parent_step_id", "position"],
-    edit_step: ["solution_id", "step_id", "base_hash", "title", "description"],
-    remove_step: ["solution_id", "step_id", "base_hash"],
-};
-export async function issueSolution(client, args) {
-    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");
-    // DX-3310 (nit) — `problem_id` is unioned in here rather than listed in
-    // every `SOLUTION_ACTION_FIELDS` entry: unlike `issue_problem` (where it
-    // only applies to edit/remove), `issue_solution` requires it for every
-    // action (checked above), so it is structural FOR THIS TOOL specifically.
-    refuseInapplicableFields("issue_solution", `action=${args.action}`, args, new Set(["problem_id", ...SOLUTION_ACTION_FIELDS[args.action]]));
-    const base = `/${encodeURIComponent(args.id)}/problems/${problemId}/solutions`;
-    const board = args.board;
-    const content = {};
-    for (const key of ["title", "body", "pro", "con", "recommended"]) {
-        if (args[key] !== undefined)
-            content[key] = args[key];
-    }
-    switch (args.action) {
-        case "add": {
-            // DX-2735: the POST carries the CHECKED title, not a re-read of args.title.
-            const title = need.string(args.title, "title");
-            // DX-3310 — omitted `steps` on add means "no steps", not "leave
-            // untouched" (there is nothing yet to leave untouched on a brand new
-            // solution) — sent through only when the caller actually supplied it,
-            // so an existing add-only caller that never heard of `steps` keeps
-            // creating exactly what it always created.
-            if (args.steps !== undefined)
-                content.steps = args.steps;
-            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");
-            // DX-3310 — omitted keeps the stored steps untouched; an explicit
-            // (including empty) array replaces them via the server's diff.
-            if (args.steps !== undefined) {
-                content.steps = args.steps;
-                // B2 (code-review fix) — REQUIRED alongside `steps`, checked here
-                // (not only by the server) so a caller gets the teaching error at
-                // this boundary rather than a round trip for something this client
-                // already knows is missing.
-                content.steps_base_hash = need.string(args.steps_base_hash, "steps_base_hash");
-            }
-            return client.request({
-                method: "PATCH",
-                path: `${base}/${solutionId}`,
-                body: { base_hash: baseHash, ...content },
-                board,
-            });
-        }
-        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}/${solutionId}`,
-                body: { base_hash: baseHash },
-                board,
-            });
-        }
-        // DX-3310 (AC 35250) — granular single-step CUD, so changing one step
-        // never requires resending the whole `steps` tree.
-        case "add_step": {
-            const solutionId = need.id(args.solution_id, "solution_id");
-            const title = need.string(args.title, "title");
-            const body = { title };
-            if (args.description !== undefined)
-                body.description = args.description;
-            if (args.parent_step_id !== undefined)
-                body.parent_step_id = args.parent_step_id;
-            if (args.position !== undefined)
-                body.position = args.position;
-            return client.request({ method: "POST", path: `${base}/${solutionId}/steps`, body, board });
-        }
-        case "edit_step": {
-            const solutionId = need.id(args.solution_id, "solution_id");
-            const stepId = need.id(args.step_id, "step_id");
-            const baseHash = need.string(args.base_hash, "base_hash");
-            const body = { base_hash: baseHash };
-            if (args.title !== undefined)
-                body.title = args.title;
-            if (args.description !== undefined)
-                body.description = args.description;
-            return client.request({ method: "PATCH", path: `${base}/${solutionId}/steps/${stepId}`, body, board });
-        }
-        case "remove_step": {
-            const solutionId = need.id(args.solution_id, "solution_id");
-            const stepId = need.id(args.step_id, "step_id");
-            const baseHash = need.string(args.base_hash, "base_hash");
-            return client.request({
-                method: "DELETE",
-                path: `${base}/${solutionId}/steps/${stepId}`,
-                body: { base_hash: baseHash },
-                board,
-            });
-        }
-    }
-}
-/**
- * Put ONE quality gate on a card, or take it off, via
- * POST /api/issues/:id/quality-gates/:gate {action} — the same write the
- * dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY
- * post-create path to change a card's gates: `issue_create` names them at
- * birth via `quality_gates`, and `issue_edit` rejects gate keys.
- *
- * `gate` is a registry name (`plan-dependency` | `plan-architecture` |
- * `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality`).
- * An unknown gate is a 400 from the server (never a silent no-op), as is a
- * card whose type is never gated (`Epic` / `Feature` / `Task`).
- *
- * DX-3015 — there is no board tri-state to reason about any more. A gate is on
- * the card or it is not, and every gate on a card is required, so `add` always
- * means "this gate now runs on this card" and `remove` always means it does
- * not. What the board still owns is the DEFAULT SET a NEW card is born with;
- * it has no say over a card that already exists.
- *
- * Because of that, the response is plain `{issue}`. The old body carried
- * `{applied, effective, reason}` because the per-card flag was only one of
- * three inputs and the board could silently make the write a no-op — with the
- * tri-state gone, the write IS the outcome and those fields would be constants.
- *
- * `note` records why the gate is on the card; `effort_level` (DX-1760) sets
- * `card_quality_gates.effort_level` (`null` clears a prior override). Both are
- * `add`-only — the server 400s either one alongside `remove`, since a removed
- * gate has no row to carry them.
- *
- * Re-adding a gate the card already carries updates `note`/`effort_level` and
- * leaves any recorded verdict untouched, so `add` is never a way to quietly
- * clear a `fail`. `remove` DOES discard the row and its verdict.
- */
-export async function issueQualityGate(client, args) {
-    const body = { action: args.action };
-    if (args.note !== undefined)
-        body.note = args.note;
-    if (args.effort_level !== undefined)
-        body.effort_level = args.effort_level;
-    return client.request({
-        method: "POST",
-        path: `/${encodeURIComponent(args.id)}/quality-gates/${encodeURIComponent(args.gate)}`,
-        body,
+// ---------------- danxbot_api (DX-3465, PLN-11 R-25) ----------------
+export const DANXBOT_API_METHODS = ["GET", "POST", "PATCH", "PUT", "DELETE"];
+export function isDanxbotApiMethod(value) {
+    return typeof value === "string" && DANXBOT_API_METHODS.includes(value);
+}
+/**
+ * `danxbot_api({method, path, query, body})` — the ONE generic tool that
+ * reaches every dashboard API route this credential is allowed to call
+ * (R-25, DX-3465). Replaces the ~45 per-operation tools this package used to
+ * ship one-for-one against each route: a new route needs a permission and a
+ * spec entry (`danxbot_api_spec`), never a new tool.
+ *
+ * The credential lives inside `client` (resolved once at boot — the
+ * operator's declared token file for a session, the per-dispatch
+ * `DANXBOT_DISPATCH_TOKEN` for a worker) and never appears in this
+ * function's arguments or return value — nothing in `DanxbotApiArgs` can
+ * carry one. The session id (`x-danx-session-id`) rides every call the SAME
+ * way it already does for every other tool on this server
+ * (`http-client.ts#request` stamps it from `config.session`); this tool adds
+ * no special-casing for that.
+ *
+ * `path` MUST start with `/api/` — this is a guardrail against a caller
+ * accidentally reaching for something outside the dashboard's own API
+ * surface (there is nothing else this credential could reach through
+ * `client`'s configured `baseUrl` that would make sense to call this way),
+ * not a route allowlist: the dashboard's own route policy (`authorize()`,
+ * `src/dashboard/route-policy.ts`) is the actual authorization boundary —
+ * an unknown or unauthorized route 404s/401s/403s exactly as it would to any
+ * other caller, and that refusal body (which names the fix — CP1) is
+ * returned verbatim, unmodified, like every other route's response.
+ *
+ * The response is the target route's JSON body, VERBATIM — including its
+ * own `reminders[]` field when the route embeds one (every reminder-
+ * registry row is keyed on `{method, route}` now, DX-3465 item 5, so a
+ * route that used to attach a reminder to a deleted per-operation tool's
+ * response still attaches it here, with zero special MCP-side plumbing).
+ */
+export async function danxbotApi(client, args) {
+    return client.request({
+        method: args.method,
+        // `basePath: ""` — `path` here is the FULL absolute path already (see
+        // the tool's own docs), unlike every other handler in this file, which
+        // passes a path RELATIVE to a fixed `basePath` (`/api/issues`,
+        // `/api/plans`, ...). This tool has no fixed base; the caller names the
+        // whole route.
+        basePath: "",
+        path: args.path,
+        query: args.query,
+        body: args.body,
         board: args.board,
     });
 }
+// ---------------- danxbot_api_list (DX-3465 A5, PLN-11 R-25) ----------------
+const ROUTES_BASE_PATH = "/api/routes";
 /**
- * Stamp an operator MANUAL quality-gate verdict via
- * PATCH /api/issues/:id/quality-gates/:gate {status, message} — the same write
- * the dashboard Gates-tab Pass / Fail / Revert controls perform (DX-1373).
- *
- * SIBLING, NOT A REPLACEMENT, of `issueQualityGate` above: they are two
- * distinct operations on one resource, mirroring the server's own verb split.
- * POST flips the per-card `required` FLAG (does this gate run at all); PATCH
- * stamps the VERDICT (did it pass). Neither substitutes for the other, which
- * is why this is a separate tool rather than an overloaded mode on the
- * existing one (CLAUDE.md Core Principle 2 — no dual-shape).
- *
- * DX-2222 — why this tool has to exist. A card cannot reach Done while any
- * required POST gate row is not `pass` (`issue_transition complete` refuses
- * 409 with `failed_gate: "quality_gate_post"`). Until now the ONLY way to
- * write a verdict was the worker route `src/worker/quality-gate-route.ts`,
- * authed by the per-dispatch `DANX_AGENT_TOKEN` that exists only INSIDE a
- * spawned dispatch. An operator/host session (`issue_transition pickup
- * {manual:true}`, DX-946) has no such token, so it could pick a card up and
- * do the work but never close it — every manually-claimed card stranded In
- * Progress, and each stranded card then projects `conflict_on` / `waiting_on`
- * gates onto the ToDo queue, stalling dispatch for cards nobody is working.
- *
- * This route is the RIGHT one to expose for that: its handler
- * (`src/issues/write/quality-gate-verdict.ts`) is a pure, dispatch-less row
- * write authed by the ordinary per-user dashboard bearer — explicitly "NOT
- * the dispatch token — there is no dispatch behind a manual stamp". It does
- * NOT fire the worker route's per-dispatch side effects (`gate_release` on
- * pass, `block` on fail), so a manual verdict can never release or block a
- * dispatch that does not exist.
- *
- * Fail-loud (CP1), all server-side: unknown `gate` → 400; `status` outside
- * pass/fail/pending → 400; a pass/fail whose `message` is under 20 characters
- * → 400, because the note IS the accountability record for a human override.
- * `pending` reverts a prior verdict and clears the message.
+ * `danxbot_api_list()` — the routes YOUR credential may currently call,
+ * `[{method, path, summary, permission}]`, one line each. Backed by DX-3528's
+ * `GET /api/routes`, which filters the served route table through the SAME
+ * `isRouteAuthorizedForPrincipal` check `authorize()` enforces on every
+ * request — a route listed here is always callable, and a route this
+ * credential cannot call never appears. This is how you find the route for
+ * something you need to do: call this first when you don't already know the
+ * path, then `danxbot_api_spec({endpoints})` for the exact contract of the
+ * one(s) you picked, then `danxbot_api` to call it. No arguments — the
+ * server-side route table has no filter to pass.
  */
-export async function issueQualityGateVerdict(client, args) {
-    const body = { status: args.status };
-    if (args.message !== undefined)
-        body.message = args.message;
+export async function danxbotApiList(client) {
     return client.request({
-        method: "PATCH",
-        path: `/${encodeURIComponent(args.id)}/quality-gates/${encodeURIComponent(args.gate)}`,
-        body,
-        board: args.board,
+        method: "GET",
+        path: "",
+        basePath: ROUTES_BASE_PATH,
     });
 }
-// ---------------- quality_gate_instruction ----------------
-const QUALITY_GATE_INSTRUCTION_BASE_PATH = "/api/quality-gates";
+// ---------------- danxbot_api_spec (DX-3465, PLN-11 R-25) ----------------
+const OPENAPI_BASE_PATH = "/api/openapi";
 /**
- * DX-3341 (PLN-11 R-20) — fetch a named gate's CURRENT instruction via
- * GET /api/quality-gates/:gate/instruction. NOT card-scoped (unlike
- * `issue_quality_gate`/`issue_quality_gate_verdict` above) — this reads the
- * gate's DB-catalog SKILL PROSE for the calling session's board/repo, byte-
- * identical to what a dispatched gate reviewer's clean-room materializes at
- * `.claude/skills/<segment>/SKILL.md`. No second source: the dashboard route
- * behind this call reuses the exact same catalog-read + materialize-transform
- * chain a real gate dispatch's clean-room assembly uses.
+ * `danxbot_api_spec({endpoints})` — the exact OpenAPI 3.1 contract (DX-3527)
+ * for the named routes: request/response shapes, required permission/
+ * consumer action, and every documented error envelope. Call this before a
+ * `danxbot_api` call whose shape you are not already sure of — "a 4xx body
+ * names the fix; check the spec" (the MCP server's own shared instructions).
  *
- * Use this to run a quality gate from an operator session (R-19/R-20): fetch
- * the gate's instruction with this tool, dispatch a `danxbot:worker-*` tier
- * chosen by effort with that instruction, review, then record the verdict
- * via `issue_quality_gate_verdict` — never a hand-written review brief.
- *
- * `gate` is a registry name (same enum `issue_quality_gate` accepts). Unknown
- * gate -> 400; a registered gate with no resolvable catalog skill artifact
- * for this repo (a boot-seed/catalog-drift defect) -> 500.
+ * Backed by DX-3528's permission-aware `GET /api/openapi` — the SAME
+ * `isRouteAuthorizedForPrincipal` check `danxbot_api_list` uses, so an
+ * endpoint this credential may not call refuses loud (400
+ * `invalid_endpoints`, naming it under `unknown` or `disallowed`) rather
+ * than silently documenting a route you cannot actually reach.
  */
-export async function qualityGateInstruction(client, args) {
+export async function danxbotApiSpec(client, args) {
     return client.request({
         method: "GET",
-        path: `/${encodeURIComponent(args.gate)}/instruction`,
-        basePath: QUALITY_GATE_INSTRUCTION_BASE_PATH,
-        board: args.board,
-    });
-}
-export async function issueRetro(client, args) {
-    const { id, board, ...body } = args;
-    return client.request({
-        method: "PUT",
-        path: `/${encodeURIComponent(id)}/retro`,
-        body,
-        board,
+        path: "",
+        basePath: OPENAPI_BASE_PATH,
+        query: { endpoints: args.endpoints.join(",") },
     });
 }
 /**
  * Extension → MIME map for the agent-attached file types that matter for
- * downstream rendering (image previews in the dashboard drawer, Trello card,
- * and Slack thread all key on the persisted `mime`). This package is a
- * standalone published artifact and cannot import the backend's helpers, so
- * the small map lives here. An unknown extension resolves to the generic
- * octet-stream — a sensible default for "we don't know the type", NOT a
- * silenced error (the bytes still upload + the row is still written).
+ * downstream rendering (image previews in the dashboard drawer, Trello
+ * card, and Slack thread all key on the persisted `mime`). This package is
+ * a standalone published artifact and cannot import the dashboard
+ * backend's own MIME table, so the small map lives here. An unknown
+ * extension resolves to the generic octet-stream — a sensible default for
+ * "we don't know the type", NOT a silenced error (the bytes still upload +
+ * the row is still written).
  */
 const MIME_BY_EXT = {
     ".png": "image/png",
@@ -921,700 +204,49 @@ const MIME_BY_EXT = {
     ".tgz": "application/gzip",
 };
 export function inferAttachmentMime(filename) {
-    return (MIME_BY_EXT[extname(filename).toLowerCase()] ?? "application/octet-stream");
-}
-/**
- * Attach a local file to an issue card. Reads the bytes from the dispatch's
- * shared filesystem (this MCP server runs co-located with the agent), then
- * forwards to the dashboard's `POST /api/issues/:id/attachments` route — the
- * SAME ingest the dashboard UI upload uses, which uploads to S3, inserts ONE
- * danxbot-origin `issue_attachments` row (`source_type=''`), and publishes
- * `issue:updated` so the DX-1122 outbound projection mirrors the file to both
- * the linked Trello card and the Slack card-view thread.
- *
- * Fail-loud (`base:fail-loudly`): the path is validated (non-empty + absolute)
- * and the file is read BEFORE any HTTP call, so a bad/missing/unreadable path
- * throws here and NEVER reaches S3, the DB row, or the projection. An S3 /
- * server fault on the route surfaces as a 5xx, which the HTTP client throws.
- */
-export async function issueAttach(client, args, deps = {}) {
-    if (typeof args.file_path !== "string" || args.file_path.trim() === "") {
-        throw new Error("issue_attach: file_path must be a non-empty string");
-    }
-    if (!isAbsolute(args.file_path)) {
-        throw new Error(`issue_attach: file_path must be an absolute path (got "${args.file_path}")`);
+    return MIME_BY_EXT[extname(filename).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+ * Attach a local file to a card. Reads the bytes from the dispatch's
+ * shared filesystem (this MCP server runs co-located with the agent that
+ * calls it), then forwards to the dashboard's `POST /api/issues/:id/attachments`
+ * route — the SAME ingest the dashboard UI's own upload uses: stores the
+ * bytes in S3, inserts one attachment row, and (via the dashboard's
+ * existing outbound projection) auto-mirrors the file to the card's
+ * linked Trello card and Slack thread. Board-scoped; see `board`.
+ *
+ * Fail-loud (`base:fail-loudly`): `path` is validated (non-empty +
+ * absolute) and the file is read BEFORE any HTTP call, so a bad/missing/
+ * unreadable path throws here and NEVER reaches S3, the DB row, or the
+ * projection. THE FILE'S BYTES NEVER APPEAR IN THIS FUNCTION'S ARGUMENTS
+ * OR IN THE AGENT'S OWN TRANSCRIPT — they are read directly off disk into
+ * this process's memory and sent straight to the dashboard, the same
+ * privacy property `danxbot_api`'s credential handling has for tokens. An
+ * S3 / server fault on the route surfaces as a 5xx, which the HTTP client
+ * throws.
+ */
+export async function attachFile(client, args, deps = {}) {
+    if (typeof args.path !== "string" || args.path.trim() === "") {
+        throw new Error("attach_file: path must be a non-empty string");
+    }
+    if (!isAbsolute(args.path)) {
+        throw new Error(`attach_file: path must be an absolute path (got "${args.path}")`);
     }
     const read = deps.readFile ?? readFile;
     // A missing / unreadable file rejects here — no HTTP call is made, so no
     // S3 upload, no row insert, and no projection are ever triggered.
-    const bytes = await read(args.file_path);
-    const filename = basename(args.file_path);
+    const bytes = await read(args.path);
+    const filename = args.filename?.trim() ? args.filename.trim() : basename(args.path);
+    const contentType = args.content_type?.trim() ? args.content_type.trim() : inferAttachmentMime(filename);
     return client.request({
         method: "POST",
-        path: `/${encodeURIComponent(args.id)}/attachments`,
+        basePath: "/api/issues",
+        path: `/${encodeURIComponent(args.card_id)}/attachments`,
         body: {
             filename,
-            contentType: inferAttachmentMime(filename),
+            contentType,
             base64: bytes.toString("base64"),
         },
         board: args.board,
     });
 }
-/* ── Plans: what a connected session may read and add to (DX-2683) ────────── */
-const PLANS_BASE_PATH = "/api/plans";
-const PLAN_SESSIONS_BASE_PATH = "/api/plan-sessions";
-/**
- * DX-3428 — every kind the plan resource's `events` relation accepts as a
- * `kinds` filter (`{"events": {"kinds": [...]}}`). The ONE copy in this
- * package (the `resource_fields`-describable `events` relation validates the
- * same set server-side), duplicated from the server's
- * `src/issues/db/plan-events.ts#PLAN_EVENT_KINDS` because the published
- * package cannot import server source at runtime — kept here purely for a
- * CONSUMER'S typed convenience (`PlanEventKind`); the MCP tool schema itself
- * no longer enumerates it (DX-3428 moved `plan_get` onto the generic,
- * resource-agnostic `fieldTreeSchema` every field-tree tool shares — see
- * `field-tree.ts`). `__tests__/handlers.test.ts` asserts the two are equal,
- * so drift fails a test rather than a live call.
- */
-export const PLAN_EVENT_KINDS = [
-    "comment_added",
-    "solution_answered",
-    "problem_added",
-    "problem_unanswered",
-    "problem_answer_changed",
-    "blocked",
-    "unblocked",
-    "transitioned",
-    "edited",
-    "dependency_added",
-    "dependency_removed",
-    "card_created",
-    "plan_created",
-    "plan_renamed",
-    "card_added_to_plan",
-    "card_removed_from_plan",
-    "record_added",
-    "record_updated",
-    "record_removed",
-    "note_added",
-    "note_updated",
-    "note_removed",
-    "architecture_section_added",
-    "architecture_section_updated",
-    "architecture_section_removed",
-    "architecture_sections_reordered",
-    "session_connected",
-    "session_switched_away",
-    "idle_nudge_sent",
-    // DX-3519 — plan sign-off.
-    "plan_signed_off",
-    "plan_sign_off_cleared",
-    "plan_auto_sign_off_changed",
-];
-/**
- * DX-3428 — every origin the `events` relation's `origin` filter accepts.
- * Mirrors the server's `src/issues/db/plan-events.ts#PlanEventOrigin`
- * (itself `ActivityOrigin`) — same drift protection as `PLAN_EVENT_KINDS`
- * above, and likewise kept only for a consumer's typed convenience (not read
- * by the MCP tool schema any more).
- */
-export const PLAN_EVENT_ORIGINS = ["operator", "agent", "machine"];
-/**
- * DX-2834 / DX-3519 — the plan-status taxonomy, mirroring `PLAN_FIELD_GROUPS`
- * just above: the ONE copy in this package (the `plan_list` zod enum in
- * `index.ts` reads this const), duplicated from the server's
- * `src/issues/db/plans.ts#PLAN_STATUS_IDS` because the published package
- * cannot import server source at runtime. `__tests__/handlers.test.ts`
- * asserts the two are equal, so drift fails a test rather than a live call.
- */
-export const PLAN_STATUSES = ["awaiting-session", "planning", "building", "awaiting-sign-off", "complete"];
-/** Every plan, plus which one THIS session is connected to. */
-export async function planList(client, args = {}) {
-    return client.request({
-        method: "GET",
-        path: "",
-        basePath: PLANS_BASE_PATH,
-        query: { status: args.status },
-    });
-}
-/**
- * One plan — its cheap scalars by default, or opt into its cards, its goals
- * + rules + caveats, its architecture sections, its sessions and its event
- * ledger via a field TREE (DX-3428, replacing the retired flat field-GROUP
- * list). One call rather than several, which is what keeps this tool
- * surface small enough to be worth an agent's context even once every part
- * of a plan is opt-in rather than always-on.
- */
-export async function planGet(client, args = {}) {
-    const query = {};
-    // DX-3428 — the tree travels as ONE JSON-encoded query param, exactly like
-    // `issue_get`/`issue_list`'s own `fields` (see `issueGet` above).
-    if (args.fields !== undefined && Object.keys(args.fields).length > 0) {
-        query.fields = JSON.stringify(args.fields);
-    }
-    return client.request({
-        method: "GET",
-        path: args.plan_id === undefined ? "/mine" : `/${args.plan_id}/full`,
-        basePath: PLANS_BASE_PATH,
-        query,
-    });
-}
-/**
- * Connect THIS session to a plan — the same write the operator's Connect
- * action performs, reaching the same server-side code path. `me` in the URL
- * is resolved from the forwarded session id, so this can only ever bind the
- * caller's own session.
- *
- * A session already on another plan is MOVED, and the response says which
- * plan it left (`movedFrom`).
- *
- * IT DOES NOTHING ABOUT HEARING THE PLAN'S EVENTS, deliberately. Delivery belongs
- * to the danxbot Claude Code plugin's plan event bridge, a background process
- * that holds the session's ONE listener ticket and starts when this tool
- * succeeds. The dashboard keeps one ticket per session, so a ticket minted here
- * would end the bridge's stream.
- *
- * `title` (DX-2816) rides here, not on a header, because the AGENT — not this
- * server — is the one thing able to read Claude's own session title (via a
- * Desktop-side `get_session` tool no MCP server subprocess can call). Sent
- * only when the caller supplied one; the server leaves an unset title alone.
- */
-export async function planConnect(client, args) {
-    return client.request({
-        method: "POST",
-        path: "/me/plan",
-        basePath: PLAN_SESSIONS_BASE_PATH,
-        body: {
-            plan_id: args.plan_id,
-            ...(args.title === undefined ? {} : { title: args.title }),
-        },
-    });
-}
-/** Add a goal, rule or caveat to the connected plan. `context` is sent only when given. */
-export async function planAddRecord(client, args) {
-    return client.request({
-        method: "POST",
-        path: "/mine/records",
-        basePath: PLANS_BASE_PATH,
-        body: {
-            kind: args.kind,
-            body: args.body,
-            ...(args.context === undefined ? {} : { context: args.context }),
-        },
-    });
-}
-/** Add an existing card to the connected plan. */
-export async function planAddCard(client, args) {
-    return client.request({
-        method: "POST",
-        path: "/mine/cards",
-        basePath: PLANS_BASE_PATH,
-        body: { card_id: args.card_id },
-    });
-}
-/**
- * Remove a card from a plan, via `DELETE /api/plans/:plan_id/cards/:card_id`
- * — the existing route `plan_add_card`'s sibling. TAKES AN EXPLICIT
- * `plan_id`, unlike `plan_add_card`: this is a membership toggle on a named
- * plan (like `issue_dependency` add/remove), not a write scoped to the
- * caller's connected session, so there is no `/mine` form of it. Idempotent
- * — removing a card that was never a member is a no-op, not an error.
- * Returns the plan's remaining member list.
- */
-export async function planRemoveCard(client, args) {
-    return client.request({
-        method: "DELETE",
-        path: `/${args.plan_id}/cards/${encodeURIComponent(args.card_id)}`,
-        basePath: PLANS_BASE_PATH,
-    });
-}
-/**
- * Rename a plan, via `PATCH /api/plans/:plan_id` `{name}`. TAKES AN
- * EXPLICIT `plan_id` for the same reason `plan_remove_card` does — renaming
- * a plan is not a write scoped to the caller's connected session, it names
- * the plan directly. The new name shows up immediately in `plan_list`.
- */
-export async function planRename(client, args) {
-    return client.request({
-        method: "PATCH",
-        path: `/${args.plan_id}`,
-        basePath: PLANS_BASE_PATH,
-        body: { name: args.name },
-    });
-}
-/**
- * Read ONE section of the plan this session is connected to, via
- * `GET /api/plans/mine/architecture/sections/:sid`. TAKES NO PLAN ID: the
- * plan is resolved from your connected session, same as `plan_add_record`.
- * Useful for a targeted read (skip pulling the whole plan via `plan_get`)
- * and for conflict recovery after a 409 `stale_plan_architecture_section` —
- * though that refusal already carries `currentTitle`/`currentContent`, so a
- * second read is rarely needed for that specific case. Not connected →
- * `{error: "session_not_connected"}`. Unknown/foreign section id → 404.
- */
-export async function planGetArchitectureSection(client, args) {
-    return client.request({
-        method: "GET",
-        path: `/mine/architecture/sections/${args.section_id}`,
-        basePath: PLANS_BASE_PATH,
-    });
-}
-/**
- * Append a section to the connected plan's architecture, via
- * `POST /api/plans/mine/architecture/sections`. TAKES NO PLAN ID, same as
- * `plan_add_record`. The new section sorts after every existing live
- * section — see `plan_reorder_architecture_section` to move it.
- */
-export async function planAddArchitectureSection(client, args) {
-    return client.request({
-        method: "POST",
-        path: "/mine/architecture/sections",
-        basePath: PLANS_BASE_PATH,
-        body: { title: args.title, content: args.content },
-    });
-}
-/**
- * Edit a section's title and/or content, via
- * `PATCH /api/plans/mine/architecture/sections/:sid`. Both `title` and
- * `content` are OPTIONAL — send only whichever changed. `base_hash` MUST be
- * the section's `contentHash` from the immediately-prior `plan_get`/
- * `plan_get_architecture_section`; the server compares it against the row's
- * current hash and, on a mismatch, refuses the write ENTIRELY and fails loud
- * with `{ok: false, status: 409, body: {error:
- * "stale_plan_architecture_section", currentHash, currentTitle,
- * currentContent}}` rather than overwriting whoever wrote in between —
- * `currentTitle`/`currentContent` ride the SAME refusal so you can merge and
- * retry in ONE round trip. TAKES NO PLAN ID: the plan is resolved from your
- * connected session, same as `plan_add_record`.
- */
-export async function planUpdateArchitectureSection(client, args) {
-    return client.request({
-        method: "PATCH",
-        path: `/mine/architecture/sections/${args.section_id}`,
-        basePath: PLANS_BASE_PATH,
-        body: {
-            base_hash: args.base_hash,
-            ...(args.title === undefined ? {} : { title: args.title }),
-            ...(args.content === undefined ? {} : { content: args.content }),
-        },
-    });
-}
-/**
- * Soft-delete a section of the connected plan's architecture, via
- * `DELETE /api/plans/mine/architecture/sections/:sid`. `base_hash` MUST be
- * the section's `contentHash` from the immediately-prior read; a stale hash
- * refuses the delete ENTIRELY (nothing is removed) with the same
- * `{ok: false, status: 409, body: {error: "stale_plan_architecture_section",
- * currentHash, currentTitle, currentContent}}` shape
- * `plan_update_architecture_section` uses — on a mismatch, re-fetch and
- * confirm this is still the section you meant to remove before retrying,
- * never blindly re-send with the fresh hash. TAKES NO PLAN ID. Unknown/
- * foreign/already-deleted section id → 404.
- */
-export async function planDeleteArchitectureSection(client, args) {
-    return client.request({
-        method: "DELETE",
-        path: `/mine/architecture/sections/${args.section_id}`,
-        basePath: PLANS_BASE_PATH,
-        body: { base_hash: args.base_hash },
-    });
-}
-/**
- * Reassign the connected plan's section display order, via
- * `PUT /api/plans/mine/architecture/sections/reorder`. UNGUARDED by content
- * hash, by design: moving a section never changes its (or any other
- * section's) `contentHash`. `order` must name exactly the plan's current
- * live section ids, each once — a partial or foreign list is refused with a
- * 400 rather than silently reordering a subset or dropping a section from
- * view. TAKES NO PLAN ID.
- */
-export async function planReorderArchitectureSection(client, args) {
-    return client.request({
-        method: "PUT",
-        path: "/mine/architecture/sections/reorder",
-        basePath: PLANS_BASE_PATH,
-        body: { order: args.order },
-    });
-}
-/**
- * Create a new, empty plan via `POST /api/plans`. GLOBAL — a plan is not
- * board-scoped, so this takes no board and creates no membership; the caller
- * still owns zero cards, zero records and zero architecture sections until
- * it adds them. This does NOT connect any session to the new plan — call
- * `plan_connect` separately (mirroring how creating a card does not add it to
- * a plan; these are two deliberately separate steps, same as everywhere else
- * in this tool surface).
- */
-export async function planCreate(client, args) {
-    return client.request({
-        method: "POST",
-        path: "",
-        basePath: PLANS_BASE_PATH,
-        body: { name: args.name },
-    });
-}
-/**
- * Read ONE goal/rule/caveat of the plan this session is connected to, via
- * `GET /api/plans/mine/records/:rid`. TAKES NO PLAN ID: the plan is resolved
- * from your connected session, same as `plan_add_record`. Useful both for an
- * ordinary targeted read (skip pulling the whole plan via `plan_get` just to
- * see one record) and for conflict recovery after a 409 `stale_plan_record`
- * — though that refusal already carries `currentBody`, so a second read is
- * rarely needed for that specific case. Not connected →
- * `{error: "session_not_connected"}`. Unknown/foreign record id → 404.
- */
-export async function planGetRecord(client, args) {
-    return client.request({
-        method: "GET",
-        path: `/mine/records/${args.record_id}`,
-        basePath: PLANS_BASE_PATH,
-    });
-}
-/**
- * Edit a goal/rule/caveat of the plan this session is connected to, via
- * `PATCH /api/plans/mine/records/:rid`. The reference (`G-1`, `R-4`,
- * `CAV-12`) NEVER moves — only the text changes. `content_hash` MUST be the
- * record's `contentHash` from the immediately-prior `plan_get`/
- * `plan_get_record`; the server compares it against the row's current hash
- * and, on a mismatch, refuses the write ENTIRELY and fails loud with
- * `{ok: false, status: 409, body: {error: "stale_plan_record", currentHash,
- * currentBody, currentContext}}` rather than overwriting whoever wrote in
- * between. DX-2734: the hash covers body AND context, and `context` is sent
- * only when given (omitted keeps the stored context, `null` clears it).
- * `currentBody` rides the SAME refusal — the same richer shape
- * `stale_plan_architecture_section` carries for a section — so you can
- * merge and retry in ONE round trip without a second `plan_get_record` call.
- * TAKES NO PLAN ID: the plan is resolved from your connected session, same as
- * `plan_add_record`. Not connected → `{error: "session_not_connected"}`.
- */
-export async function planUpdateRecord(client, args) {
-    return client.request({
-        method: "PATCH",
-        path: `/mine/records/${args.record_id}`,
-        basePath: PLANS_BASE_PATH,
-        body: {
-            body: args.body,
-            content_hash: args.content_hash,
-            ...(args.context === undefined ? {} : { context: args.context }),
-        },
-    });
-}
-/**
- * Soft-delete a goal/rule/caveat of the plan this session is connected to,
- * via `DELETE /api/plans/mine/records/:rid`. Its reference (`G-1`, `R-4`,
- * `CAV-12`) is retired PERMANENTLY and never reused by a later record of the
- * same kind. `content_hash` MUST be the record's `contentHash` from the
- * immediately-prior `plan_get`/`plan_get_record`; a stale hash refuses the
- * delete ENTIRELY (nothing is removed) with the same
- * `{ok: false, status: 409, body: {error: "stale_plan_record", currentHash,
- * currentBody}}` shape `plan_update_record` uses. TAKES NO PLAN ID: the plan
- * is resolved from your connected session, same as `plan_add_record`. Not
- * connected → `{error: "session_not_connected"}`. Unknown/foreign/already-
- * deleted record id → 404.
- */
-export async function planDeleteRecord(client, args) {
-    return client.request({
-        method: "DELETE",
-        path: `/mine/records/${args.record_id}`,
-        basePath: PLANS_BASE_PATH,
-        body: { content_hash: args.content_hash },
-    });
-}
-/**
- * Write a milestone note to a plan, via `POST /api/plans/:plan_id/notes`.
- * TAKES AN EXPLICIT `plan_id`, unlike `plan_add_record`/`plan_add_architecture_section`
- * — mirrors `plan_add_card`'s sibling `plan_remove_card`/`plan_rename`: a
- * dispatched worker has no plan connection when it finishes a card, and a
- * card can sit on several plans, so the writer names which one the note
- * belongs to. A note is a MILESTONE, not a log — write one when a card (or a
- * related group of cards) finishes, an important decision lands, or a
- * goal/rule/caveat/architecture section changes meaningfully; routine step
- * progress stays a card comment. Links resolve on read into what they point
- * at (a card's title, a record's ref + body, a section's title) — an unknown
- * card id, an unparseable or foreign record ref, or an unknown or foreign
- * section id is refused 400 naming exactly which one. A card link does NOT
- * require the card to be a member of this plan; a record/section link MUST
- * belong to THIS plan. `author` is stamped server-side from your identity,
- * never sent by you. Unknown plan → 404. Returns the new note plus the
- * plan's latest notes page.
- */
-export async function planAddNote(client, args) {
-    return client.request({
-        method: "POST",
-        path: `/${args.plan_id}/notes`,
-        basePath: PLANS_BASE_PATH,
-        body: {
-            title: args.title,
-            body: args.body,
-            ...(args.card_ids === undefined ? {} : { card_ids: args.card_ids }),
-            ...(args.record_refs === undefined ? {} : { record_refs: args.record_refs }),
-            ...(args.section_ids === undefined ? {} : { section_ids: args.section_ids }),
-        },
-    });
-}
-/**
- * Edit a plan note, via `PATCH /api/plans/:plan_id/notes/:note_id`.
- * `content_hash` MUST be the note's `contentHash` from your last read; on a
- * mismatch nothing is written and you get `{error: "stale_plan_note",
- * currentHash, currentTitle, currentBody, currentLinks}` — merge into those
- * and retry with `content_hash: currentHash`, never blindly. `title`/`body`
- * are each optional and keep their stored value when omitted. The LINK
- * fields are all-or-nothing as a GROUP: omit all three to keep the stored
- * link set untouched; send ANY one of them to REPLACE THE WHOLE SET (never a
- * per-link add/remove — the set is the unit of change). The hash covers
- * title, body AND the link set, so a stale read of any of the three is
- * refused. TAKES AN EXPLICIT `plan_id`, same reason as `plan_add_note`.
- * Unknown plan or note id → 404. Returns the edited note plus the plan's
- * latest notes page.
- */
-export async function planUpdateNote(client, args) {
-    return client.request({
-        method: "PATCH",
-        path: `/${args.plan_id}/notes/${args.note_id}`,
-        basePath: PLANS_BASE_PATH,
-        body: {
-            content_hash: args.content_hash,
-            ...(args.title === undefined ? {} : { title: args.title }),
-            ...(args.body === undefined ? {} : { body: args.body }),
-            ...(args.card_ids === undefined ? {} : { card_ids: args.card_ids }),
-            ...(args.record_refs === undefined ? {} : { record_refs: args.record_refs }),
-            ...(args.section_ids === undefined ? {} : { section_ids: args.section_ids }),
-        },
-    });
-}
-/**
- * Soft-delete a plan note, via `DELETE /api/plans/:plan_id/notes/:note_id`.
- * `content_hash` MUST be the note's `contentHash` from your last read; a
- * stale hash deletes nothing and returns the same `{error:
- * "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}`
- * shape `plan_update_note` uses. TAKES AN EXPLICIT `plan_id`, same reason as
- * `plan_add_note`. Unknown plan, unknown note, or an already-deleted note →
- * 404. Returns the plan's remaining latest notes page.
- */
-export async function planDeleteNote(client, args) {
-    return client.request({
-        method: "DELETE",
-        path: `/${args.plan_id}/notes/${args.note_id}`,
-        basePath: PLANS_BASE_PATH,
-        body: { content_hash: args.content_hash },
-    });
-}
-// ---------------- failure_category_list / _create / _update (DX-2792) ----------------
-/**
- * DX-2792 (Failure evaluation 3/4) — wraps `src/dashboard/failure-categories-routes.ts`,
- * the DX-2791 (Failure evaluation 2/4) category registry's REST API. INSTALL-
- * GLOBAL, not board-scoped: `failure_categories` carries no `board_id`
- * column (every category applies across the whole install), so — unlike
- * every `/api/issues/*`-backed tool above — these three never send a
- * `board` query param and the `board` override field is simply absent from
- * their schemas (mirrors the `plan_*` family's own board-less rationale in
- * `index.ts`'s `boardField` comment, for the same underlying reason: nothing
- * server-side would read it).
- */
-const FAILURE_CATEGORIES_BASE_PATH = "/api/failure-categories";
-/**
- * List every failure category with its live matched-occurrence count and
- * last-seen time, via `GET /api/failure-categories`. Returns
- * `{categories: [{id, name, description, matchers, ignore, ignoreReason,
- * expectedRate, matchedCount, lastSeenMs, ...}]}`. A fresh install returns
- * `{categories: []}`.
- */
-export async function failureCategoryList(client) {
-    return client.request({
-        method: "GET",
-        path: "",
-        basePath: FAILURE_CATEGORIES_BASE_PATH,
-    });
-}
-/**
- * Create a new failure category via `POST /api/failure-categories`. At
- * least one matcher, each with at least one of `sourceKind`/`tool`/
- * `regexPattern` set, is required (400 otherwise). `ignore: true` REQUIRES a
- * non-empty `ignoreReason` (400 otherwise). A matcher set that would overlap
- * an EXISTING category's matchers is refused 400 naming the conflicting
- * category — expand that category instead of creating a near-duplicate. On
- * success, the dashboard re-matches every existing uncategorized occurrence
- * against the new category before responding, so `matchedCount` in the
- * response already reflects any newly-covered signatures.
- */
-export async function failureCategoryCreate(client, args) {
-    return client.request({
-        method: "POST",
-        path: "",
-        basePath: FAILURE_CATEGORIES_BASE_PATH,
-        body: {
-            name: args.name,
-            description: args.description ?? "",
-            matchers: args.matchers,
-            ignore: args.ignore ?? false,
-            ignoreReason: args.ignoreReason ?? null,
-            expectedRate: args.expectedRate ?? null,
-        },
-    });
-}
-/**
- * Patch an existing failure category via `PATCH /api/failure-categories/:id`
- * — the tool for BOTH "expand an existing category's matchers" (send the
- * full replacement `matchers` array) and "mark a category ignored" (send
- * `ignore: true` + a non-empty `ignoreReason`). At least one field is
- * required (400 otherwise). Same overlap refusal as create (excluding this
- * category's own prior matchers). On success, re-matches every
- * uncategorized occurrence against the updated matcher set before
- * responding.
- */
-export async function failureCategoryUpdate(client, args) {
-    const { id, ...patch } = args;
-    return client.request({
-        method: "PATCH",
-        path: `/${id}`,
-        basePath: FAILURE_CATEGORIES_BASE_PATH,
-        body: patch,
-    });
-}
-// ---------------- dispatch_transcript_search (DX-3221) ----------------
-/**
- * DX-3221 — search or tail ANOTHER dispatch's stored JSONL transcript
- * without ever touching the filesystem. Wraps the existing durable
- * `GET /api/dispatches/:id/logs` route (DX-1682, reading the `dispatch_logs`
- * sink every worker already streams its raw JSONL lines into per DX-1484 —
- * no dashboard-side change needed, that data is already captured today for
- * every worker dispatch).
- *
- * Why this exists instead of a filesystem path: the transcript lives in
- * ANOTHER dispatch's storage, not this one's container, so there is no local
- * path to point Read/Grep at — an ordinary HTTP call authenticated the same
- * way every other `mcp__danx-dashboard__*` tool already is, is how a
- * dispatch reaches it at all.
- *
- * Why this ALSO fixes the underlying complaint `Read` can't: `Read`
- * paginates by LINE, and a persisted JSONL entry can itself be one giant
- * line (a large MCP tool-result payload, escaped-newline JSON) that exceeds
- * the 25000-token cap with no way to sub-page inside it (`offset`/`limit`
- * are line-granular). This handler does the string/regex search ITSELF,
- * server-side of the model (inside this Node process), and only ever hands
- * back a bounded excerpt around a match — never the whole line — so a
- * single oversized line is no longer un-searchable.
- */
-const DISPATCHES_BASE_PATH = "/api/dispatches";
-/** Tail lines returned when no `pattern` is given. */
-const DEFAULT_TAIL_LINES = 20;
-/** Hard ceiling on `tail` — keeps a mistaken huge request bounded. */
-const MAX_TAIL_LINES = 200;
-/** Characters of context returned around (or up to, for tail) each line. */
-const DEFAULT_CONTEXT_CHARS = 1000;
-/** Hard ceiling on `contextChars` — this is what keeps a single giant line from blowing the model's context the way `Read` does today. */
-const MAX_CONTEXT_CHARS = 4000;
-/** Matches returned before search stops scanning further lines. */
-const DEFAULT_MAX_MATCHES = 10;
-/** Hard ceiling on `maxMatches`. */
-const MAX_MATCHES_CEILING = 50;
-function clampPositiveInt(value, fallback, ceiling) {
-    const n = value ?? fallback;
-    if (!Number.isFinite(n) || n <= 0)
-        return fallback;
-    return Math.min(Math.floor(n), ceiling);
-}
-/**
- * `GET /api/dispatches/:id/logs` (DX-1682) → search or tail, in-process.
- * Proxies the SAME durable sink `handleGetDispatchLogs` already serves —
- * this tool adds no new dashboard route, only client-side windowing.
- */
-export async function dispatchTranscriptSearch(client, args) {
-    const hasPattern = args.pattern !== undefined && args.pattern !== "";
-    // Validate the regex BEFORE the network call — a malformed `pattern` is a
-    // caller input error, not a reason to spend an HTTP round-trip first.
-    let re = null;
-    if (hasPattern) {
-        try {
-            re = new RegExp(args.pattern, "gi");
-        }
-        catch (err) {
-            return {
-                ok: false,
-                status: 400,
-                body: {
-                    error: `dispatch_transcript_search: invalid \`pattern\` regex: ${err instanceof Error ? err.message : String(err)}`,
-                },
-            };
-        }
-    }
-    const logsResult = await client.request({
-        method: "GET",
-        path: `/${encodeURIComponent(args.dispatchId)}/logs`,
-        basePath: DISPATCHES_BASE_PATH,
-    });
-    if (!logsResult.ok) {
-        return logsResult;
-    }
-    const body = logsResult.body;
-    const lines = body?.lines ?? [];
-    const contextChars = clampPositiveInt(args.contextChars, DEFAULT_CONTEXT_CHARS, MAX_CONTEXT_CHARS);
-    if (re) {
-        const maxMatches = clampPositiveInt(args.maxMatches, DEFAULT_MAX_MATCHES, MAX_MATCHES_CEILING);
-        const results = [];
-        for (const { ordinal, line } of lines) {
-            re.lastIndex = 0;
-            const match = re.exec(line);
-            if (!match)
-                continue;
-            const half = Math.floor(contextChars / 2);
-            const start = Math.max(0, match.index - half);
-            const end = Math.min(line.length, match.index + match[0].length + half);
-            const truncated = start > 0 || end < line.length;
-            results.push({
-                ordinal,
-                excerpt: `${start > 0 ? "…" : ""}${line.slice(start, end)}${end < line.length ? "…" : ""}`,
-                truncated,
-            });
-            if (results.length >= maxMatches)
-                break;
-        }
-        return {
-            ok: true,
-            status: 200,
-            body: {
-                dispatch_id: args.dispatchId,
-                pattern: args.pattern,
-                total_lines: lines.length,
-                matched_lines: results.length,
-                results,
-            },
-        };
-    }
-    const tail = clampPositiveInt(args.tail, DEFAULT_TAIL_LINES, MAX_TAIL_LINES);
-    const results = lines.slice(-tail).map(({ ordinal, line }) => {
-        const truncated = line.length > contextChars;
-        return {
-            ordinal,
-            excerpt: truncated ? `${line.slice(0, contextChars)}…` : line,
-            truncated,
-        };
-    });
-    return {
-        ok: true,
-        status: 200,
-        body: {
-            dispatch_id: args.dispatchId,
-            total_lines: lines.length,
-            returned_lines: results.length,
-            results,
-        },
-    };
-}
-// ---------------- 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,
-    });
-}