@50arms/platform-mcp 0.0.0-stage → 0.1.437

package/dist/plugin-screenshot.js

@@ -0,0 +1,81 @@
+import { captureWith } from "./design-screenshot.js";
+/** The route the app draws the plugin on, the prefix its files are requested under, the window global it is handed the manifest on, and the attribute the page reports through: restated from `frontend/src/lib/plugin-preview-contract.ts` (this package cannot import the app); `src/dispatch/design-publish-restated-constants.test.ts` ties them. */
+export const PLUGIN_PREVIEW_ROUTE = "/plugin-preview";
+export const PLUGIN_PREVIEW_FILES = "/__plugin-preview__/";
+export const PLUGIN_PREVIEW_ATTRIBUTE = "data-plugin-preview";
+export const PLUGIN_PREVIEW_MANIFEST_GLOBAL = "__DANX_PLUGIN_PREVIEW_MANIFEST__";
+// Restated from `src/plugins/plugin-manifest.ts` (`CARD_VIEW_EXPORT`, `CARD_LIST_VIEW_EXPORT`): this package cannot import the app's source.
+const CARD_VIEW_EXPORT = "CardView";
+const CARD_LIST_VIEW_EXPORT = "CardListView";
+export function previewModeOf(exports) {
+    if (exports.includes(CARD_VIEW_EXPORT))
+        return "card";
+    if (exports.includes(CARD_LIST_VIEW_EXPORT))
+        return "list";
+    throw new Error(`plugin preview: the revision exports neither ${CARD_VIEW_EXPORT} nor ${CARD_LIST_VIEW_EXPORT}, so there is no view to draw`);
+}
+/** The ceiling on one render, from page load to the page saying `ready` or `failed`. A page that reports is waited on only as long as it takes. */
+export const RENDER_WAIT_MS = 30_000;
+/** The content types of the files a plugin may carry: restated from the server's `PLUGIN_FILE_TYPES` (`src/plugins/manifest-validation.ts`, minus its charset suffix); `src/dispatch/design-publish-restated-constants.test.ts` ties them. */
+export const CONTENT_TYPES = {
+    js: "text/javascript",
+    css: "text/css",
+    map: "application/json",
+    json: "application/json",
+    svg: "image/svg+xml",
+    png: "image/png",
+    webp: "image/webp",
+    woff2: "font/woff2",
+};
+function contentTypeOf(filePath) {
+    return CONTENT_TYPES[filePath.slice(filePath.lastIndexOf(".") + 1).toLowerCase()] ?? "application/octet-stream";
+}
+/** The build's files by path. Only what the build listed can be requested. */
+function servedFiles(built) {
+    return new Map(built.files.map((file) => [file.path, file.bytes]));
+}
+async function answer(route, prefix, served) {
+    const { pathname } = new URL(route.request().url());
+    let requested;
+    try {
+        requested = decodeURIComponent(pathname.slice(prefix.length));
+    }
+    catch {
+        requested = ""; // a malformed percent-escape names no file
+    }
+    const bytes = served.get(requested);
+    if (bytes === undefined) {
+        await route.fulfill({ status: 404, contentType: "text/plain", body: `no such plugin file: ${pathname}` });
+        return;
+    }
+    await route.fulfill({ status: 200, contentType: contentTypeOf(pathname), body: bytes });
+}
+const REPORT_EXPRESSION = `(() => { const el = document.querySelector("[${PLUGIN_PREVIEW_ATTRIBUTE}]"); return { state: el ? el.getAttribute("${PLUGIN_PREVIEW_ATTRIBUTE}") : null, text: el ? el.textContent : "" }; })()`;
+/** Settled: the page said `ready` or `failed`, and nothing on it is still loading (`aria-busy`). */
+const SETTLED_EXPRESSION = `(() => { const el = document.querySelector("[${PLUGIN_PREVIEW_ATTRIBUTE}]"); const state = el && el.getAttribute("${PLUGIN_PREVIEW_ATTRIBUTE}"); return (state === "ready" || state === "failed") && !document.querySelector('[aria-busy="true"]'); })()`;
+/**
+ * Renders the built plugin on the dashboard's preview page and screenshots it.
+ * @param dashboardUrl the dashboard's base URL (`ClientConfig.baseUrl`).
+ */
+export async function capturePluginRender(built, dashboardUrl, where) {
+    const origin = new URL(dashboardUrl).origin;
+    const served = servedFiles(built);
+    return captureWith(where, false, async (page) => {
+        await page.addInitScript(`window[${JSON.stringify(PLUGIN_PREVIEW_MANIFEST_GLOBAL)}] = ${JSON.stringify({ entry: built.manifest.entry, styles: built.manifest.styles, runtime: built.manifest.runtime, mode: previewModeOf(built.manifest.exports) })};`);
+        await page.route(`${origin}${PLUGIN_PREVIEW_FILES}**`, (route) => answer(route, PLUGIN_PREVIEW_FILES, served));
+        const response = await page.goto(`${origin}${PLUGIN_PREVIEW_ROUTE}`, { waitUntil: "load" });
+        const status = response?.status();
+        if (status !== undefined && (status < 200 || status > 299))
+            return `the dashboard answered ${status} for its ${PLUGIN_PREVIEW_ROUTE} page; a dashboard older than this tool does not serve it`;
+        try {
+            await page.waitForFunction(SETTLED_EXPRESSION, undefined, { timeout: RENDER_WAIT_MS });
+        }
+        catch {
+            const report = await page.evaluate(REPORT_EXPRESSION);
+            return `the dashboard's ${PLUGIN_PREVIEW_ROUTE} page did not say ready within ${RENDER_WAIT_MS} ms (it said ${report.state ?? "nothing"}); the page may be missing, a plugin file may not have loaded, or something on it is still loading`;
+        }
+        const report = await page.evaluate(REPORT_EXPRESSION);
+        if (report.state === "failed")
+            return `the plugin did not render: ${report.text.trim().slice(0, 300)}`;
+    });
+}

