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

package/dist/index.js

@@ -0,0 +1,1128 @@
+#!/usr/bin/env node
+/**
+ * @50arms/platform-mcp
+ *
+ * Stdio MCP server wrapping danxbot's dashboard `/api/issues/*`
+ * normalized DB-backed HTTP routes (DX-704 Phase 2 / DX-811). Replaces
+ * the legacy "agents Edit/Write YAML files directly" pattern: every
+ * tool here POSTs/GETs against the dashboard, which atomically applies
+ * the change via the transactional layer and publishes SSE.
+ *
+ * Tool surface (all exposed as `mcp__platform__<name>` once wired
+ * through the workspace `mcp.template.json`):
+ *
+ *   - 50arms_api            the generic surface for every non-agent-specific dashboard
+ *                            operation (DX-3465 / PLN-11 R-25) — list/get/create/update/delete
+ *                            against the uniform resource routes that used to each have their
+ *                            own per-operation tool (issue_*, plan_* (except plan_connect),
+ *                            brief_*, repo_knowledge_*, failure_category_*,
+ *                            dispatch_transcript_search, quality_gate_instruction — all deleted
+ *                            here). See `SERVER_INSTRUCTIONS` below for the calling convention.
+ *   - 50arms_api_list       lists the routes your credential may call, one string each (DX-3465
+ *                            A5, backed by DX-3528's permission-aware discovery). Call this
+ *                            first to find the route for something you need to do.
+ *   - 50arms_api_spec       discovers the exact request/response shape of any route
+ *                            `50arms_api` can call, before calling it.
+ *   - request_permission     POST   /api/permission-requests (DX-4434) — asks a person to grant
+ *                            this key ONE MORE permission while the agent works; answers at once
+ *                            with the approval URL and confirm code, and the grant is picked up in
+ *                            the background (`permission-request.ts`). A dashboard call refused
+ *                            `403 forbidden` carries a hint to call it (`forbidden-hint.ts`).
+ *   - plan_connect           POST   /api/plan-sessions/me/plan — SESSION-BOUND (kept as a
+ *                            dedicated tool; every plan READ or WRITE operation goes
+ *                            through 50arms_api now, e.g. GET /api/plans/mine or
+ *                            POST /api/plans/mine/records)
+ *
+ * DX-2683, updated DX-3465 — PLAN WRITES ARE SESSION-BOUND, and
+ * asymmetrically so relative to reads. There is no dedicated plan-write
+ * tool any more (DX-3465 deleted every `plan_add_*`/`plan_update_*`/
+ * `plan_delete_*`/`plan_remove_card`/`plan_rename`/`plan_reorder_*` tool);
+ * a plan write is an ordinary `50arms_api` call to a `/api/plans/mine/...`
+ * route. Reads may name any plan by id (`/api/plans/:id/...`); a WRITE
+ * route instead takes NO plan id at all and acts on the plan this session
+ * is connected to (`plan_connect`), resolved server-side from the session
+ * id this package forwards on every request. A session therefore cannot
+ * modify a plan it is not connected to, whatever id it believes. A write
+ * from an unconnected session is refused loudly (`session_not_connected`),
+ * never silently dropped and never guessed at.
+ *
+ * BOARD-ONLY (DX-1171): board is the first-level concept; repo is
+ * DERIVED from board server-side, never passed. The package composes the
+ * dispatch's board ref from DANXBOT_BOARD_ID at boot and sends it as
+ * `board` — the dashboard owns board→repo resolution.
+ *
+ * Env at boot (validated fail-loud — a missing required var → process.exit(1)):
+ *   DANXBOT_DASHBOARD_URL   dashboard base (e.g. http://danxbot-dashboard:5555)
+ *   the CREDENTIAL (DX-4390), resolved by the ONE resolver this package's event relay
+ *   also uses (`credential.ts`, DX-2862), and never a reason to exit:
+ *     DANX_DASHBOARD_CREDENTIAL  the bearer verbatim (a dispatch, substituted into
+ *                           the materialized `.mcp.json` from its overlay)
+ *     otherwise this session's approved key (`session-key.ts`), else none: the
+ *                           server boots SIGNED OUT, every tool but `plan_connect`
+ *                           halts, and `plan_connect` requests access (`session-access.ts`)
+ *   DANXBOT_TEAM            OPTIONAL (DX-4446), non-secret: the team slug (or id) whose
+ *                           approvers see this session's access request in their danxbot
+ *                           site. Set it in your shell or a repo's committed `.claude/settings.json` `env` block.
+ *                           Unset: the request is answered by link only. Set but not a
+ *                           valid ref, or unknown to the dashboard: fails loud, never a
+ *                           silent fall back to the link flow.
+ *   DANXBOT_BOARD_ID        OPTIONAL (DX-4555): the dispatch's board, the board's ref number the worker injects;
+ *                           a positive integer (anything else exits loudly), appended as ?board=<ref>.
+ *                           Each tool's optional `board` arg (a board ref)
+ *                           overrides it per-call for cross-board reads/writes.
+ *
+ * Envelope contract: every tool returns the dashboard's response body
+ * verbatim wrapped as `{ok, status, body}`. Refusals (4xx with the v2
+ * `{error, ...extra}` shape) come through as `{ok: false, ...}`; the
+ * agent reads `body.error` + structured fields to decide next action.
+ * 5xx and network failures throw — never silently swallowed.
+ */
+import { MACHINE_DAEMON_SUBCOMMANDS, runMachineDaemonCommand } from "./machine-daemon/cli.js";
+import { isEntrypointModule } from "./entrypoint.js";
+import { compactionFilesIn } from "./compaction-control.js";
+import { clearFilesIn } from "./clear-control.js";
+import { PlanEventRelay, WAIT_MAX_MS, WAIT_MIN_MS } from "./plan-events-relay.js";
+import { READ_IDLE_TIMEOUT_MS } from "./listen.js";
+import { REQUEST_TIMEOUT_MS, realScheduleInterval, realSleep } from "./session-stream.js";
+import { servePlanEventsWait } from "./plan-events-tool.js";
+import { lookupRestartNotice, RESTART_NOTICE_ARGS } from "./restart-notice.js";
+import { makeSessionStop, stopWhenSessionEnds } from "./shutdown.js";
+import { SUBAGENTS_LIVE_SUBCOMMAND, runSubagentsLiveCommand } from "./subagents-live.js";
+import { resolveBootCredential } from "./credential.js";
+import { SessionKeyUnusableError, deleteSessionKey } from "./session-key.js";
+import { assertMcpTeamRef } from "./access-request.js";
+import { SessionAccess } from "./session-access.js";
+import { PermissionRequests } from "./permission-request.js";
+import { makeGuardedCalls } from "./guarded-calls.js";
+import { readOwnVersion } from "./version-floor.js";
+import { createCheckoutDocsRootReporter } from "./checkout-docs-root.js";
+import { isPickupConnect, projectKeyOf, recordSessionConnectionAfterConnect, removeSessionConnectionAfterLeave } from "./session-connection.js";
+import { createListenerReminder, isPlanConnectedOnThisMachine, } from "./listener-reminder.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { boardRefArgSchema, parseBoardRefText, repoNameArgSchema } from "./board-id.js";
+import { DashboardHttpClient } from "./http-client.js";
+import { cardConnect, claimSessionAgent, planConnect, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
+import { miniAppPublish } from "./mini-app-publish.js";
+import { miniAppRestore } from "./mini-app-restore.js";
+import { pluginPublish } from "./plugin-publish.js";
+import { docsRead, docsSearch, docsSourceShape } from "./docs-tools.js";
+import { spillRoleInstruction } from "./role-instruction-file.js";
+import { DEFAULT_LIMIT, MAX_SEARCH_LIMIT } from "@danxbot/docs/agent";
+import { boundedResultText } from "./result-limit.js";
+import { bodyValueSchema, queryValueSchema } from "./types.js";
+import { termsAcceptanceCallHalt, termsHaltFor } from "./terms-halt.js";
+import { danxbotApiExamplesText } from "./danxbot-api-examples.js";
+import { assertWithinTextLimit } from "./text-limit.js";
+import { registerLifecycleTools, presentCallbacksFromEnv } from "./lifecycle.js";
+import { LEGACY_TOOL_NAMES, TOOL_ACCESS } from "./tool-access.js";
+import { ToolAccessSync, ToolSurface } from "./tool-surface.js";
+import { PermissionWatch } from "./permission-watch.js";
+import { AgentGate, isAgentGateOpenCall, isAgentGateOpenSpec, onlyAgentProposalRoutes } from "./agent-gate.js";
+import { SYNC_ATTEMPTS, retryBounded } from "./bounded-retry.js";
+import { dashboardIdentity } from "./dashboard-identity.js";
+function readEnvOrDie(name) {
+    const v = process.env[name];
+    if (typeof v !== "string" || v === "") {
+        console.error(`[platform-mcp] required env var ${name} is missing or empty`);
+        process.exit(1);
+    }
+    return v;
+}
+/**
+ * Read an OPTIONAL env var, treating empty string as absent. DX-1398 — the
+ * worker injects `DANXBOT_TRACEPARENT` for a traced dispatch and substitutes it
+ * to `""` for an untraced one (the optional-placeholder default), so empty
+ * MUST read as "no trace" rather than a literal value. Never exits — an
+ * untraced dispatch is valid.
+ */
+function readEnvOptional(name) {
+    const v = process.env[name];
+    return typeof v === "string" && v !== "" ? v : undefined;
+}
+/** DX-4555 / DX-5512: optional `DANXBOT_BOARD_ID`; set, it must be a positive integer or boot fails loud (a name or a malformed value is never a board). */
+function readBoardId() {
+    const text = readEnvOptional("DANXBOT_BOARD_ID");
+    if (text === undefined)
+        return undefined;
+    const id = parseBoardRefText(text);
+    if (id === null) {
+        console.error(`[platform-mcp] DANXBOT_BOARD_ID must be a positive integer (the board's ref), got "${text}"`);
+        process.exit(1);
+    }
+    return id;
+}
+/** DX-4446: optional `DANXBOT_TEAM`; set, it must be a valid team ref or boot fails loud (no fallback to the link flow). */
+function readTeamRef() {
+    const team = readEnvOptional("DANXBOT_TEAM");
+    if (team === undefined)
+        return undefined;
+    try {
+        return assertMcpTeamRef(team);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+}
+// The dispatch config + HTTP client are LATE-BOUND (assigned by `boot()` at
+// entrypoint, below). Tool registration happens at module import and the
+// callbacks close over these `let` bindings, reading them at CALL time — so the
+// module can be IMPORTED without env (the DX-1606 tool-defs generator + its
+// drift test introspect `server`'s tool schemas without spawning a dispatch),
+// while a real run still fails loud on missing env via `boot()`.
+let config;
+let client;
+// DX-3997 — late-bound with `client`; see `listener-reminder.ts`.
+let listenerReminder;
+/**
+ * DX-4390 — this server's credential: a dispatch's env bearer, this session's approved key, or
+ * none (signed out). The plan event relay in this server signs in with it directly (`access.currentToken()`).
+ * `restart_notice` runs against other sessions' credentials and cannot see it, so `access.connection()` (the URL, where the credential is, its
+ * fingerprint; never the credential itself) is written to the session's connection record on a successful `plan_connect`
+ * for it.
+ */
+let access;
+// DX-4434 — late-bound with `access` and `client`; see `permission-request.ts`.
+let permissionRequests;
+// DX-4523 - late-bound with `access` and `client`; see `tool-surface.ts` and `permission-watch.ts`.
+let toolAccessSync;
+let permissionWatch;
+// DX-4233 - late-bound with `access`; see `plan-events-relay.ts`. The plugin's relay loop (a person's session) and an orchestrator's waiter sub-agent (DX-4667) call `plan_events_wait` on it.
+let planEventRelay;
+/**
+ * Read the dispatch's default board from DANXBOT_BOARD_ID (the board's ref number the worker injects at the spawn site) and build the HTTP client.
+ * Unset (DX-4555) leaves the server board-less: a call that needs a board must then carry its own `board`
+ * argument, or the dashboard answers 400 (DX-4592: the client no longer refuses on its behalf). A value that is not a positive integer fails loud.
+ */
+function boot() {
+    const dashboardUrl = readEnvOrDie("DANXBOT_DASHBOARD_URL");
+    const board = readBoardId();
+    const session = readSessionConfig();
+    config = {
+        baseUrl: dashboardUrl,
+        // DX-4390 — set by `SessionAccess` below; "" while signed out.
+        token: "",
+        board,
+        // DX-1398 — OPTIONAL cross-process trace context. Present → stamped on every
+        // outbound call so the agent's card writes chain under the launch; absent
+        // (untraced dispatch) → omitted, and the dashboard mints a fresh root.
+        traceparent: readEnvOptional("DANXBOT_TRACEPARENT"),
+        // DX-2683 — the working session, when there is one. See below.
+        session,
+    };
+    client = new DashboardHttpClient(config);
+    const dashboardClient = client;
+    access = new SessionAccess({
+        dashboardUrl,
+        sessionId: session?.id,
+        clientVersion: readOwnVersion(),
+        team: readTeamRef(),
+        setToken: (token) => dashboardClient.setToken(token),
+        initial: resolveInitialCredential(dashboardUrl, session?.id),
+        log: (line) => console.error(line),
+    });
+    permissionRequests = new PermissionRequests({
+        access,
+        request: (args) => dashboardClient.request(args),
+        requestOwn: (args) => dashboardClient.requestOwn(args),
+        log: (line) => console.error(line),
+    });
+    listenerReminder = createListenerReminder({
+        sessionId: config.session?.id,
+        fetchHealth: () => dashboardClient.requestOwn({ method: "GET", basePath: "", path: "/api/plan-sessions/me/listener-health" }),
+        isPlanConnected: isPlanConnectedOnThisMachine,
+        now: Date.now,
+        logLine: (line) => console.error(line),
+    });
+    // DX-4523 - a session sees only the tools it can call (`toolsFor`, `tool-access.ts`). Applied here (inside `boot()`,
+    // before `server.connect()`) as a session with no key: the bootstrap set plus the callback tools this dispatch's worker
+    // gave a URL for. `syncToolsAfterSignIn` widens it once the key's permissions are read. The DX-1606 tool-defs
+    // generator imports this module WITHOUT calling `boot()`, so it still sees every tool enabled.
+    const surface = new ToolSurface(registeredTools, presentCallbacksFromEnv(), {
+        // A dispatch's credential is the env bearer its worker injected; a person's session holds none or its own session key.
+        operatorSession: access.connection()?.source.kind !== "env",
+        onChanged: () => server.sendToolListChanged(),
+    });
+    surface.apply(new Set());
+    toolAccessSync = new ToolAccessSync({
+        surface,
+        readPermissions: readHeldPermissions,
+        log: (line) => console.error(line),
+    });
+    // DX-4233 - the relay signs in as THIS server does, with the key it holds now, as this session.
+    planEventRelay = new PlanEventRelay({
+        auth: () => {
+            const connection = access.connection();
+            return connection === null || session === undefined
+                ? null
+                : { dashboardUrl: connection.dashboardUrl, token: access.currentToken(), sessionId: session.id };
+        },
+        fetch: (input, init) => fetch(input, init),
+        sleep: realSleep,
+        now: Date.now,
+        readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
+        requestTimeoutMs: REQUEST_TIMEOUT_MS,
+        scheduleInterval: realScheduleInterval,
+        compactionFiles: compactionFilesIn(),
+        clearFiles: clearFilesIn(),
+        onAgentCreated: adoptCreatedAgent,
+    });
+    permissionWatch = new PermissionWatch({
+        dashboardUrl,
+        token: () => access.currentToken(),
+        sync: () => toolAccessSync.sync(),
+        log: (line) => console.error(line),
+    });
+}
+/**
+ * DX-4523 - this key's current permissions (`GET /api/auth/permissions`, DX-6369: the key list alone, where `/api/auth/me` composed a 27.6 KB payload that took seconds under load). A dashboard failure throws, a 401 or 403 included: a key the
+ * dashboard refuses holds nothing to advertise, and narrowing the tool list quietly would hide that.
+ */
+async function readKeyPermissions() {
+    if (!access.isSignedIn())
+        return { outcome: "no-key" };
+    // DX-5076: this process reading its own key's permissions is not the agent acting.
+    const guarded = await access.guard(() => client.requestOwn({ method: "GET", basePath: "", path: "/api/auth/permissions" }));
+    if ("halt" in guarded)
+        return { outcome: "no-key" };
+    const { result } = guarded;
+    if (termsHaltFor(result) !== null)
+        return { outcome: "terms-pending" };
+    if (!result.ok) {
+        throw new Error(`GET /api/auth/permissions answered ${result.status}: ${JSON.stringify(result.body)}`);
+    }
+    const permissions = result.body?.permissions;
+    if (!Array.isArray(permissions) || !permissions.every((p) => typeof p === "string")) {
+        throw new Error(`GET /api/auth/permissions answered without a permissions list: ${JSON.stringify(result.body)}`);
+    }
+    return { outcome: "held", permissions: new Set(permissions) };
+}
+/** The tool surface's input: the key's permissions, or null for a session that holds none (bootstrap set only). */
+async function readHeldPermissions() {
+    const key = await readKeyPermissions();
+    return key.outcome === "held" ? key.permissions : null;
+}
+/**
+ * How hard a failed permission read is for this session. A dispatch cannot work without its tools, so it retries a few times (a
+ * dashboard blip at spawn must not cost it its MCP server) and then fails the boot; an operator session logs it and keeps the
+ * bootstrap set until its next `plan_connect` or the permission stream's next connect.
+ */
+function syncPolicy() {
+    const isDispatch = access.connection()?.source.kind === "env";
+    return { attempts: isDispatch ? SYNC_ATTEMPTS : 1, fatal: isDispatch };
+}
+async function syncToolsWithPolicy() {
+    const { attempts, fatal } = syncPolicy();
+    try {
+        await retryBounded(() => toolAccessSync.sync(), { attempts, sleep: sleepHoldingProcess });
+    }
+    catch (err) {
+        if (fatal)
+            throw err;
+        console.error(`[platform-mcp] could not read this key's permissions, tools stay at the bootstrap set: ${err.message}`);
+    }
+}
+/**
+ * DX-4523 - show the tools the key's permissions allow, and watch for a grant. Called at boot and again whenever a
+ * `plan_connect` finds the session signed in, which is the moment a first approval or a re-approved key takes effect.
+ */
+async function syncToolsAfterSignIn() {
+    if (!access.isSignedIn())
+        return;
+    await syncToolsWithPolicy();
+    permissionWatch.start();
+}
+/**
+ * DX-6157 - a person created the agent this session proposed, and the dashboard signed the session in as it (and connected it to its plan or card) without a `plan_connect` from the session. The
+ * session therefore never saw a connect answer, so this does here what one that binds does: it opens the agent gate (`50arms_api` stops answering `agent_needed`), shows the tools the key's
+ * permissions allow, restarts the listener reminder's health read and, for a session now on a plan or card, writes the local connection record `restart_notice` and the listener reminder read.
+ * Called by the relay's listener as it writes the notice; a failure is a stderr line, never silence (the notice itself still reaches the session).
+ */
+function adoptCreatedAgent(created) {
+    agentGate.record({ agent: created.agent });
+    listenerReminder.invalidate();
+    const connection = access.connection();
+    if (created.plan !== null || created.card !== null) {
+        // DX-6157: the frame arrived over this key's own stream, so no credential here is a broken invariant: said loudly, as plan_connect throws on it.
+        if (connection === null) {
+            console.error("agent created: no credential after the dashboard signed this session in; the local connection record was not written");
+        }
+        else {
+            const recorded = recordSessionConnectionAfterConnect({ ok: true }, { sessionId: config.session?.id, projectKey: projectKeyOf(process.cwd()), dashboardUrl: connection.dashboardUrl, source: connection.source, fingerprint: connection.fingerprint });
+            if (recorded.connection_record_error !== undefined)
+                console.error(`agent created: ${recorded.connection_record_error}`);
+        }
+    }
+    syncToolsAfterSignIn().catch((err) => console.error(`agent created: showing the tools after the sign-in failed: ${err.message}`));
+}
+/**
+ * Before `server.connect` nothing reads stdin, so an unref'd timer (`defaultSleep`) would let the process exit silently with
+ * code 0 in the middle of the retry. This one keeps the process alive until it fires.
+ */
+const sleepHoldingProcess = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * DX-2862 / DX-4390 — the credential this server boots with, through the ONE resolver
+ * `restart_notice` also uses (`session-options.ts`), so a session's tools and its lookups can never sign in as
+ * two different identities. None is not an error: the server boots signed out. A stored key that
+ * is there but unusable is reported loudly and deleted - it is a cache of a revocable key, and the
+ * session asks for a new one.
+ */
+function resolveInitialCredential(dashboardUrl, sessionId) {
+    try {
+        return resolveBootCredential(process.env, { dashboardUrl, sessionId });
+    }
+    catch (err) {
+        if (!(err instanceof SessionKeyUnusableError) || sessionId === undefined)
+            throw err;
+        console.error(`[platform-mcp] ${err.message}; deleting it, this session must request access again`);
+        deleteSessionKey(err.path);
+        return null;
+    }
+}
+/**
+ * DX-2683 — WHO THIS SESSION IS, read from the environment Claude Code
+ * already provides.
+ *
+ * `CLAUDE_CODE_SESSION_ID` is set on every process an interactive Claude Code
+ * session spawns — this server among them — so no launcher, no dispatch
+ * overlay and no agent cooperation is needed for a session to be identifiable.
+ *
+ * OPTIONAL, unlike every other env this package reads. A process running
+ * outside a Claude Code session has no session to report; it sends no session
+ * headers and behaves exactly as this package did before. Requiring it would
+ * break the tool-defs generator, the drift test, and any non-Claude consumer.
+ *
+ * NO TITLE HERE AT ALL (DX-2816, revised). This used to guess one from
+ * `basename(process.cwd())`, which is how a dashboard Connect list ended up
+ * showing "gpt-manager" for a session Claude itself calls "Fix program
+ * status tracking" — the repo name told two sessions in the same checkout
+ * apart from EACH OTHER, but never matched what the operator sees in Claude.
+ * A later `DANX_SESSION_TITLE` env fallback was tried next and also removed:
+ * DX-2816's research found no documented env var, hook input, or
+ * MCP-server-reachable signal carries Claude's own session title — this
+ * SERVER genuinely cannot read it. The AGENT can, though (a Desktop-side
+ * `get_session` tool this server has no access to), and the agent is what
+ * calls `plan_connect` — so the title travels as that tool's own `title`
+ * argument (see `handlers.ts#planConnect`) at connect time, not as a header
+ * stamped here. DX-4461: the session's TRANSCRIPT carries every rename as a
+ * `custom-title` record, so the event relay in this server reads it from
+ * there and reports it on its heartbeat (`session-title.ts`) and a later rename needs no
+ * agent call. A session that never connects with a title keeps the
+ * dashboard's own placeholder (`session <id prefix>`) until the relay reports
+ * one — an honest placeholder beats a guess.
+ */
+function readSessionConfig() {
+    const id = readEnvOptional("CLAUDE_CODE_SESSION_ID");
+    if (id === undefined)
+        return undefined;
+    return { id };
+}
+// DX-5549: whether this session holds a team agent; closed by a plan_connect answer of `agent_needed` / `agent_limit_reached`, opened only by one carrying an agent.
+const agentGate = new AgentGate();
+/**
+ * DX-3465 (PLN-11 R-25) — the conventions shared by every `50arms_api` call,
+ * stated once here instead of on each tool. DX-4525 / DX-4015: its first paragraph makes `50arms_api` THE channel and says
+ * to read the spec first (an agent skipping the spec is a behaviour to fix, not a reason to keep a tool per job).
+ *
+ * DX-4318 — this block is the ONE home of the stale-hash rule and of the
+ * writing standard (PLN-11 R-24): it is the only text every caller of these
+ * tools receives (operator sessions, their sub-agents, every dispatch
+ * profile). It was 3,916 characters and Claude Code delivered the first
+ * 2,048, so both rules were cut from every session. `assertWithinTextLimit`
+ * below refuses a block that would be cut again. Behaviour only, no rationale.
+ */
+const SERVER_INSTRUCTIONS = `\
+\`50arms_api\` is your primary channel to the dashboard: every card, plan, Slack and dispatch-callback job (ending
+yours too) is a call to it. Find a route with \`50arms_api_list\`. Read its exact shape with
+\`50arms_api_spec\` before the first call to any route you have not called before; never guess a body.
+
+RESOURCES. Most collections take GET (list) and POST (create); a single resource (\`<collection>/<id>\`) takes
+GET, PATCH or PUT (send only the fields you change) and DELETE. A card is edited at
+\`PATCH /api/issues/<id>/edit\`. A card get answers the compact row; the card list answers a compact row per card, one page of 50 with
+\`total\` (page with \`limit\` and \`offset\`). Name each other field or relation you need in the \`fields\` query
+tree. \`GET /api/resources/<resource>/fields\` lists the names.
+
+STALE HASH. A write to contested text sends back the \`content_hash\` or \`base_hash\` you read. A stale content write is
+never refused: \`collided\` says what it met, so re-read. Only 409 \`merge_base_unknown\` is: reapply your
+change to the text and hash it returns. Settings and sign-offs still refuse a stale hash: re-read, then write again.
+
+REFUSALS. A 4xx body is \`{error, ...}\`, and its other fields name the fix: \`offending_keys\`, \`failed_gate\`,
+\`unresolved_items\`, \`did_you_mean\`.
+
+WRITING STANDARD, for every title, summary, description, comment, problem, solution and plan record you write. The
+reader is new to the subject and will not read the code or docs: what you write is their documentation. Open with
+plain background (what it is, why, what is wrong or changes) before evidence.
+Define each term a newcomer would not know. Cite exact ids (\`PBLM-2757\`, not "problem 2757"), SHAs and paths. Be brief; never transcribe reasoning. A title or summary alone must let the reader decide.
+
+DESIGN. UI designs and style options go on the card they concern (\`mini_app_publish\`), never an Artifact or HTML page.
+Options are design states, never a chat or text question; a person chooses.
+`;
+assertWithinTextLimit("the server instructions", SERVER_INSTRUCTIONS);
+export const server = new McpServer({
+    name: "platform-mcp",
+    version: "0.1.0",
+}, { instructions: SERVER_INSTRUCTIONS });
+function haltResult(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+/** The dashboard this session is connected to, named (`dashboard-identity.ts`). ONE source: `config.baseUrl`, the URL every call goes to. */
+function connectedDashboard() {
+    return dashboardIdentity(config.baseUrl);
+}
+/**
+ * DX-4390 — `plan_connect`'s answer while access is not in place: the request (or why there is none),
+ * an error when it names a failure. `note` says why a new request was needed.
+ */
+function accessReply(ready, note) {
+    // the dashboard this session is on is named in the sign-in answer, so a session aimed at the wrong dashboard shows it before any write
+    if (ready.signedIn)
+        return jsonResult({ state: "signed_in", ...(note ? { note } : {}), dashboard: connectedDashboard() });
+    // DX-4418: a person revoked this session's access: the one stop halt, verbatim, never a request.
+    if (ready.halt !== undefined)
+        return haltResult(ready.halt);
+    // DX-6392: every access answer names the dashboard it is on, not only the signed-in one (AC 57978).
+    const answer = { ...ready.answer, dashboard: connectedDashboard(), ...(note ? { note } : {}) };
+    return ready.isError ? haltResult(JSON.stringify(answer)) : jsonResult(answer);
+}
+// DX-4390 / DX-4434 / DX-5549 / DX-5550: every tool's dashboard call goes through `guardedCall` (the agent gate, then the sign-in halt; see `guarded-calls.ts`).
+const { guardedCall } = makeGuardedCalls({ access: () => access, gate: agentGate });
+/** DX-4390 — a tool's dashboard call behind the sign-in halt (and the 401 sign-out). */
+async function guardedJson(run) {
+    const guarded = await guardedCall(run);
+    return "halt" in guarded ? haltResult(guarded.halt) : jsonResult(guarded.result);
+}
+/** DX-4400 — `guardedJson` for the read tools whose answer can be a whole document: bounded. */
+async function guardedBoundedJson(run, opts) {
+    const guarded = await guardedCall(run, opts);
+    return "halt" in guarded ? haltResult(guarded.halt) : boundedJsonResult(guarded.result);
+}
+function jsonResult(value) {
+    return {
+        // DX-4400: compact — nothing parses the indentation and it costs every call 16% to 55% more characters.
+        content: [{ type: "text", text: JSON.stringify(value) }],
+    };
+}
+/** DX-4400 / DX-6117 — a dashboard route's result, its body delivered as a file when over `MCP_MAX_RESULT_CHARS`. */
+function boundedJsonResult(result) {
+    return { content: [{ type: "text", text: boundedResultText(result) }] };
+}
+/** DX-4523 - every tool `strictTool` registered, by name: what `ToolSurface` switches. */
+const registeredTools = new Map();
+/**
+ * DX-3238 — every tool on this server MUST reject an undeclared/mistyped
+ * argument instead of silently stripping it. `server.tool(name, description,
+ * shape, cb)` builds its input schema as a bare `z.object(shape)` internally
+ * (via the SDK's own `objectFromShape`), and zod's default behaviour for an
+ * object schema is to STRIP any key not in `shape` — so a caller's typo (or a
+ * field the route accepts but this tool never declared, e.g. the issue-create
+ * route's `priority` before this card) vanished before the HTTP request was even
+ * built, and the server's own fail-loud checks (e.g. `parseFilterObject`'s
+ * "Unknown filter key" 400) never got a chance to run.
+ *
+ * `strictTool` is the ONE place that fixes this for every tool at once: it
+ * wraps `shape` in `z.object(shape).strict()` itself and registers it via
+ * `registerTool` (the SDK preserves a pre-built Zod object schema's `.strict()`
+ * verbatim through `normalizeObjectSchema` — passing the same `shape` to the
+ * deprecated `server.tool(...)` overload instead would NOT: that overload only
+ * accepts a raw shape, which the SDK rebuilds as a plain `z.object(shape)`
+ * with no strict flag). A zod-rejected extra/misspelled key now throws
+ * `McpError(InvalidParams, ...)` naming the offending key and the accepted
+ * set, exactly like the dashboard's own `parseFilterObject` refusal.
+ */
+function strictTool(name, description, shape, cb) {
+    // DX-4318 — the one registration path, so no tool can ship a description an agent would receive cut.
+    assertWithinTextLimit(`the "${name}" tool description`, description);
+    // DX-4523 - the same path, so no tool can ship without declaring what makes it usable.
+    if (!Object.hasOwn(TOOL_ACCESS, name)) {
+        throw new Error(`the "${name}" tool has no entry in TOOL_ACCESS (tool-access.ts): declare what makes it usable`);
+    }
+    const tool = server.registerTool(name, { description, inputSchema: z.object(shape).strict() }, cb);
+    registeredTools.set(name, tool);
+    return tool;
+}
+/**
+ * DX-6847 / DX-6864 (DEC-571): registers a tool the rename gave a new name (`LEGACY_TOOL_NAMES`) under its current name AND the name it had before. Both
+ * registrations share one schema and one handler (built per name, so an answer names the tool that was called), which is what makes the two answer identically;
+ * the old name's description only points at the new one. DX-6864 removes the old registration.
+ */
+function renamedTool(name, description, shape, handlerFor) {
+    strictTool(name, description, shape, handlerFor(name));
+    const legacy = LEGACY_TOOL_NAMES[name];
+    strictTool(legacy, `The previous name of \`${name}\`: the same tool, answering identically. Use \`${name}\`; this name will be removed.`, shape, handlerFor(legacy));
+}
+// ---------------- lifecycle tool set (DX-3465 / PLN-11 R-25, DX-4525) ----------------
+// One tool is left, `50arms_slack_reply` (it reads local files); every other dispatch callback is a `50arms_api` call
+// (see `lifecycle.ts`). `toolsFor` (`tool-access.ts`) decides whether a session sees it.
+registerLifecycleTools(renamedTool);
+// Optional per-call board override shared by every tool. Omitted → the
+// dispatch's env-derived board (`DANXBOT_BOARD_ID`) is used; provided → that
+// board is targeted instead (the dashboard owns board→repo and 404s an
+// unknown board). The override is a board ref (a number, or its decimal
+// text), forwarded as the number: what the dashboard accepts beyond a ref
+// is decided by its `parseRefNum`, never here. Spread into each
+// tool's Zod input object so cross-board work is reachable from any
+// dispatch without rebinding the MCP server.
+const boardField = {
+    board: boardRefArgSchema
+        .optional()
+        .describe("Board ref (the number); omit for this dispatch's board (none when this server has no default board), except on `GET /api/issues`, where omitting it lists the whole team across every board. Unknown → 404."),
+};
+// DX-3465 (code-architecture gate finding, at 275f82c0d) — `resource_fields`
+// (DX-3426) was deleted from here: it was a dedicated wrapper around a plain
+// `GET /api/resources/:resource/fields`, which `50arms_api` already reaches
+// with no agent-specific behavior earning it its own tool (R-25 keeps a
+// dedicated tool only for what's genuinely agent-specific — session binding,
+// local-file reads, dispatch lifecycle). Call
+// `50arms_api({method:"GET", path:"/api/resources/<resource>/fields"})`
+// instead; the route and its response shape are unchanged.
+// ---------------- 50arms_api (DX-3465, PLN-11 R-25) ----------------
+renamedTool("50arms_api", 
+// DX-3997 — `reminders[]` also relays the dashboard's own listener reminder
+// to a plan-connected session; the reminder's text explains itself.
+"Call any dashboard API route your credential may reach. The answer is the route's JSON body: act on its " +
+    "`reminders[]` when present. " +
+    // DX-4015 / DX-4525 — narrows SERVER_INSTRUCTIONS' general spec-first rule: a write shown below is
+    // copied from its example (3 of 3 canary sessions did, with zero 4xx), so only a write NOT shown, and
+    // always the retro, needs a spec call first.
+    "Before your first write to a route not shown below, and always before `PUT /api/issues/:id/retro`, " +
+    "call `50arms_api_spec`. " +
+    // DX-3923 — the shapes agents guessed wrong most often, shown before the
+    // first call instead of learned from a 4xx.
+    danxbotApiExamplesText(), {
+    method: z.enum(DANXBOT_API_METHODS),
+    path: z
+        .string()
+        .min(1)
+        .startsWith("/api/")
+        .describe('Full path starting with "/api/" — never a route template.'),
+    // DX-3465 — a query value may be a scalar, a field TREE (a plain
+    // object, e.g. `{"description":true,"comments":{"limit":20}}` — see
+    // SERVER_INSTRUCTIONS above and the OpenAPI spec's `fields` schema), an
+    // array of scalars (e.g. `ids` on the batch-get route); a list's sort is
+    // two scalars, `sort` + `order` (DX-4492).
+    // `DashboardHttpClient#buildUrl` JSON-encodes a plain object but
+    // comma-joins an array, matching the shapes the server actually parses
+    // (a JSON tree vs. a comma-separated list param).
+    query: queryValueSchema.optional(),
+    // DX-3685 — was `z.unknown()` (JSON Schema `{}`), which gave the model
+    // no structural hint that a body must be an OBJECT, so it sometimes
+    // sent `body` as a JSON-encoded string; `http-client.ts` then
+    // `JSON.stringify`'d that string again, and every dashboard route
+    // refused the resulting JSON-string-literal body with `body: must be an
+    // object` (every route's body schema is object-only — see
+    // `bodyValueSchema`'s own doc in `types.ts`). A string/array/etc body
+    // now fails zod validation at this boundary with a clear message
+    // instead of reaching the dashboard malformed.
+    body: bodyValueSchema.optional(),
+    // DX-5724 - the raw-file counterpart of `body`: this server reads the file, so its bytes never pass through your context.
+    body_file: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Absolute path of an image file (png, jpg, webp, svg; max 1 MB) sent as the raw body instead of `body`."),
+    ...boardField,
+    // DX-5033 - sends x-danx-plugin-background (see DanxbotApiArgs.background); an agent setting it would hide its own calls from the pause and idle logic.
+    background: z.boolean().optional().describe("Set only by plugin hooks; an agent never sets it."),
+}, 
+// DX-3997 — the result rides back verbatim, plus the dashboard's own `reminders[]` entries
+// for this plan-connected session (the server decides; `listener-reminder.ts` only relays).
+(calledAs) => async (args) => {
+    // DX-4148 — an agent never accepts the Terms, and a terms refusal halts it (see terms-halt.ts).
+    const refused = termsAcceptanceCallHalt(args, config.baseUrl);
+    if (refused)
+        return haltResult(refused);
+    const guarded = await guardedCall(() => danxbotApi(client, args), { gateOpen: isAgentGateOpenCall(args.method, args.path) });
+    if ("halt" in guarded)
+        return haltResult(guarded.halt);
+    const result = guarded.result;
+    const halt = termsHaltFor(result);
+    if (halt)
+        return haltResult(halt);
+    // DX-6089: `GET /api/plan-sessions/me/role`'s role text lands in a local file; the reply names it.
+    const spilled = spillRoleInstruction(result);
+    // DX-6556: a manual pickup that connected the session is a connect, whatever tool carried it.
+    if (isPickupConnect(spilled))
+        return finishConnect(calledAs, spilled, false);
+    return boundedJsonResult(await listenerReminder.apply(spilled));
+});
+// ---------------- 50arms_api_list (DX-3465 A5, PLN-11 R-25) ----------------
+renamedTool("50arms_api_list", 
+// DX-3528 — the list is filtered by the same permission check every request takes.
+"Start here to find the route for any job: lists the dashboard API routes your credential may call, `{routes: " +
+    "[\"METHOD /path/template\", ...]}`, the strings `50arms_api_spec` takes (`POST /api/issues/:id/transition`). A route " +
+    "not listed is not callable by you.", {}, 
+// DX-5765: with no agent held it lists exactly the two proposal routes an agent-less session may call.
+() => async () => {
+    const noAgent = agentGate.current() !== null;
+    return guardedBoundedJson(async () => {
+        const listed = await danxbotApiList(client);
+        return noAgent ? onlyAgentProposalRoutes(listed) : listed;
+    }, { gateOpen: noAgent });
+});
+// ---------------- 50arms_api_spec (DX-3465, PLN-11 R-25) ----------------
+renamedTool("50arms_api_spec", 
+// DX-3527 — the contract is generated from the route table. DX-4015 / DX-4525 — read before the first call to a route you
+// have not called: `50arms_api` is the only channel, and a guessed body is a 4xx or a wrong terminal call.
+"Read this before your first `50arms_api` call to any route you have not called before. The OpenAPI 3.1 contract for the " +
+    "routes you name: request and response shape, required permission and " +
+    'every documented error. `endpoints`: `"METHOD /path/template"` strings as `50arms_api_list` reports them ' +
+    '(e.g. `"POST /api/issues/:id/transition"`), never a real path with ids. An endpoint the dashboard does ' +
+    "not serve, or your credential may not call, is refused and named.", {
+    endpoints: z.array(z.string().min(1)).min(1),
+}, 
+// DX-5765: with no agent held it answers for the two proposal routes only; any other endpoint keeps the no-agent answer.
+() => async (args) => {
+    return guardedBoundedJson(() => danxbotApiSpec(client, args), { gateOpen: isAgentGateOpenSpec(args.endpoints) });
+});
+// ---------------- attach_file (DX-3465 A4, checklist item 36140) ----------------
+//
+// The "25 MB" ceiling quoted below tracks the backend route's
+// MAX_DECODED_BYTES (`src/issues/write/attachments.ts`). This package is a
+// separate published artifact and cannot import that constant, so the
+// number is restated here as prose — keep the two in sync if the backend
+// ceiling moves. Opt-in (R-25's "operations about the agent itself" carve-
+// out plus a role-by-role grant, see `tool-defs.ts`'s `MCP_SERVER_OPT_IN_TOOLS`
+// — a role needs local-file-upload only when it deals with files an agent
+// might hold locally, e.g. the Slack recovery agent's CSV path).
+strictTool("attach_file", "Upload a LOCAL file. This server reads and uploads the bytes, so they never pass through your context. " +
+    "`target: \"card\"` (default) attaches it to a card; `target: \"inline_image\"` uploads an image for a markdown body and replies `{url, markdown}` (below). The card attachment mirrors to the card's linked Trello card and Slack thread. 25 MB limit (413). " +
+    "Card target returns `{issue, attachment_id, url, thumbnail_url, is_primary}`: `url` is permanent, embed it in any " +
+    "markdown field as `![description](url)` and it renders inline. Use it when a screenshot or file judges something faster than prose, or instead of pasting a " +
+    "large CSV or log into a card field. " +
+    "`target: \"inline_image\"` instead uploads a local png/jpeg/gif/webp/avif (25 MB) with NO card and returns `{url, markdown}`: put the " +
+    "markdown in any markdown body, notably a `POST /api/feedback` body (`50arms_api`'s `body_file` sends one raw png/jpg/webp/svg of at most 1 MB to a route that takes a file; this tool adds the upload routes, gif/avif, and the 25 MB limit).", {
+    target: z.enum(["card", "inline_image"]).optional().describe("`card` (default): attach to a card. `inline_image`: upload an image for a markdown body; takes only `path`."),
+    card_id: z.string().min(1).optional().describe("The card id to attach the file to. Required for target `card`; not allowed with `inline_image`."),
+    path: z.string().min(1).describe("Absolute local path on the machine this server runs on (`/tmp/a.png` or `C:\\x\\a.png`)."),
+    filename: z.string().min(1).optional().describe("Override for the stored filename; default: path's basename."),
+    content_type: z.string().min(1).optional().describe("Override for the stored MIME type; default: an extension guess."),
+    replaces: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Id of this card's attachment to replace in place: it keeps its id, name and cover flag. Not with `filename`."),
+    primary: z.boolean().optional().describe("Make this attachment the card's single cover (lead image)."),
+    ...boardField,
+}, async (args) => guardedJson(() => attachFile(client, args)));
+// ---------------- mini_app_publish (DX-5294, replaces DX-4077's design_publish) ----------------
+//
+// Agent-specific, so a dedicated tool (R-25): it runs the repo's own build command in the agent's OWN checkout, which the dashboard
+// cannot do (no connected repo's source or toolchain), and uploads the result. Opt-in (`tool-defs.ts`'s `MCP_SERVER_OPT_IN_TOOLS`) and
+// granted to no profile here: a default tool would add its schema to every default-all role's first turn, and a role with no worktree or
+// toolchain can only fail it. The package takes no `vite` or `playwright` dependency: the build is the repo's command, and the browser is
+// resolved from the repo at run time (`design-screenshot.ts`).
+strictTool("mini_app_publish", "Build a page with this repo's own mini app and publish it as a revision of one of an existing card's designs, or as a new design on it. " +
+    "The design is a gitignored, untracked working folder (`dir`) of text files that the repo's committed build command turns into a page; it may be a whole front-end app, and how to split its states is your call. " +
+    "The board's own design guidance lives in the `plan-design` gate's reviewer prompt: `50arms_api` GET " +
+    "/api/boards/<board> with fields {controls: true}, the row keyed `quality_gate.plan-design.reviewer_prompt`, field `value`. " +
+    "`target.name` is one of the repo's mini app targets (GET /api/repos/<repo> with fields {mini_app_targets: true}): a build command, run in the repo root with no shell " +
+    "and `dir` (repo-relative) and a fresh temporary output folder (absolute) as its last two arguments, which it writes `index.html`, one .js and one .css into. Its script must be committed and unchanged from HEAD. " +
+    "`target.repo` defaults to the card's board's repo; name it for another repo's mini app. " +
+    "`destination.card_id` is the card (not an Epic or Feature). " +
+    "A card holds several designs: pass `destination.design_title` with `destination.design_element` (what it decides) to start a NEW design, or `destination.design_no` (from the card's `designs` relation) to add a revision; exactly one. " +
+    "`option_groups` are the axes a person picks on; restate them every revision (the latest decides). " +
+    "A new design joins its element's open problem; else send `problem_*`. " +
+    "Returns `{card_id, design_no, revision_no, dashboard_url, local_html_path, " +
+    "screenshot}`: `local_html_path` is the built page; `screenshot` is " +
+    "`captured` (1280x800) or `none: <reason>` (the publish still succeeds). A build error comes back as the command's own output, and a " +
+    "refused revision (400, 409, 413) verbatim with the `card_id`: fix the " +
+    "design and call again. Limits: the frame has no network (use fixture props); on Windows name `node` and a committed script, never npm or npx.", {
+    target: z
+        .object({
+        repo: repoNameArgSchema.optional().describe("The name of the repo whose mini app builds the page; default: the repo of the card's board."),
+        name: z.string().min(1).describe("A mini app target's name, as listed in `mini_app_targets` of `GET /api/repos/<repo name>` (`50arms_api`, fields {mini_app_targets: true})."),
+    })
+        .strict(),
+    dir: z
+        .string()
+        .min(1)
+        .describe("The design folder: absolute, or relative to this server's cwd. Inside the repo checkout, gitignored and untracked."),
+    note: z
+        .string()
+        .min(1)
+        .describe("The revision note, shown beside the revision on the card: what changed since the last revision, which decision note it answers, what is still open."),
+    destination: z
+        .object({
+        kind: z.literal("card_design").describe("Where the page goes: a design of a card."),
+        card_id: z.string().min(1).describe("The card this design goes on: any existing card but an Epic or Feature."),
+        design_no: z.number().int().positive().optional().describe("Add a revision to this existing design of the card (its `designs` relation). Not with `design_title`."),
+        design_title: z.string().min(1).optional().describe("Start a NEW design on the card with this title, fixed for good. Not with `design_no`."),
+        design_element: z.string().min(1).optional().describe("With `design_title` (required there, refused with `design_no`): the one thing this design decides, a few words (\"Indicator pill\", \"Popover layout\"). It joins that element's open design problem, matched ignoring case and extra spaces."),
+    })
+        .strict(),
+    option_groups: z
+        .array(z
+        .object({
+        key: z.string().describe("The stable id a pick is recorded under (non-blank, at most 40 characters, unique among the groups)."),
+        label: z.string().describe("The group's name as the viewer shows it (non-blank, at most 30 characters)."),
+        options: z.array(z.string()).describe("The group's choices, each one short phrase, word or letter (non-blank, at most 30 characters, unique in the group)."),
+        multiple: z.boolean().describe("true when a person may pick several options, false for exactly one."),
+        recommended: z.array(z.string()).describe("Your recommended pick(s), each one of `options`: exactly one when `multiple` is false, at least one when true. Every group starts on them."),
+    })
+        .strict())
+        .optional()
+        .describe("The option groups a person picks from when choosing this design: one per axis of LOOK they decide on (a layout, a style, a marker), with your recommendation. The viewer draws the groups above the design and the design reads the picks with its repo's kit (in danxbot, `useDesignOption`); never hand-build a toggle row for one, and never make the STATE of the example contents (empty, loading, error, many items) a group: show state inside the page. " +
+        "RESTATE the groups on every revision: omitting this declares none and the latest revision's groups decide what is offered. Genuinely different approaches are separate designs, each with its own groups. " +
+        "The server is the only validator (at most 12 groups, 30 options each); a broken rule comes back as a 400 naming it."),
+    checklist: z
+        .array(z.string())
+        .min(1)
+        .describe("The design checklist: 1 to 30 brief items (each at most 300 characters), one per thing this design adds or changes: name it, where it is and why it is there, so the reviewer ignores everything that already existed. " +
+        "Never the option groups, the states or widths to look at, or steps to follow. " +
+        "RESTATE it whole every revision (a new revision starts unticked). Ticking never blocks approval. A missing or empty list, or a blank item, is a 400."),
+    browser_check: z
+        .object({
+        status: z.enum(["checked", "not_checked"]).describe("checked: you looked at it in a browser; not_checked: you had none."),
+        note: z
+            .string()
+            .regex(/\S/)
+            .max(500)
+            .describe("checked: what you checked; not_checked: why you had no browser."),
+    })
+        .strict()
+        .describe("REQUIRED: did you check this revision in a browser? not_checked shows a red warning and tells the operator; never claim checked unseen."),
+    problem_statement: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("With `design_title`; required when this publish opens a design problem (no open one for `design_element`), refused otherwise: one plain question naming what is being designed, at most 200 characters."),
+    problem_summary: z.string().min(1).optional().describe("With `problem_statement`: 1-3 plain sentences."),
+    problem_context: z.string().min(1).optional().describe("With `problem_statement`: markdown background for a first-time reader."),
+}, async (args) => guardedJson(() => miniAppPublish(client, args, { baseUrl: config.baseUrl, cwd: process.cwd() })));
+// ---------------- mini_app_restore (DX-6070) ----------------
+//
+// Agent-specific like mini_app_publish: it WRITES local files, which `50arms_api` cannot. A design's source is stored with every revision on the
+// dashboard; this puts one revision's folder back on disk so a designer in a checkout that lacks it can revise instead of starting empty.
+// Opt-in and granted wherever mini_app_publish is.
+strictTool("mini_app_restore", "Write a design revision's stored source back to disk, in this repo checkout, so you can revise a design whose gitignored folder is missing here (another worktree, another machine). " +
+    "Every revision keeps its design folder's text files on the dashboard; run this BEFORE editing and publishing the next revision of a design whose `design_dir` is missing or empty in your checkout. " +
+    "`revision_no` defaults to the design's latest. Each file goes at its repo-relative path under this server's checkout (the git top level of its cwd). " +
+    "Refused before any write, naming each path: a path outside the revision's `design_dir`, or a file that exists locally with DIFFERENT content (unpublished work is never overwritten). " +
+    "Files with equal content are `unchanged`; files in the folder that the revision lacks are left alone and listed in `extra_local`. " +
+    "Returns `{design_dir, revision_no, built_from_commit, written, unchanged, extra_local}`.", {
+    card_id: z.string().min(1).describe("The card the design is on."),
+    design_no: z.number().int().positive().describe("The design's number on the card (its `designs` relation)."),
+    revision_no: z.number().int().positive().optional().describe("The revision to restore; default: the design's latest."),
+}, async (args) => guardedJson(() => miniAppRestore(client, args, { cwd: process.cwd() })));
+// ---------------- plugin_publish (DX-5237, parent DX-4679) ----------------
+//
+// Agent-specific like mini_app_publish: it builds in the agent's OWN checkout (`npm run build` in a short-lived child process) and uploads the
+// result, which the dashboard cannot do. The build, archive and upload are `@danxbot/plugin-sdk/publish`, shared with the `danx-plugin`
+// CLI; the screenshot is this tool's alone. Opt-in for the same reason as mini_app_publish (`tool-defs.ts`'s `MCP_SERVER_OPT_IN_TOOLS`).
+strictTool("plugin_publish", "Build a card-type plugin project (Vite, `danxPlugin()` from `@danxbot/plugin-sdk/vite`, a lockfile) with its own `npm run build` and publish it as a new revision of the team's plugin " +
+    "`plugin` (a new key creates it): uploads `dist/`, the source `.tar.gz` and a screenshot of the plugin's own render (its `CardView` drawn with a sample card on the dashboard's `/plugin-preview` page). " +
+    "Returns `{ok: true, status, body: {plugin, plugin_id, revision_id, revision_no, approval_url, screenshot}}`: `approval_url` is Settings > Plugins, where a team admin approves the revision; you cannot. " +
+    "`screenshot` is `captured` or `none: <reason>` (the publish still succeeds). A build error throws with the build's output; a refused upload comes back verbatim as `{ok: false, status, body, plugin, step}`.", {
+    dir: z.string().min(1).describe("The project directory: absolute, or relative to this server's cwd."),
+    plugin: z.string().min(1).describe("The plugin's key: lowercase letters, digits, - and _, at most 64."),
+    note: z.string().min(1).describe("What this revision changes, shown to the approver."),
+    name: z.string().min(1).optional().describe("Display name for a plugin this call creates; default: the key."),
+}, async (args) => guardedJson(() => pluginPublish(client, args, { baseUrl: config.baseUrl, cwd: process.cwd() })));
+// ---------------- docs_search / docs_read (DX-5582) ----------------
+//
+// One pair of tools over three places a docs root lives (`source`): this checkout's `docs/pages`, another local docs root, or a team repo's hosted
+// docs on the dashboard. They answer with file paths and sizes, never page text (`docs-tools.ts`): `50arms_api` answers into context and cannot write
+// the local file a remote page is read from. Opt-in like `plugin_publish` (`tool-defs.ts`'s `MCP_SERVER_OPT_IN_TOOLS`).
+strictTool("docs_search", "Search docs with the shared @danxbot/docs engine. Returns `{query, results: [{id, type, title, summary, file, bytes, lines, look_in?}]}`, best first, never a page body; " +
+    "then `docs_read` the id you pick. `file` is an absolute path for local/dir and the page's path in the repo's docs for remote; `bytes`/`lines` size it for offset/limit reads.", {
+    source: docsSourceShape,
+    query: z.string().min(1).describe("A question or the words a page would use."),
+    limit: z.number().int().min(1).max(MAX_SEARCH_LIMIT).optional().describe(`Most results (default ${DEFAULT_LIMIT}).`),
+}, async (args) => guardedJson(() => docsSearch(client, args, { cwd: process.cwd() })));
+strictTool("docs_read", "Get a docs page as a file on this machine: returns `{id, path, bytes, lines}`, never the text. local/dir: the page's own file. remote: a fresh copy fetched from the dashboard into the temp directory. " +
+    "Read `path` with your own file tools (offset/limit, grep). An unknown id is refused with the nearest ids.", {
+    source: docsSourceShape,
+    id: z.string().min(1).describe("A page id from docs_search, e.g. topic.mini-apps."),
+}, async (args) => guardedJson(() => docsRead(client, args, { cwd: process.cwd() })));
+// ---------------- request_permission (DX-4434, parent DX-4432) ----------------
+strictTool("request_permission", "Ask a person to grant this key ONE MORE permission. Call it when a call was refused `403 forbidden` naming a " +
+    "`permission`, or you know you need one more. It returns AT ONCE with `{state, approvalUrl, confirmCode, " +
+    "instruction}`: show the person the code and URL, and keep working on anything else. It waits until this session " +
+    "ends; if expired, reconnect and ask again. If they approve, a " +
+    "later call just succeeds with the same key. The same ask while " +
+    "pending returns the pending request. A refusal (unknown permission, already held, rate limited) comes back as " +
+    "`{ok:false, status, body}`. If you are blocked without it, raise a problem on the card.", {
+    permissions: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe("The permission keys to ask for: the `permission` a `403 forbidden` named."),
+    reason: z.string().min(1).describe("Why you need them; shown to the person who approves."),
+}, async (args) => {
+    const asked = await permissionRequests.ask(args);
+    if ("halt" in asked)
+        return haltResult(asked.halt);
+    if ("result" in asked) {
+        // DX-4148 — a terms refusal halts here as on every dashboard call.
+        const halt = termsHaltFor(asked.result);
+        return halt ? haltResult(halt) : jsonResult(asked.result);
+    }
+    return jsonResult(asked.answer);
+});
+// ---------------- plans (DX-2683) ----------------
+// THE BINDING ASYMMETRY IS IN THE SCHEMAS, NOT IN PROSE. `GET /api/plans/:planId`
+// takes a plan id in its path; the plan records, plan cards and
+// architecture-section routes under `/api/plans/mine/...` take NO plan id in
+// any form, so a connected session cannot even express "write to that other
+// plan". `plan_connect` takes a plan id because binding a session to a plan
+// is the one operation that is ABOUT a plan id — and it can only ever bind
+// the caller's own session. `POST /api/plans` also takes no plan id, but for
+// a different reason: it MAKES a plan rather than acting on one, so there is
+// no existing plan for an id to name yet.
+strictTool("plan_connect", 
+// DX-4493 — the `naming` block carries the thread title the session must take before it connects.
+// DX-4318 — states only what to do with the reply. What it used to add arrives where it is used: a rejected
+// action's rule in the event line itself (`listen.ts`), the mantra in the reply's own `reminders[]` text.
+// DX-4390 — signed out, this is also how the session asks for access.
+"Connect THIS session to a plan; one call is enough to start. Signed out, it requests access instead: " +
+    "the reply is `state: approval_required` or `approval_pending` with an `approvalUrl` and `confirmCode` " +
+    "(show the code, open the URL, then call again; it waits until this session ends; a call re-asks an expired one). " +
+    "Signed in, the reply carries `owedComments` (person comments no agent has answered yet: read first, answer each, ack then reply) and `missedEvents` (operator " +
+    "events no session had been told about: read next), " +
+    "`browserInstruction` (do it now), `briefing` (the plan's goals, rules, caveats, architecture " +
+    "titles and a first page of open cards) and `listenerHealth` (when its `state` is not `healthy`, do its " +
+    "`nextStep`). A session is on at most one plan: connecting elsewhere moves it (`movedFrom` names the " +
+    "plan it left). A plan holds one live session: when another is on it the connect is refused " +
+    "`plan_has_live_session`, naming that session; do not retry: tell the person which session holds " +
+    "it and connect elsewhere. A session whose plan another took while it was quiet is refused its next `/api/plans/mine/...` call: connect elsewhere or ask the person. Afterwards `50arms_api` calls to `/api/plans/mine/...` act on this plan, no plan id. " +
+    "Connecting signs you in as a team agent: `agent`/`agentInstruction` say who you are. " +
+    "No agent to sign in as: `agent_needed` (none exists for you; propose one) or `agent_limit_reached` (the member's or team's cap on sessions signed in as an agent is full; the person ends another session or raises the cap), nothing connects: follow its `instruction`, " +
+    "no other dashboard work until `plan_connect` holds an agent. A `naming` block (status `needed`) gives the exact " +
+    "`title`, `{Name}: PLAN-NNN {short title}`; rename this thread to it (`set_session_title`, or ask for `/rename`), then connect again with that `title`. " +
+    // DX-4608 / DX-5549: a title in the format naming another agent than the held one is refused.
+    "A `title` in that format naming another agent than yours is refused `session_title_not_agent_name` with the title to use.", {
+    plan_id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("The plan's number within your team (the `n` of `PLAN-n`; a plan's `ref` in `50arms_api` `GET /api/plans`). Omit only to sign in (it still takes your team agent)."),
+    title: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+    // DX-4608: stored as sent; a wrong one does not refuse the connect, the reply's `naming` says what to rename it to.
+    'The `naming` block\'s exact `{Name}: PLAN-NNN {short title}`, after renaming this thread. Omit on the first connect.'),
+    assignment_id: z.number().int().positive().optional().describe("The assignment this connect answers, when a person's assignment message names one. Refused `assignment_ended` once it is over: then do nothing more about it."),
+    disconnect: z.boolean().optional().describe("true = leave `plan_id` (your current plan); no `title`."),
+}, 
+// DX-2862 — the connect is also the moment the session's connection record is written for `restart_notice` and the listener reminder: of the
+// dashboard MCP servers a session may have configured, the one that connected the plan is the one whose credential they
+// must resolve (the relay needs none of this: it lives in each server, with that server's own credential).
+async (args) => {
+    // DX-4390 — a leave names the plan it leaves, and needs a key like any other call.
+    if (args.disconnect === true && args.plan_id === undefined) {
+        return haltResult("plan_connect: `disconnect: true` needs `plan_id`, the plan this session is currently on");
+    }
+    // DX-4390 — no key yet: ask for one (or wait for the approval already asked for).
+    const ready = await access.ensureAccess(args.title);
+    if (!ready.signedIn)
+        return accessReply(ready);
+    if (args.plan_id === undefined) {
+        // DX-4523 - signed in (possibly just now): show the tools this key's permissions allow.
+        await syncToolsAfterSignIn();
+        // DX-5549: signing in takes a team agent. The dashboard's answer (the agent and the instruction to use its name, or why there is none) is the reply.
+        const claimed = await claimSessionAgent(client);
+        const claimHalt = access.refusalHalt(claimed);
+        if (claimHalt !== null)
+            return haltResult(claimHalt);
+        if (!claimed.ok)
+            return jsonResult(claimed);
+        agentGate.record(claimed.body);
+        if (agentGate.current() === null)
+            void reportCheckoutDocsRoot();
+        return jsonResult({
+            ...claimed.body,
+            ...(agentGate.current() === null ? { instruction: "This session is signed in. Call `plan_connect` with `plan_id` to connect it to a plan." } : {}),
+        });
+    }
+    // DX-6089: the role text lands in a local file; the reply names it (`role-instruction-file.ts`).
+    const result = spillRoleInstruction(await planConnect(client, { ...args, plan_id: args.plan_id }));
+    // DX-4418 — a person revoked this key: the stop halt, and nothing asks again.
+    const revokedHalt = access.refusalHalt(result);
+    if (revokedHalt !== null)
+        return haltResult(revokedHalt);
+    // DX-4390 — the dashboard no longer accepts the stored key: drop it and ask again in the same call.
+    if (result.status === 401 && access.dropKey(result)) {
+        return accessReply(await access.ensureAccess(args.title), "the dashboard no longer accepted this session's key");
+    }
+    return finishConnect("plan_connect", result, args.disconnect === true);
+});
+// DX-6735: started by each connect that holds an agent, and never awaited by it.
+const reportCheckoutDocsRoot = createCheckoutDocsRootReporter(() => client, process.cwd());
+/**
+ * What `plan_connect` and `card_connect` do with a connect answer once the key is known good (DX-6157 - one path, so a wiring test through either tool covers it), and `50arms_api` with a manual pickup that connected (DX-6556).
+ * DX-5549: the dashboard connects only a session that holds a team agent. With none it answers why (`agent_needed` / `agent_limit_reached`) and binds nothing: that answer is handed to the agent
+ * unchanged and every other dashboard tool stays closed until a later connect finds an agent. The tools are shown and the listener reminder reset BEFORE that block is handed back (DX-4523, DX-3997),
+ * so a session whose key was just approved can run `plan_events_wait` and hear the person's Create. A leave (DX-2985) drops the local connection record; a connect writes it.
+ */
+async function finishConnect(tool, result, disconnect) {
+    await syncToolsAfterSignIn();
+    listenerReminder.invalidate();
+    if (!disconnect) {
+        agentGate.record(result.body);
+        if (agentGate.current() !== null)
+            return jsonResult(result.body);
+        void reportCheckoutDocsRoot();
+    }
+    if (disconnect) {
+        removeSessionConnectionAfterLeave(result, config.session?.id);
+        return jsonResult(result);
+    }
+    const connection = access.connection();
+    if (connection === null)
+        throw new Error(`${tool}: no credential after a successful connect`);
+    return jsonResult({
+        ...result,
+        dashboard: connectedDashboard(),
+        ...recordSessionConnectionAfterConnect(result, {
+            sessionId: config.session?.id,
+            projectKey: projectKeyOf(process.cwd()),
+            dashboardUrl: connection.dashboardUrl,
+            source: connection.source,
+            fingerprint: connection.fingerprint,
+        }),
+    });
+}
+// ---------------- card_connect (DX-5553) ----------------
+strictTool("card_connect", 
+// DX-5553 - the stand-alone counterpart of `plan_connect`: one card on no plan instead of a plan.
+"Hold ONE card that is on no plan instead of a plan: for a one-off, a quick fix or an epic that is not a plan. You then hear that card's and its descendants' events, " +
+    "and no other card's. The reply carries `owedComments` (every person comment on it no agent has answered yet, oldest first: read them first and answer each, ack then reply), `missedEvents` (operator events no session had been told about on it: read them next), `naming` and `agent`/`agentInstruction`. " +
+    "Refused `card_on_plan` when the card or any card above it is on a plan (connect to that plan with `plan_connect`), `card_held` when another live session holds it. " +
+    "A session holding no team agent is first signed in as one, as `plan_connect` does: with none free the answer is `agent_needed` (propose one) or `agent_limit_reached`, and nothing is held. " +
+    "Holding it assigns the card to you, like a manual pickup; a card " +
+    "with children is held as a whole and its children are picked up normally. A session holds a plan or a card, never both: connecting to either lets go of the other. " +
+    "A `naming` block (status `needed`) gives the exact `title`, `{Name}: {CARD-ID} {card title}`; rename this thread to it (`set_session_title`, or ask for `/rename`), then connect " +
+    "again with that `title`. A card later added to a plan moves you off it: you are told on your next plan call.", {
+    card_id: z.string().min(1).describe("The id of the card to hold, as the board shows it."),
+    title: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("The `naming` block's exact `{Name}: {CARD-ID} {card title}`, after renaming this thread. Omit on the first connect."),
+    assignment_id: z.number().int().positive().optional().describe("The assignment this connect answers, when a person's assignment message names one. Refused `assignment_ended` once it is over: then do nothing more about it."),
+    disconnect: z.boolean().optional().describe("true = let go of `card_id` (the card you hold); no `title`."),
+}, async (args) => {
+    const ready = await access.ensureAccess(args.title);
+    if (!ready.signedIn)
+        return accessReply(ready);
+    const result = spillRoleInstruction(await cardConnect(client, args));
+    const revokedHalt = access.refusalHalt(result);
+    if (revokedHalt !== null)
+        return haltResult(revokedHalt);
+    if (result.status === 401 && access.dropKey(result)) {
+        return accessReply(await access.ensureAccess(args.title), "the dashboard no longer accepted this session's key");
+    }
+    return finishConnect("card_connect", result, args.disconnect === true);
+});
+// ---------------- plan_events_wait (DX-4233) ----------------
+strictTool("plan_events_wait", 
+// DX-4882 - `plan_id` is null for a signed-in session on no plan: its stream still carries its account's pacing and resume messages.
+// DX-4233 - for the 50arms plugin's relay loop. DX-4667 - and for a background waiter sub-agent of an orchestrator, which
+// loops on it until events exist and returns them (and the cursor) to the orchestrator it wakes. It answers `events` (each
+// `{cursor, text, urgent, acks}`; empty after `timeout_ms`), the cursor to send being the last delivered event's, or `stopped` with the remedy
+// to tell the session. General-audience text (DX-4550): nothing here names our own setup.
+"Waits for events for this session: the events of the plan it is connected to, and the messages about its usage. For a relay " +
+    "or a background waiter that calls it in a loop and hands every event to the session; call it for nothing else. " +
+    "`plan_id` is the plan the session is on, or null when it is on no plan (then only the usage messages arrive; a different " +
+    "plan than the last call's, or a move to or from null, starts clean). `cursor` is the `cursor` of the last event delivered, as answered (null " +
+    "when none). Answers `{events: [{cursor, text, urgent, acks}]}`, with `events` empty once `timeout_ms` passes, or `{stopped: " +
+    "{reason, detail, fix}}` when the stream ended: tell the session the `fix`. An event stays until a later call's " +
+    "`cursor` passes it. `urgent` is true for an event the session must hear at once (a critical usage limit, a revoked " +
+    "key) and false for every other: deliver an urgent one to the session even while it is working, and any other once its " +
+    "current turn ends. `acks`: events to acknowledge as `text` says, else re-sent. " +
+    "One wait per session: a newer call ends the older. " +
+    "`transcript_path` is the session's transcript file, for its usage and title.", {
+    plan_id: z.number().int().positive().nullable().describe("Number of the plan this session is connected to (the `n` of `PLAN-n`, within your team), or null when it is on no plan."),
+    cursor: z
+        .string()
+        .nullable()
+        .describe("The `cursor` of the last event delivered to the session, exactly as answered, or null when there is none."),
+    timeout_ms: z
+        .number()
+        .int()
+        .min(WAIT_MIN_MS)
+        .max(WAIT_MAX_MS)
+        .describe(`How long to wait for an event, ${WAIT_MIN_MS} to ${WAIT_MAX_MS} ms.`),
+    transcript_path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Absolute path of this session's transcript (.jsonl file)."),
+}, 
+// The relay is bound to the session the server booted for (the id every other tool on this server also sends); a server
+// with none holds no session key, so the surface never shows this tool and the relay would answer `credential_unavailable`.
+async (args, extra) => jsonResult(await servePlanEventsWait(planEventRelay, args, extra.signal)));
+// ---------------- restart_notice (DX-4632) ----------------
+strictTool("restart_notice", 
+// DX-4632 - for the 50arms plugin's session-start hook, not for a model to call. General-audience text (DX-4550).
+"Which plan the session this one replaced was working, and what waits there. For the 50arms plugin's session start: " +
+    "a model never calls it. Works before sign-in. Answers " +
+    "`{notice: text}` (tell the session), `{notice: null}` (nothing to say) or `{stopped: {reason, detail, fix}}`.", RESTART_NOTICE_ARGS, async (args) => jsonResult(await lookupRestartNotice({
+    predecessorId: args.predecessor_id,
+    transcriptPath: args.transcript_path,
+    sessionId: config.session?.id,
+    cwd: process.cwd(),
+    env: process.env,
+    fetch: (input, init) => fetch(input, init),
+})));
+// ---------------- main ----------------
+async function main() {
+    boot();
+    await syncToolsAfterSignIn();
+    stopWhenSessionEnds({
+        server: server.server,
+        stdin: process.stdin,
+        signals: process,
+        exit: (code) => process.exit(code),
+        stop: makeSessionStop(permissionWatch, planEventRelay),
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`platform-mcp running on stdio (dashboard=${config.baseUrl}, board=${config.board ?? "none, each call names its own"})`);
+}
+// Boot the stdio server ONLY when run as the entrypoint (the published bin).
+// Importing this module (the tool-defs generator + its drift test) registers
+// the tools on `server` without reading env or attaching stdin — so the
+// schemas can be introspected without spawning a dispatch. The check is
+// symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
+// spawns, not just a direct `node dist/index.js`.
+//
+// The only subcommand is `subagents-live`, which the 50arms plugin's plan pane runs (DX-4508); it does not boot the MCP
+// server; it reads the declared model prices once at start with the session key (DX-5611). A session's plan events are served in this process by `plan_events_wait` (DX-4233).
+//
+// Any OTHER argument is refused rather than ignored, so a typo cannot
+// silently start an MCP server on stdio where a subcommand was meant to run.
+if (isEntrypointModule(import.meta.url, process.argv[1])) {
+    const [subcommand, ...rest] = process.argv.slice(2);
+    if (MACHINE_DAEMON_SUBCOMMANDS.includes(subcommand ?? "")) {
+        // DX-5902 - install, status or remove the machine daemon on this machine. The daemon itself is the separate bundle dist/machine-daemon.js.
+        runMachineDaemonCommand(subcommand, rest).then((code) => process.exit(code), (err) => {
+            console.error(`[platform-mcp] ${subcommand} fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
+    else if (subcommand === SUBAGENTS_LIVE_SUBCOMMAND) {
+        // DX-4508 — the plugin pane's local live sub-agent feed: stdout is its JSON Lines channel, so a fatal goes to
+        // stderr only and exits 1; a refused path exits 2 from the command itself.
+        runSubagentsLiveCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[platform-mcp] ${SUBAGENTS_LIVE_SUBCOMMAND} fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
+    else if (subcommand !== undefined) {
+        console.error(`[platform-mcp] unknown subcommand "${subcommand}" (the only one is ` +
+            `"${SUBAGENTS_LIVE_SUBCOMMAND}")`);
+        process.exit(2);
+    }
+    else {
+        main().catch((err) => {
+            console.error(`[platform-mcp] fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
+}