package/dist/request-bound.js

@@ -0,0 +1,21 @@
+/**
+ * DX-4632 - the ONE bound every dashboard request of this package shares: a timeout of its own, plus an OUTER signal that ends
+ * the request early (a lookup's one deadline, a closed relay). Used by `sendSessionRequest` (`restart-notice.ts`) and by `request` in `session-stream.ts` (the relay's mint, inventory and
+ * heartbeat), so the controller, the timer, the link to the outer signal and the cleanup exist once.
+ */
+export function boundRequest(timeoutMs, outer) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const timer = setTimeout(abort, timeoutMs);
+    if (outer?.aborted === true)
+        abort();
+    outer?.addEventListener("abort", abort, { once: true });
+    return {
+        signal: controller.signal,
+        aborted: () => controller.signal.aborted,
+        release: () => {
+            clearTimeout(timer);
+            outer?.removeEventListener("abort", abort);
+        },
+    };
+}

package/dist/restart-notice.js

@@ -0,0 +1,271 @@
+/**
+ * The `restart_notice` tool - DX-3928, DX-4632. How a RESTARTED Claude Code session learns which plan the session it replaced was
+ * working, so it can say so to its agent and reconnect.
+ *
+ * WHY IT EXISTS. A restarted session gets a NEW session id, no plan binding and, until a person approves its first call, no
+ * dashboard key of its own: its MCP server boots signed out. Nothing told it (or the operator) that the plan it had been
+ * working was unattended: six operator answers sat unread for an hour on 2026-10-01. The session's own connection record cannot
+ * help (it does not exist yet); the PREVIOUS session's record can, found by the project key `plan_connect` wrote into it
+ * (`findPredecessorCandidates`). So this asks the dashboard about each predecessor as the predecessor, with the credential
+ * that predecessor's record names (`resolveDashboardAuth`, the resolver `session-options.ts` holds), which a signed-out
+ * session needs no key of its own to do. The tool is therefore usable signed out: it is declared like `plan_connect` (no
+ * permission) and only on a person's session (`tool-access.ts`).
+ *
+ * THE ANSWER (the plugin's hooks module reads it through `$.mcp.call`):
+ *   - `{notice: "<text>"}` - say this to the agent (the registry's `plan_restart.waiting_events` text; this module carries no
+ *     wording of its own).
+ *   - `{notice: null}` - nothing to say: no earlier session of this project connected a plan, or the plan is archived or
+ *     deleted, or the record is stale, or every predecessor is still live. The plugin stays silent, as PLN-11 R-10 requires of
+ *     a project that never connected a plan.
+ *   - `{stopped: {reason, detail, fix}}` - the lookup could not answer: no session id, an unreadable transcript, a named predecessor
+ *     with no usable record, NO candidate answered (credential, network, non-2xx, bad shape, for every one), or the one deadline
+ *     passed. Never a silent null. (A failure that is not
+ *     one of these, a bug in the credential resolver, is rethrown: fail loud, never dressed as a lookup failure.)
+ *
+ * WHO THE PREDECESSOR IS (DX-4234). The project scan is a GUESS (the newest non-self record of the project): another session
+ * of the same checkout can win it, so a forked session was told about a stranger's plan. The caller can name the predecessor
+ * instead, in this precedence (`choosePredecessors`):
+ *   1. `predecessor_id` (a Claude Code session id): ask ONLY that session's record. No usable record for it is a `stopped`
+ *      (`no_predecessor_record`), never a fall back to the guess.
+ *   2. `transcript_path` (this session's own transcript, absolute `.jsonl`): the transcript says whether this session was forked
+ *      and from which session (`readTranscriptLineage`: the nearest ancestor, which for a fork of a fork is not the first row's
+ *      session). A fork's parent is asked as in (1), except that a parent with no record (it never connected a plan) is
+ *      `{notice: null}`. A transcript that proves this is NOT a fork (a plain resume) is `{notice: null}` too. One that cannot be
+ *      read (a bad path, a missing or malformed file, an over-cap row) is a `stopped` (`transcript_unreadable`): never the guess.
+ *   3. neither argument: the project scan (a bare startup).
+ * A predecessor the caller NAMED is asked with `?named=1`, which tells the dashboard to skip its "that session's stream is still
+ * open, so it is a live sibling" check: a fork's parent is usually still live, and the fork still needs to hear its plan.
+ *
+ * ONE DEADLINE over the whole lookup (`RESTART_NOTICE_DEADLINE_MS`): the transcript read and every candidate's request share it
+ * (each request keeps its own shorter bound), so a hung dashboard or a stalled disk cannot wedge a session start. READ-ONLY: it advances
+ * no cursor on the server.
+ */
+import { z } from "zod";
+import { boundRequest } from "./request-bound.js";
+import { PLUGIN_BACKGROUND_HEADER, resolveDashboardAuth, SESSION_ID_HEADER, SessionStartError } from "./session-options.js";
+import { findPredecessorCandidates, projectKeyOf, readSessionConnection } from "./session-connection.js";
+import { checkedTranscriptPath } from "./session-stats.js";
+import { readTranscriptLineage, TranscriptReadAborted, TranscriptUnreadable } from "./transcript-lineage.js";
+import { fixForStop } from "./stop-fixes.js";
+/**
+ * One authenticated HTTP call to this session's dashboard, with a hard
+ * timeout. Never throws — a network failure or an abort is reported as
+ * `RequestFailure`, exactly like any other classified failure the caller
+ * might produce from the status/body it gets back on success.
+ */
+export async function sendSessionRequest(options, path, init, deps) {
+    const bound = boundRequest(deps.requestTimeoutMs, deps.signal);
+    try {
+        try {
+            const response = await deps.fetch(`${options.dashboardUrl}${path}`, {
+                method: init.method,
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                    Accept: "application/json",
+                    ...(init.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                    [SESSION_ID_HEADER]: options.sessionId,
+                    // DX-5354: the session-start hook's lookup is the plugin's own work, never the agent acting, so it does not extend the session's key.
+                    [PLUGIN_BACKGROUND_HEADER]: "1",
+                },
+                body: init.body,
+                signal: bound.signal,
+            });
+            const text = await response.text();
+            return { status: response.status, text };
+        }
+        catch {
+            // DX-3367 fix-up — the caught value is never inspected (an aborted
+            // fetch's own rejection shape varies by runtime), so binding it to a
+            // name the code never reads was dead weight the linter never caught.
+            return { ok: false, reason: bound.aborted() ? "timeout" : "request_failed" };
+        }
+    }
+    finally {
+        bound.release();
+    }
+}
+/** `JSON.parse`, classified rather than thrown — the ONE shared parse point
+ *  every caller uses once it has decided (from `status`) that the body is
+ *  worth reading at all. */
+export function tryParseJsonBody(text) {
+    try {
+        return { ok: true, body: text === "" ? null : JSON.parse(text) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+export const RESTART_NOTICE_REQUEST_TIMEOUT_MS = 5_000;
+/** DX-4632: the whole lookup, every candidate included (the old hook's `timeout 8s`). */
+export const RESTART_NOTICE_DEADLINE_MS = 8_000;
+/**
+ * How many earlier sessions of the project one lookup asks about, newest first. Many
+ * sessions share one checkout and the dashboard answers "nothing" for a LIVE sibling
+ * (it is not a predecessor), so the newest candidate is often not the one.
+ */
+export const RESTART_NOTICE_MAX_CANDIDATES = 10;
+/** The registry row whose text is the notice (`src/issues/reminders/seed.yaml`). */
+export const RESTART_NOTICE_REMINDER_KEY = "plan_restart.waiting_events";
+/** One authenticated GET (`sendSessionRequest` above, so its bound and its failure names are the same), answering the notice text or `null`. */
+export async function fetchRestartNotice(target, deps) {
+    // The bearer is the predecessor's; the session id header names the ASKING session.
+    const auth = { dashboardUrl: target.dashboardUrl, token: target.token, sessionId: target.askingSessionId };
+    const sent = await sendSessionRequest(auth, `/api/plan-sessions/${encodeURIComponent(target.predecessorId)}/restart-notice${target.named === true ? "?named=1" : ""}`, { method: "GET" }, deps);
+    if ("ok" in sent)
+        return { ok: false, reason: sent.reason };
+    const { status, text } = sent;
+    if (status === 401 || status === 403)
+        return { ok: false, reason: "unauthorized" };
+    if (status === 404)
+        return { ok: false, reason: "not_found" };
+    if (status < 200 || status >= 300)
+        return { ok: false, reason: "http_error" };
+    const parsed = tryParseJsonBody(text);
+    const body = parsed.ok ? parsed.body : null;
+    if (typeof body !== "object" || body === null || !("restart" in body))
+        return { ok: false, reason: "bad_response" };
+    if (body.restart === null)
+        return { ok: true, text: null };
+    // A notice exists, so the registry row MUST have answered with its text: a
+    // missing one is a server/registry fault, reported rather than papered over.
+    const reminders = Array.isArray(body.reminders) ? body.reminders : [];
+    const notice = reminders.find((r) => r.key === RESTART_NOTICE_REMINDER_KEY);
+    if (typeof notice?.text !== "string" || notice.text === "")
+        return { ok: false, reason: "bad_response" };
+    return { ok: true, text: notice.text };
+}
+/** The tool's arguments (`index.ts` registers exactly this shape). */
+export const RESTART_NOTICE_ARGS = {
+    predecessor_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Session id of the session this one replaced, when known. Asked alone, and wins over transcript_path. With neither argument the newest earlier session of the project is guessed."),
+    transcript_path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Absolute path of this session's transcript (.jsonl file): a forked session's copied rows name the session it was forked from."),
+};
+const stop = (reason, detail) => ({ stopped: { reason, detail, fix: fixForStop(reason) } });
+/**
+ * DX-4234 - the module docblock's precedence: a named id, else the transcript's lineage, else the project scan. Throws
+ * `TranscriptReadAborted` when the deadline fires mid-read; every other failure is an answer.
+ */
+async function choosePredecessors(lookup, ownId, signal) {
+    let namedId = lookup.predecessorId;
+    let namedBy = "predecessor_id";
+    if (namedId === undefined && lookup.transcriptPath !== undefined) {
+        let path;
+        try {
+            path = checkedTranscriptPath(lookup.transcriptPath, "restart_notice transcript_path");
+        }
+        catch (err) {
+            return { answer: stop("transcript_unreadable", err.message) };
+        }
+        let lineage;
+        try {
+            lineage = await readTranscriptLineage(path, ownId, { signal, open: lookup.openTranscript });
+        }
+        catch (err) {
+            if (err instanceof TranscriptUnreadable)
+                return { answer: stop("transcript_unreadable", err.message) };
+            throw err;
+        }
+        if (lineage.kind === "not_fork")
+            return { answer: { notice: null } };
+        namedId = lineage.parent;
+        namedBy = "transcript_path";
+    }
+    if (namedId === undefined) {
+        const found = findPredecessorCandidates(projectKeyOf(lookup.cwd), ownId, { home: lookup.home, now: lookup.now });
+        return { candidates: found.slice(0, RESTART_NOTICE_MAX_CANDIDATES), named: false };
+    }
+    let record;
+    try {
+        record = readSessionConnection(namedId, { home: lookup.home });
+    }
+    catch (err) {
+        return { answer: stop("no_predecessor_record", `session ${namedId} (${namedBy}) has no usable dashboard connection record: ${err.message}`) };
+    }
+    if (record === null) {
+        // A parent found through the transcript that never connected a plan has nothing to tell; an id the caller NAMED that has
+        // no record is something the caller must hear about.
+        if (namedBy === "transcript_path")
+            return { answer: { notice: null } };
+        return { answer: stop("no_predecessor_record", `session ${namedId} (${namedBy}) has no dashboard connection record on this machine`) };
+    }
+    return { candidates: [record], named: true };
+}
+/** The tool's whole body: see the module docblock for the contract. Throws only on a bug, never on a lookup failure. */
+export async function lookupRestartNotice(lookup) {
+    const ownId = lookup.sessionId;
+    if (ownId === undefined || ownId === "") {
+        return stop("no_session_id", "this server has no CLAUDE_CODE_SESSION_ID, so it cannot tell which session it replaced");
+    }
+    const resolveFrom = { home: lookup.home, now: lookup.now };
+    // DX-4632: ONE deadline for the transcript read and every candidate read. It is not unref'd: the lookup is awaited, and a
+    // pending request holds the process anyway.
+    const deadline = new AbortController();
+    const deadlineMs = lookup.deadlineMs ?? RESTART_NOTICE_DEADLINE_MS;
+    const timer = setTimeout(() => deadline.abort(), deadlineMs);
+    try {
+        let choice;
+        try {
+            choice = await choosePredecessors(lookup, ownId, deadline.signal);
+        }
+        catch (err) {
+            if (!(err instanceof TranscriptReadAborted))
+                throw err;
+            return stop("lookup_timeout", `the lookup did not finish within ${deadlineMs} ms (it was still reading the transcript)`);
+        }
+        if ("answer" in choice)
+            return choice.answer;
+        const { candidates, named } = choice;
+        // One candidate failing (its credential moved, its dashboard is down) must not hide a LATER candidate that
+        // would answer: keep going, and report failure only when no candidate answered at all.
+        const failures = [];
+        let answered = 0;
+        for (const predecessor of candidates) {
+            let options;
+            try {
+                options = resolveDashboardAuth(predecessor.sessionId, lookup.env, resolveFrom);
+            }
+            catch (err) {
+                if (!(err instanceof SessionStartError))
+                    throw err; // a bug in the resolver is not a lookup failure: fail loud
+                failures.push(`${err.reason}: ${err.message}. Fix: ${err.fix}.`);
+                continue;
+            }
+            const output = await fetchRestartNotice({
+                dashboardUrl: options.dashboardUrl,
+                token: options.token,
+                predecessorId: predecessor.sessionId,
+                askingSessionId: ownId,
+                named,
+            }, { fetch: lookup.fetch, requestTimeoutMs: lookup.requestTimeoutMs ?? RESTART_NOTICE_REQUEST_TIMEOUT_MS, signal: deadline.signal });
+            // A notice the dashboard fully answered is kept even when the deadline fired right after it; every other outcome of a
+            // deadline that passed is the stop below (this is the lookup's one deadline check).
+            if (output.ok && output.text !== null)
+                return { notice: output.text };
+            if (deadline.signal.aborted)
+                break;
+            if (!output.ok) {
+                failures.push(`${output.reason}: could not ask the dashboard what session ${predecessor.sessionId} was working`);
+                continue;
+            }
+            answered += 1;
+        }
+        // DX-4632: a deadline that passed is a stop even when earlier candidates answered "nothing": an unasked candidate may be the one.
+        if (deadline.signal.aborted) {
+            return stop("lookup_timeout", `the lookup did not finish within ${deadlineMs} ms (${failures.length} of ${candidates.length} candidates had failed)`);
+        }
+        if (answered === 0 && failures.length > 0) {
+            return stop("lookup_failed", `no candidate answered (${failures.length} of ${candidates.length} failed): ${failures.join(" | ")}`);
+        }
+        return { notice: null };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/result-limit.js

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { writeFileDurable } from "./durable-write.js";
+/**
+ * DX-4400 — the most characters one `50arms_api`, `50arms_api_spec` or `50arms_api_list` result may carry
+ * back to the agent. Every character is context the agent pays for on every later call, and Claude Code itself
+ * saves a larger result to a file with only a short preview, after the cost is paid. A deliberate, narrow
+ * exception to PLAN-11 rule R-25 (verbatim forwarding): `plan_connect` and the lifecycle tools never pass here.
+ */
+export const MCP_MAX_RESULT_CHARS = 100_000;
+const FILE_INSTRUCTION = "The reply was over the inline limit, so its body is this file, whole: read it with Read (in parts with offset and limit when it is long), or grep it.";
+/**
+ * The text the agent receives for `result`: its compact JSON when that fits `MCP_MAX_RESULT_CHARS`, otherwise
+ * `{ok, status, reply_file:{path, bytes, chars, instruction}}`, the body written whole to
+ * `<tmp>/danx-api/<content hash>.json` (DX-6117, as `docs_read` and the role text do). Never truncates, never forwards a part. `ok`
+ * and `status` stay so a write that already committed is still reported as committed.
+ */
+export function boundedResultText(result, deps = {}) {
+    const text = JSON.stringify(result);
+    if (text.length <= MCP_MAX_RESULT_CHARS)
+        return text;
+    const body = JSON.stringify(result.body);
+    const file = path.join(deps.tmpDir ?? os.tmpdir(), "danx-api", `${createHash("sha256").update(body).digest("hex").slice(0, 16)}.json`);
+    writeFileDurable(file, body);
+    return JSON.stringify({
+        ok: result.ok,
+        status: result.status,
+        reply_file: { path: file, bytes: Buffer.byteLength(body, "utf8"), chars: body.length, instruction: FILE_INSTRUCTION },
+    });
+}

package/dist/role-instruction-file.js

@@ -0,0 +1,36 @@
+/**
+ * DX-6089 - a session's role text reaches it as a local file, never inline. The dashboard answers `roleInstruction: {profile, text}` on
+ * `plan_connect`, `card_connect` and `GET /api/plan-sessions/me/role`; the text runs to tens of KB, and a tool reply that large is
+ * saved to a file by the client with only a short preview, which also hides every field after it (the briefing, the agent instruction, the
+ * reminders). So this server writes the text to `<tmp>/danx-role/<profile>-<content hash>.md` and answers `{profile, path, bytes, instruction}`
+ * in its place, leaving every other field inline, as `docs_read` does for a docs page (`docs-tools.ts`). The name carries the content hash, so a
+ * changed text never overwrites a file a session is reading, and the file is written under a temp name and renamed into place, so a reader never
+ * sees half of it.
+ */
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { writeFileDurable } from "./durable-write.js";
+export const ROLE_FILE_INSTRUCTION = "Read this file in full now, with Read (in parts with offset and limit when it is long): it is your role's workflow, the procedure you work by.";
+// The profile names the file, so it must be a plain name: never a path a reply could steer.
+const PROFILE_NAME = /^[a-z][a-z0-9-]*$/;
+/**
+ * `result` with its body's `roleInstruction` written to a file and replaced by where it is. A body without the key, or with `null` (nothing to
+ * send), passes unchanged. A `roleInstruction` of any other shape is a dashboard contract break and throws (CP1).
+ */
+export function spillRoleInstruction(result, deps = {}) {
+    const body = result.body;
+    if (typeof body !== "object" || body === null || !Object.hasOwn(body, "roleInstruction"))
+        return result;
+    const role = body.roleInstruction;
+    if (role === null)
+        return result;
+    const { profile, text } = (role ?? {});
+    if (typeof profile !== "string" || !PROFILE_NAME.test(profile) || typeof text !== "string") {
+        throw new Error(`the dashboard answered a roleInstruction that is not {profile, text}: ${JSON.stringify(role).slice(0, 200)}`);
+    }
+    const file = path.join(deps.tmpDir ?? os.tmpdir(), "danx-role", `${profile}-${createHash("sha256").update(text).digest("hex").slice(0, 16)}.md`);
+    writeFileDurable(file, text);
+    const spilled = { profile, path: file, bytes: Buffer.byteLength(text, "utf8"), instruction: ROLE_FILE_INSTRUCTION };
+    return { ...result, body: { ...body, roleInstruction: spilled } };
+}

package/dist/route-board-scope.generated.js

@@ -0,0 +1,95 @@
+export const GET_ROUTE_BOARD_SCOPE = [
+    ["/api/access-requests", "refuse"],
+    ["/api/account/sessions", "refuse"],
+    ["/api/agents/:agentId/halt-history", "refuse"],
+    ["/api/audit-events", "refuse"],
+    ["/api/boards", "refuse"],
+    ["/api/boards/:boardId", "refuse"],
+    ["/api/boards/:boardId/context-cost", "refuse"],
+    ["/api/boards/:boardId/usage-series", "refuse"],
+    ["/api/catalog/:catalogId", "refuse"],
+    ["/api/dispatch-queue", "refuse"],
+    ["/api/dispatches", "refuse"],
+    ["/api/dispatches/:dispatchId", "stamp"],
+    ["/api/dispatches/:dispatchId/context-series", "refuse"],
+    ["/api/dispatches/:dispatchId/logs", "refuse"],
+    ["/api/dispatches/:dispatchId/usage-events", "refuse"],
+    ["/api/dispatches/dead-letter-ids", "refuse"],
+    ["/api/docs/:repo/changes", "refuse"],
+    ["/api/docs/:repo/pages/:id", "refuse"],
+    ["/api/docs/:repo/progress/:pathId", "refuse"],
+    ["/api/docs/:repo/search", "refuse"],
+    ["/api/failure-categories", "refuse"],
+    ["/api/failure-categories/ambiguous", "refuse"],
+    ["/api/failure-categories/uncategorized", "refuse"],
+    ["/api/failure-signatures", "refuse"],
+    ["/api/feedback/mine", "refuse"],
+    ["/api/issues", "named"],
+    ["/api/issues/:id/decision-records", "refuse"],
+    ["/api/issues/:id/problems", "refuse"],
+    ["/api/issues/:id/usage-runs", "refuse"],
+    ["/api/issues/:id/usage-series", "refuse"],
+    ["/api/issues/:issueId/dispatches", "refuse"],
+    ["/api/landing-queue/pipeline-health", "refuse"],
+    ["/api/model-ledger", "refuse"],
+    ["/api/notifications", "refuse"],
+    ["/api/pacing/history", "refuse"],
+    ["/api/permission-requests", "refuse"],
+    ["/api/plan-sessions", "refuse"],
+    ["/api/plan-sessions/ready", "refuse"],
+    ["/api/plans", "refuse"],
+    ["/api/plans/:planId/architecture/sections", "refuse"],
+    ["/api/plans/:planId/cards", "refuse"],
+    ["/api/plans/:planId/designs", "refuse"],
+    ["/api/plans/:planId/notes", "refuse"],
+    ["/api/plans/:planId/records", "refuse"],
+    ["/api/plans/:planId/usage-series", "refuse"],
+    ["/api/plans/mine/architecture/sections", "refuse"],
+    ["/api/plans/mine/records", "refuse"],
+    ["/api/platform/feedback", "refuse"],
+    ["/api/platform/signup-codes", "refuse"],
+    ["/api/platform/teams", "refuse"],
+    ["/api/plugins", "refuse"],
+    ["/api/product-docs/pages/:id", "refuse"],
+    ["/api/product-docs/search", "refuse"],
+    ["/api/reminders", "refuse"],
+    ["/api/repos", "refuse"],
+    ["/api/security-incidents", "refuse"],
+    ["/api/self-repair/errors", "refuse"],
+    ["/api/sync-root", "refuse"],
+    ["/api/tasks", "refuse"],
+    ["/api/team", "refuse"],
+    ["/api/team/activity", "refuse"],
+    ["/api/team/audit-events", "refuse"],
+    ["/api/team/consumer-tokens", "refuse"],
+    ["/api/team/cost/landed-cards", "refuse"],
+    ["/api/team/delivery", "refuse"],
+    ["/api/team/invitations", "refuse"],
+    ["/api/team/members", "refuse"],
+    ["/api/team/overview/boards", "refuse"],
+    ["/api/team/overview/boards-spend", "refuse"],
+    ["/api/team/overview/plans", "refuse"],
+    ["/api/team/overview/plans-spend", "refuse"],
+    ["/api/team/quality/dispatches", "refuse"],
+    ["/api/team/quality/effort", "refuse"],
+    ["/api/team/quality/gates", "refuse"],
+    ["/api/team/quality/people", "refuse"],
+    ["/api/team/roles", "refuse"],
+    ["/api/test-runs/file-times", "refuse"],
+    ["/api/test-runs/stats", "refuse"],
+    ["/api/usage/series", "refuse"],
+    ["/api/users", "refuse"],
+    ["/api/widget-surfaces", "refuse"],
+    ["/api/worker/catalog-mcp-servers", "refuse"],
+    ["/api/worker/dispatches/:dispatchId", "stamp"],
+    ["/api/worker/dispatches/:dispatchId/usage-predecessor", "refuse"],
+    ["/api/worker/dispatches/non-terminal", "refuse"],
+    ["/api/worker/dispatches/recent-signal-failures", "refuse"],
+    ["/api/worker/test-runs/file-times", "refuse"],
+    ["/api/workers", "refuse"],
+];
+/** DX-5337 - the routes that read the card's board from `body.board` only: the client fills a dispatch's board in there and sends no `?board=`. */
+export const BODY_BOARD_ROUTES = [
+    ["POST", "/api/issues"],
+    ["POST", "/api/issues/import"],
+];

package/dist/route-board-scope.js

@@ -0,0 +1,71 @@
+/**
+ * DX-4303 / DX-4542 - what the client does with a `?board=` query key on the dashboard route a request reaches: `stamp` it (the route
+ * takes it, so the dispatch's board is filled in when the server has one), `refuse` it (the server 400s it) or `named` (the board is optional and no board is the
+ * whole team: sent only when the caller names one).
+ *
+ * The answer comes from the dashboard's own route table, shipped in this package as `route-board-scope.generated.ts` (generated by
+ * the server's `src/dashboard/mcp-board-scope.ts`; a root test fails when it drifts). This file only matches a concrete request
+ * path against those templates, the way the server's `RouteTable` does: segments compared left to right, a literal beating a
+ * `:param` beating a trailing `*`. It holds no route knowledge of its own.
+ *
+ * Only GET routes are listed - the server refuses an unknown query key on a read alone - so every other method takes the key. A
+ * GET path no template matches takes it too: the server answers it with a 404 whatever the query.
+ */
+import { BODY_BOARD_ROUTES, GET_ROUTE_BOARD_SCOPE } from "./route-board-scope.generated.js";
+const RANK = { literal: 2, param: 1, rest: 0 };
+function compile(template, stamp) {
+    const segments = template
+        .slice(1)
+        .split("/")
+        .map((s) => (s === "*" ? { kind: "rest" } : s.startsWith(":") ? { kind: "param" } : { kind: "literal", value: s }));
+    return { segments, rank: segments.map((s) => RANK[s.kind]), stamp };
+}
+function compareRank(a, b) {
+    const n = Math.max(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const x = a[i] ?? -1;
+        const y = b[i] ?? -1;
+        if (x !== y)
+            return y - x;
+    }
+    return 0;
+}
+const ROUTES = GET_ROUTE_BOARD_SCOPE.map(([template, stamp]) => compile(template, stamp)).sort((a, b) => compareRank(a.rank, b.rank));
+function matches(route, parts) {
+    for (let i = 0; i < route.segments.length; i++) {
+        const seg = route.segments[i];
+        if (seg.kind === "rest")
+            return true;
+        const part = parts[i];
+        if (part === undefined)
+            return false;
+        if (seg.kind === "literal" ? part !== seg.value : part === "")
+            return false;
+    }
+    return parts.length === route.segments.length;
+}
+/**
+ * What the client does with `?board=` on `<method> <routePath>` (no query string): `stamp` the dispatch's board when the caller names none,
+ * `refuse` to send it (the server 400s it), or (DX-4542) `named`: the route takes it OPTIONALLY and no board is the whole team, so it is sent
+ * only when the caller names one.
+ */
+export function boardStampOf(method, routePath) {
+    if (method !== "GET")
+        return "stamp";
+    const parts = routePath.slice(1).split("/");
+    return ROUTES.find((route) => matches(route, parts))?.stamp ?? "stamp";
+}
+/**
+ * DX-5337 - the routes that read the card's board ONLY from `body.board` (issue create and import), from the generated
+ * `BODY_BOARD_ROUTES` (the server's `RouteDef.boardInBody`). A dispatch's default board reaches them through the body and through
+ * nothing else: the client fills `body.board` when the caller named none and sends no `?board=` there.
+ */
+const BODY_BOARD = BODY_BOARD_ROUTES.map(([method, template]) => ({
+    method,
+    route: compile(template, "stamp"),
+}));
+/** Whether `<method> <routePath>` (no query string) takes its board in `body.board`. */
+export function takesBoardInBody(method, routePath) {
+    const parts = routePath.replace(/\/+$/, "").slice(1).split("/");
+    return BODY_BOARD.some((entry) => entry.method === method && matches(entry.route, parts));
+}