@thehammer/danx-dashboard-mcp 0.1.249 → 0.1.250

package/README.md

@@ -30,6 +30,16 @@ A call the dashboard refuses `403 {error: "forbidden", permission}` means the ke
 
 The hint: every dashboard result that is `403 {error: "forbidden", permission}` (and only that) gains one `reminders[]` entry naming the permission, `request_permission`, and saying to raise a problem on the card if blocked (`src/forbidden-hint.ts`, applied once in `guardedCall` in `src/index.ts`).
 
+### Which tools a session sees (DX-4523)
+
+A session is shown only the tools it can call. `src/tool-access.ts` declares, for every tool, what makes it usable, and its one function `toolsFor({permissions, callbacks})` maps what a session holds to the tool names it advertises. `src/tool-surface.ts` applies it with the SDK's `tool.enable()` / `disable()`, so `notifications/tools/list_changed` is sent and Claude Code refetches; nothing else decides visibility, and the danxbot service's budgets (`src/tokens/mcp-surface.ts`) read the same function.
+
+- **Bootstrap set**, for every session and the whole of a signed-out one: `plan_connect`, `request_permission` and the `danxbot_api` trio.
+- **Permission tools** (`attach_file` needs `cards.edit`): shown once the key holds the permission the tool's dashboard route needs.
+- **Callback tools**: shown when the worker injected the tool's per-dispatch URL (`DANXBOT_*_URL`). The six that post to dashboard routes (`danxbot_slack_*`, `link_thread_to_issue`, `slack_recovery_*`) also need the route's permission; the six that post to a worker route (`danxbot_complete`, `quality_gate_complete`, `request_code_review`, `danxbot_set_evaluator_summary`, `save_template_app`, `load_template_app`) authenticate with the dispatch's agent token and need only the URL.
+- **When it is applied.** At boot, as a session with no key; then, if the session holds a key (a dispatch's env credential, or a stored session key), right away from `GET /api/auth/me`; a dispatch retries that read three times and fails the boot rather than start without its tools. After `plan_connect` signs a session in. And again when a person approves a `request_permission` grant: the dashboard ends the key's open `/api/stream` with `event: end {reason: "permissions_changed"}`, this process holds one stream open on the key-self topic `key:self` (`src/permission-watch.ts`; any key may subscribe with no permission, because a dispatch's agent role holds no read-floor key), and after EVERY (re)connect re-reads the key's permissions (a failed read is retried with bounded backoff) and enables what is newly allowed in ONE `list_changed`. It reconnects with backoff after a drop, and stops when stdin closes. A grant that adds no tool, and a repeated read, switch nothing and send no notification, because a changed tool list costs the session its prompt cache.
+- A stream the dashboard refuses (any 4xx) is logged and ends the watch; that session's grants then show their tools at its next `plan_connect`. A permission read the dashboard refuses (401/403, other than the Terms halt) fails a dispatch's boot rather than quietly narrowing its tools.
+
 ## Tool surface (DX-3465 — one generic tool, not one per operation)
 
 All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `mcp.template.json`. There is no per-operation tool any more (no `issue_get`, `issue_create`, `plan_add_note`, …) — three tools cover the whole dashboard API (a fourth, `request_permission`, asks for more access):
@@ -39,7 +49,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `danxbot_api` | `{method, path, query?, body?}` — calls any dashboard route the caller's credential may reach (card/plan CRUD, comments, dependencies, problems/solutions, quality gates, retro, triage, transitions, …). Returns `{ok, status, body}`; `body` carries the route's own response, or its structured error verbatim when `ok:false`. While this session is plan-connected, the dashboard's own reminders for it (today: `plan_list.listener_unattached`, attached by the server to `GET /api/plans` when the event listener is unattached past the startup grace, DX-3997) are relayed into the body's `reminders[]`; the MCP carries no reminder text or state of its own and re-reads at most every 30s. |
 | `danxbot_api_list` | No args. Lists the routes this caller's credential may reach as `{routes: ["METHOD /path"], external: [{route, served_by}]}` (one bare string per route, exactly what `danxbot_api_spec` takes) — call this first when you don't know the route for what you need to do. |
 | `danxbot_api_spec` | `{endpoints}` (comma-joined `METHOD /path` list, required, min 1). Returns the exact OpenAPI contract for those routes — call this when you know the route but not its exact request/response shape. |
-| `attach_file` | `{card_id, path, replaces?, primary?, filename?, content_type?}` — the server reads the LOCAL file at `path` (absolute, `/tmp/a.png` or `C:\x\a.png`) and uploads it, so its bytes never pass through the agent's context. `replaces: <attachment id>` swaps that attachment's file in place (`PUT /api/issues/:id/attachments/:aid`: same id, name and cover flag) instead of adding one; `primary: true` makes it the card's single cover, atomically with the write. Reply: `{issue: <compact row>, attachment_id, url, thumbnail_url, is_primary}`. Opt-in: granted to `slack-agent` and `work` (DX-4386) through `extraTools`. A screenshot of browser-visible work: first `primary: true`, then `replaces` at each milestone. |
+| `attach_file` | `{card_id, path, replaces?, primary?, filename?, content_type?}` — the server reads the LOCAL file at `path` (absolute, `/tmp/a.png` or `C:\x\a.png`) and uploads it, so its bytes never pass through the agent's context. `replaces: <attachment id>` swaps that attachment's file in place (`PUT /api/issues/:id/attachments/:aid`: same id, name and cover flag) instead of adding one; `primary: true` makes it the card's single cover, atomically with the write. Reply: `{issue: <compact row>, attachment_id, url, thumbnail_url, is_primary}`. Shown to a key holding `cards.edit` (DX-4523); a dispatch profile still receives it only when its catalog selection names it (`slack-agent` and `work`, DX-4386, through `extraTools`). A screenshot of browser-visible work: first `primary: true`, then `replaces` at each milestone. |
 | `request_permission` | `{permissions, reason}` — asks a person to grant this key ONE MORE permission (see "Asking for one more permission" above). Answers at once with the approval URL and confirm code; the grant is picked up in the background. |
 
 There is no dedicated `resource_fields` tool (removed DX-3465 — it was a thin wrapper `danxbot_api` already reaches with no agent-specific behavior earning it its own tool). What an opt-in field TREE may name for one resource (`{resource, description, always, hashes, fields, relations}`) is `danxbot_api({method:"GET", path:"/api/resources/<resource>/fields"})` — install-global, no `board`; `resource: "issue"` is the root, and a relation's own `resource` in the response is what to call this again with, one level deeper.

package/dist/bounded-retry.js

@@ -0,0 +1,25 @@
+/**
+ * DX-4523 - the one bounded retry the tool-access sync uses, at boot (`index.ts`) and on every permission-stream connect
+ * (`permission-watch.ts`): a few attempts with a growing wait, insurance against a dashboard blip, never the primary mechanism.
+ */
+export const SYNC_ATTEMPTS = 3;
+export const SYNC_RETRY_BACKOFF_MS = 500;
+/**
+ * Run `run` up to `attempts` times, waiting `backoffMs * attempt` between tries. The last failure is rethrown for the caller to
+ * decide how loud it is. `shouldStop` ends the loop quietly (the watch was stopped).
+ */
+export async function retryBounded(run, opts) {
+    const backoffMs = opts.backoffMs ?? SYNC_RETRY_BACKOFF_MS;
+    for (let attempt = 1;; attempt++) {
+        if (opts.shouldStop?.())
+            return undefined;
+        try {
+            return await run();
+        }
+        catch (err) {
+            if (attempt >= opts.attempts)
+                throw err;
+            await opts.sleep(backoffMs * attempt);
+        }
+    }
+}

package/dist/index.js

@@ -108,7 +108,11 @@ 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, applyLifecycleVisibility, readLifecycleUrlsFromEnv, } from "./lifecycle.js";
+import { registerLifecycleTools, presentCallbacks, readLifecycleUrlsFromEnv, } from "./lifecycle.js";
+import { TOOL_ACCESS } from "./tool-access.js";
+import { ToolAccessSync, ToolSurface } from "./tool-surface.js";
+import { PermissionWatch } from "./permission-watch.js";
+import { SYNC_ATTEMPTS, retryBounded } from "./bounded-retry.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
     if (typeof v !== "string" || v === "") {
@@ -160,6 +164,9 @@ let listenerReminder;
 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;
 /**
  * Compose the dispatch's qualified board id (`<repo>:<slug>`) from the two env
  * halves the worker injects and build the HTTP client. DANXBOT_BOARD_NAME
@@ -207,15 +214,86 @@ function boot() {
         now: Date.now,
         logLine: (line) => console.error(line),
     });
-    // DX-3465 (PLN-11 R-25) — the lifecycle tool set's per-tool visibility is
-    // per-dispatch, not static: a tool whose callback URL wasn't injected for
-    // THIS dispatch must not even be advertised (mirrors the old standalone
-    // server's `buildActiveTools`). Applied here (inside `boot()`, before
-    // `server.connect()`) so the DX-1606 tool-defs generator — which imports
-    // this module WITHOUT calling `boot()` — still sees every lifecycle tool
-    // registered and enabled for token-cost accounting.
-    applyLifecycleVisibility(lifecycleTools, readLifecycleUrlsFromEnv());
+    // 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, presentCallbacks(readLifecycleUrlsFromEnv()), () => server.sendToolListChanged());
+    surface.apply(new Set());
+    toolAccessSync = new ToolAccessSync({
+        surface,
+        readPermissions: readHeldPermissions,
+        log: (line) => console.error(line),
+    });
+    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/me`). 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" };
+    const guarded = await access.guard(() => client.request({ method: "GET", basePath: "", path: "/api/auth/me" }));
+    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/me 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/me 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(`[danx-dashboard-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();
+}
+/**
+ * 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 the
  * `bridge` subcommand also uses, so a session's tools and its event stream can never sign in as
@@ -356,6 +434,8 @@ function jsonResult(value) {
 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,
@@ -380,15 +460,20 @@ function boundedJsonResult(result) {
 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);
-    return server.registerTool(name, { description, inputSchema: z.object(shape).strict() }, cb);
+    // 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;
 }
 // ---------------- lifecycle tool set (DX-3465 / PLN-11 R-25) ----------------
 // Merged from `src/mcp/danxbot-server.ts` — see `lifecycle.ts` for the full
 // per-tool doc comments and the DX-3394 problem 1682 cleanup this merge
 // folded in. `danxbot_complete` registers unconditionally-visible; the rest
-// register here and are `.enable()`/`.disable()`d per-dispatch inside
-// `boot()` above, based on which callback URL env vars are present.
-const lifecycleTools = registerLifecycleTools(strictTool);
+// register here; `toolsFor` (`tool-access.ts`) decides which a session sees.
+registerLifecycleTools(strictTool);
 // Optional per-call board override shared by every tool. Omitted → the
 // dispatch's env-derived board (`<repo>:<slug>`) is used; provided → that
 // board is targeted instead (the dashboard owns board→repo and 404s an
@@ -588,6 +673,8 @@ async (args) => {
     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();
         return jsonResult({
             state: "signed_in",
             instruction: "This session is signed in. Call `plan_connect` with `plan_id` to connect it to a plan.",
@@ -602,6 +689,9 @@ async (args) => {
     if (result.status === 401 && access.dropKey()) {
         return accessReply(await access.ensureAccess(args.title), "the dashboard no longer accepted this session's key");
     }
+    // DX-4523 - the key just worked: show the tools its permissions allow. After the refusals above, so a revoked or lapsed
+    // key is found by the connect itself and answered as before.
+    await syncToolsAfterSignIn();
     // DX-3997 — a (re)connect restarts the bridge; the next `danxbot_api` must re-read health.
     listenerReminder.invalidate();
     // DX-2985 — a leave drops the local connection record (the bridge exits on `not_connected`; a later connect writes a fresh one).
@@ -626,6 +716,11 @@ async (args) => {
 // ---------------- main ----------------
 async function main() {
     boot();
+    await syncToolsAfterSignIn();
+    // DX-4523 - the open permission stream would keep the process alive after the client goes away. The SDK's stdio transport
+    // does not watch stdin for its end (only a transport `close()` reaches `onclose`), so the end of stdin stops the watch too.
+    server.server.onclose = () => permissionWatch.stop();
+    process.stdin.once("end", () => permissionWatch.stop());
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`danx-dashboard-mcp running on stdio (dashboard=${config.baseUrl}, board=${config.board})`);

package/dist/lifecycle.js

@@ -11,12 +11,9 @@
  *
  * Registered UNCONDITIONALLY at module load (so the DX-1606 tool-defs
  * generator — which never calls `boot()` — still introspects every one of
- * them for token-cost accounting), then individually `.disable()`d inside
- * `boot()` (`index.ts`) based on which per-dispatch callback URL env vars
- * are actually present — the same visibility contract
- * `buildActiveTools`/`callTool` used to enforce in the old standalone
- * server: a tool whose URL wasn't injected for this dispatch is not just
- * inert, it is invisible to `tools/list`.
+ * them for token-cost accounting). Which of them a session SEES is decided by
+ * `toolsFor` (`tool-access.ts`) from the key's permissions and the callback
+ * URLs present (`presentCallbacks`), applied by `tool-surface.ts` (DX-4523).
  *
  * DX-3394 problem 1682 cleanup folded into this merge:
  *  - `danxbot_restart_worker` — already removed on `main` before this card
@@ -39,6 +36,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { basename, isAbsolute } from "node:path";
 import { z } from "zod";
+import { CALLBACK_ENV } from "./tool-access.js";
 /**
  * The five canonical agent-visible `danxbot_complete` statuses. DX-3394
  * problem 1682 / Core Principle 1 — the pre-DX-770 deprecated aliases
@@ -64,26 +62,19 @@ export const QUALITY_GATE_SKIP_REASON_MIN_CHARS = 20;
 export function hasAdequateBlockSummary(summary) {
     return typeof summary === "string" && summary.trim().length >= ADEQUATE_SUMMARY_MIN_CHARS;
 }
-/** Read the lifecycle callback URLs straight from `process.env`. */
+/** The callbacks whose URL is present: what `toolsFor` takes as this dispatch's callbacks (`tool-access.ts`). */
+export function presentCallbacks(urls) {
+    return new Set(Object.keys(urls).filter((name) => urls[name] !== undefined));
+}
+/** Read the lifecycle callback URLs straight from `process.env`; an empty value reads as absent. */
 export function readLifecycleUrlsFromEnv() {
-    const opt = (name) => {
-        const v = process.env[name];
-        return typeof v === "string" && v !== "" ? v : undefined;
-    };
-    return {
-        stop: opt("DANXBOT_STOP_URL"),
-        slackReply: opt("DANXBOT_SLACK_REPLY_URL"),
-        slackUpdate: opt("DANXBOT_SLACK_UPDATE_URL"),
-        linkThreadToIssue: opt("DANXBOT_LINK_THREAD_TO_ISSUE_URL"),
-        slackRecoveryList: opt("DANXBOT_SLACK_RECOVERY_LIST_URL"),
-        slackRecoveryMessage: opt("DANXBOT_SLACK_RECOVERY_MESSAGE_URL"),
-        slackRecoveryCreateOrLink: opt("DANXBOT_SLACK_RECOVERY_CREATE_OR_LINK_URL"),
-        qualityGate: opt("DANXBOT_QUALITY_GATE_URL"),
-        requestCodeReview: opt("DANXBOT_REQUEST_CODE_REVIEW_URL"),
-        evaluatorSummary: opt("DANXBOT_EVALUATOR_SUMMARY_URL"),
-        saveTemplateApp: opt("DANXBOT_TEMPLATE_APP_SAVE_URL"),
-        loadTemplateApp: opt("DANXBOT_TEMPLATE_APP_LOAD_URL"),
-    };
+    const urls = {};
+    for (const name of Object.keys(CALLBACK_ENV)) {
+        const v = process.env[CALLBACK_ENV[name]];
+        if (typeof v === "string" && v !== "")
+            urls[name] = v;
+    }
+    return urls;
 }
 async function postJson(url, body, bearer) {
     return fetch(url, {
@@ -162,10 +153,10 @@ export function registerLifecycleTools(strictTool) {
     // it", but an OPERATOR session is not a dispatch: it has no
     // DANXBOT_STOP_URL, so `danxbot_complete` was always advertised there and
     // every call threw. It is now gated on the stop URL exactly like every
-    // other lifecycle tool below (`applyLifecycleVisibility`) — a real
+    // other lifecycle tool below (`toolsFor`, `tool-access.ts`) — a real
     // dispatch always has the URL, so nothing is lost there; an operator
     // session simply never sees a tool it could never successfully call.
-    const danxbotComplete = strictTool("danxbot_complete", "Finalize the current dispatch. Releases the worker's per-dispatch scope and ends the dispatch row. " +
+    strictTool("danxbot_complete", "Finalize the current dispatch. Releases the worker's per-dispatch scope and ends the dispatch row. " +
         "Does NOT move any card — if you're working an issue-bound dispatch and want the card to move " +
         "(Done / Blocked / Cancelled / etc.), transition the card FIRST through danxbot_api " +
         "({method:'POST', path:'/api/issues/:id/transition', body:{action:...}}), then call this tool. " +
@@ -213,7 +204,7 @@ export function registerLifecycleTools(strictTool) {
         };
     });
     // ---------------- danxbot_slack_reply ----------------
-    const slackReply = strictTool("danxbot_slack_reply", 
+    strictTool("danxbot_slack_reply", 
     // DX-4253 — no ordering against another tool here: the Slack persona (`src/agent/persona.ts`) and the
     // `slack-agent` profile own the order (reply, link, attach, complete).
     "Post the final user-facing reply to the originating Slack thread, once per dispatch. Files in `files[]` " +
@@ -246,7 +237,7 @@ export function registerLifecycleTools(strictTool) {
         };
     });
     // ---------------- danxbot_slack_post_update ----------------
-    const slackPostUpdate = strictTool("danxbot_slack_post_update", "Post an intermediate progress update to the originating Slack thread. Use SPARINGLY — only for " +
+    strictTool("danxbot_slack_post_update", "Post an intermediate progress update to the originating Slack thread. Use SPARINGLY — only for " +
         "meaningful status the user cares about. Do NOT post for every file read or trivial step.", { text: z.string().describe("The intermediate status update text.") }, async (args) => {
         const url = readLifecycleUrlsFromEnv().slackUpdate;
         if (!url)
@@ -257,7 +248,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: "Update posted to Slack thread" }] };
     });
     // ---------------- link_thread_to_issue ----------------
-    const linkThreadToIssue = strictTool("link_thread_to_issue", "Upgrade THIS Slack thread into a tracked card: bind the thread to ONE issue (immutable 1:1) and " +
+    strictTool("link_thread_to_issue", "Upgrade THIS Slack thread into a tracked card: bind the thread to ONE issue (immutable 1:1) and " +
         "register the Slack mirror so future card updates re-render the thread's card-view message. Thread " +
         "scope is IMPLICIT (channel + thread_ts come from the dispatch) — pass only the issue id. Call this " +
         "AFTER posting your substantive answer with danxbot_slack_reply (that reply becomes the card-view " +
@@ -269,7 +260,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ---------------- slack_recovery_list ----------------
-    const slackRecoveryList = strictTool("slack_recovery_list", "Read-only. Returns the Slack thread's full stored message history plus failures[], the recorded " +
+    strictTool("slack_recovery_list", "Read-only. Returns the Slack thread's full stored message history plus failures[], the recorded " +
         "router failures projected out of those same messages, so you can reason about what happened before " +
         "mutating anything. Only available on a slack-recovery dispatch.", {}, async () => {
         const url = readLifecycleUrlsFromEnv().slackRecoveryList;
@@ -279,7 +270,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ---------------- slack_recovery_message (merged replace+purge, DX-3394 problem 1682) ----------------
-    const slackRecoveryMessage = strictTool("slack_recovery_message", "Replace or delete ONE message you posted in this thread. `action: 'replace'` (`chat.update`) rewrites " +
+    strictTool("slack_recovery_message", "Replace or delete ONE message you posted in this thread. `action: 'replace'` (`chat.update`) rewrites " +
         "the message text — the replaced message becomes this thread's card-view anchor ('message #1'): a " +
         "later link_thread_to_issue registers THIS ts, and danxbot re-renders the real card view into this " +
         "exact slot, so write a short human line, never a hand-written card view, in `text`. `action: 'purge'` " +
@@ -309,7 +300,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ---------------- slack_recovery_create_or_link ----------------
-    const slackRecoveryCreateOrLink = strictTool("slack_recovery_create_or_link", "The ONLY way to get a card id for this thread on a slack-recovery dispatch (danxbot_api's card-create " +
+    strictTool("slack_recovery_create_or_link", "The ONLY way to get a card id for this thread on a slack-recovery dispatch (danxbot_api's card-create " +
         "route, POST /api/issues, is not available here). Resolves SERVER-SIDE whether the thread already " +
         "resolves to a card before creating " +
         "anything: a hit returns that existing card's id (created:false) and creates NOTHING; a miss creates a " +
@@ -355,7 +346,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ---------------- quality_gate_complete (absorbs quality_gate_skip, DX-3394 problem 1682) ----------------
-    const qualityGateComplete = strictTool("quality_gate_complete", 
+    strictTool("quality_gate_complete", 
     // DX-3741 — every gate runs as its own gate-reviewer dispatch, the only one that sees this tool. DX-4318 —
     // what a status does, per phase; how to review (read-only, no transition) is the gate-reviewer profile's
     // (`required-profiles.yaml`). The "3-pass cap" mirrors CODE_GATE_MAX_REVIEW_PASSES
@@ -403,7 +394,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ---------------- request_code_review (DX-3741) ----------------
-    const requestCodeReview = strictTool("request_code_review", "TERMINAL for this dispatch — call it when your diff is done and its own tests are green, instead of " +
+    strictTool("request_code_review", "TERMINAL for this dispatch — call it when your diff is done and its own tests are green, instead of " +
         "danxbot_complete. Pushes your branch (card/<id> to origin/card/<id>), then dispatches every code " +
         "gate this card carries as its OWN independent gate-reviewer dispatch (you never sign or review your " +
         "own diff — DX-3741). Ends this dispatch 'completed' and releases the card to ToDo; when the card is " +
@@ -418,7 +409,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ---------------- danxbot_set_evaluator_summary ----------------
-    const evaluatorSummary = strictTool("danxbot_set_evaluator_summary", "Write the root-cause summary for a 3-strike broken agent. ONLY the system-evaluator dispatch sees this " +
+    strictTool("danxbot_set_evaluator_summary", "Write the root-cause summary for a 3-strike broken agent. ONLY the system-evaluator dispatch sees this " +
         "tool. Call exactly once at the END of the dispatch, immediately before danxbot_complete. A dispatch " +
         "that exits without calling this tool is treated as evaluator failure.", {
         reason: z
@@ -437,7 +428,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ---------------- save_template_app ----------------
-    const saveTemplateApp = strictTool("save_template_app", "Build and ship ONE template app, keyed by template id. Walks <cwd>/templates/<template_id>/source/, " +
+    strictTool("save_template_app", "Build and ship ONE template app, keyed by template id. Walks <cwd>/templates/<template_id>/source/, " +
         "builds, packs the bundle, then on success fires an async callback to the repo's configured save_url. " +
         "Returns the synchronous build verdict. Call once per app after its edits are complete.", {
         template_id: z
@@ -451,7 +442,7 @@ export function registerLifecycleTools(strictTool) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ---------------- load_template_app ----------------
-    const loadTemplateApp = strictTool("load_template_app", "Set up ONE template app on demand and bring its live HMR preview up. On a FRESH dispatch this WHOLESALE-" +
+    strictTool("load_template_app", "Set up ONE template app on demand and bring its live HMR preview up. On a FRESH dispatch this WHOLESALE-" +
         "RESETS <cwd>/templates/<template_id>/source/ (pulling the consumer's source or scaffolding a default) " +
         "— call this BEFORE you start editing, never after. On a RESUMED dispatch it touches nothing. Returns " +
         "{template_id, hmr_url, source_dir} — source_dir is the ONLY path to edit; the build reads it directly.", {
@@ -465,47 +456,4 @@ export function registerLifecycleTools(strictTool) {
         const result = await postWorkerRoute(url, { template_id: args.template_id }, "load_template_app", agentBearer());
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
-    return {
-        danxbotComplete,
-        slackReply,
-        slackPostUpdate,
-        linkThreadToIssue,
-        slackRecoveryList,
-        slackRecoveryMessage,
-        slackRecoveryCreateOrLink,
-        qualityGateComplete,
-        requestCodeReview,
-        evaluatorSummary,
-        saveTemplateApp,
-        loadTemplateApp,
-    };
-}
-/**
- * Disable every conditionally-visible lifecycle tool whose URL is absent
- * from `urls` — the same advertise-filter contract `buildActiveTools` used
- * to enforce in the old standalone server. `danxbot_complete` (DX-3465,
- * code-quality gate finding, at 275f82c0d) is gated on `urls.stop` the same
- * way — a real dispatch always carries `DANXBOT_STOP_URL`, so it stays
- * visible there; an operator session (no stop URL) never advertises a tool
- * it could never successfully call.
- */
-export function applyLifecycleVisibility(tools, urls) {
-    const setVisible = (tool, visible) => {
-        if (visible)
-            tool.enable();
-        else
-            tool.disable();
-    };
-    setVisible(tools.danxbotComplete, !!urls.stop);
-    setVisible(tools.slackReply, !!urls.slackReply);
-    setVisible(tools.slackPostUpdate, !!urls.slackUpdate);
-    setVisible(tools.linkThreadToIssue, !!urls.linkThreadToIssue);
-    setVisible(tools.slackRecoveryList, !!urls.slackRecoveryList);
-    setVisible(tools.slackRecoveryMessage, !!urls.slackRecoveryMessage);
-    setVisible(tools.slackRecoveryCreateOrLink, !!urls.slackRecoveryCreateOrLink);
-    setVisible(tools.qualityGateComplete, !!urls.qualityGate);
-    setVisible(tools.requestCodeReview, !!urls.requestCodeReview);
-    setVisible(tools.evaluatorSummary, !!urls.evaluatorSummary);
-    setVisible(tools.saveTemplateApp, !!urls.saveTemplateApp);
-    setVisible(tools.loadTemplateApp, !!urls.loadTemplateApp);
 }

package/dist/permission-watch.js

@@ -0,0 +1,143 @@
+/**
+ * DX-4523 - how this process learns that its key's permissions changed while it runs: the dashboard's live stream.
+ *
+ * `/api/stream` ends every open stream of a key with `event: end {reason: "permissions_changed"}` the moment a person approves a
+ * grant for it, revokes one, or revokes the key (`closeSessionStreams`, `src/dashboard/stream-routes.ts`). This watcher holds one
+ * stream open on the key-self topic `key:self` (`src/dashboard/sse-topic-policy.ts`), which any key may subscribe to with no
+ * permission: a dispatch's agent role holds none of the team read-floor keys, yet is exactly the key that is granted one mid-session.
+ *
+ * Reconnect FIRST, then re-read the permissions (`sync`), after EVERY (re)connect, so a change that landed while the stream was down
+ * is applied and a change after the connect ends the stream. A failed sync is retried with bounded backoff, then logged: the
+ * stream stays up and the next connect syncs again. No polling: the only timers are the reconnect backoff after a drop and the sync
+ * retry. The key is read on every connect, so a replaced key is the one used.
+ *
+ * A refusal (a 4xx other than 408 and 429, which are retried like a drop) ends the watch: a 401 means the key is gone (the next dashboard call halts the session as usual) and a 403
+ * means the dashboard predates the topic or refuses this principal. A 5xx or a dropped connection is retried with backoff, which
+ * starts over once a connection proved healthy (stayed open a while, or ended by a permission change).
+ */
+import { SYNC_ATTEMPTS, retryBounded } from "./bounded-retry.js";
+import { SseParser } from "./listen.js";
+const STREAM_PATH = "/api/stream?topics=key:self";
+const PERMISSIONS_CHANGED = "permissions_changed";
+export const WATCH_INITIAL_BACKOFF_MS = 1_000;
+export const WATCH_MAX_BACKOFF_MS = 30_000;
+/** A connection that stayed open this long was healthy, so the next drop starts the backoff over. */
+export const WATCH_HEALTHY_CONNECTION_MS = 20_000;
+/** A 4xx that means "try again later", not "no": the stream is retried with backoff like a drop. */
+const RETRYABLE_REFUSALS = new Set([408, 429]);
+const defaultSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms).unref();
+});
+export class PermissionWatch {
+    deps;
+    running = false;
+    stopRequested = false;
+    controller = null;
+    fetchImpl;
+    sleep;
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.fetchImpl = deps.fetch ?? fetch;
+        this.sleep = deps.sleep ?? defaultSleep;
+        this.now = deps.now ?? Date.now;
+    }
+    /** Start watching. A watch already running is left alone, so every sign-in may call this. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.stopRequested = false;
+        void this.run().finally(() => {
+            this.running = false;
+        });
+    }
+    /** Stop watching and close the open stream, so the process can exit. */
+    stop() {
+        this.stopRequested = true;
+        this.controller?.abort();
+    }
+    async run() {
+        let attempt = 0;
+        while (!this.stopRequested) {
+            const token = this.deps.token();
+            if (token === "")
+                return;
+            const outcome = await this.connectOnce(token);
+            if (outcome.kind === "refused")
+                return;
+            if (outcome.kind === "changed" || outcome.healthy)
+                attempt = 0;
+            // A permission change reconnects at once; a drop waits out the backoff first.
+            if (outcome.kind === "dropped" && !this.stopRequested) {
+                await this.sleep(Math.min(WATCH_MAX_BACKOFF_MS, WATCH_INITIAL_BACKOFF_MS * 2 ** attempt));
+                attempt += 1;
+            }
+        }
+    }
+    async connectOnce(token) {
+        const controller = new AbortController();
+        this.controller = controller;
+        const openedAt = this.now();
+        let opened = false;
+        const healthy = () => opened && this.now() - openedAt >= WATCH_HEALTHY_CONNECTION_MS;
+        try {
+            const response = await this.fetchImpl(`${this.deps.dashboardUrl.replace(/\/+$/, "")}${STREAM_PATH}`, {
+                headers: { Authorization: `Bearer ${token}`, Accept: "text/event-stream" },
+                signal: controller.signal,
+            });
+            if (response.status >= 400 && response.status < 500 && !RETRYABLE_REFUSALS.has(response.status)) {
+                this.deps.log?.(`[danx-dashboard-mcp] the dashboard refused the permission stream (HTTP ${response.status}): a permission granted ` +
+                    `mid-session shows its tools at the next plan_connect instead`);
+                await response.body?.cancel();
+                return { kind: "refused" };
+            }
+            if (!response.ok || response.body === null) {
+                await response.body?.cancel();
+                return { kind: "dropped", healthy: false };
+            }
+            opened = true;
+            await this.syncWithRetry();
+            const parser = new SseParser();
+            const decoder = new TextDecoder();
+            for await (const chunk of response.body) {
+                for (const message of parser.push(decoder.decode(chunk, { stream: true }))) {
+                    if (message.event === "end" && endReason(message.data) === PERMISSIONS_CHANGED)
+                        return { kind: "changed" };
+                }
+            }
+            return { kind: "dropped", healthy: healthy() };
+        }
+        catch (err) {
+            if (!this.stopRequested)
+                this.deps.log?.(`[danx-dashboard-mcp] permission stream dropped: ${err.message}`);
+            return { kind: "dropped", healthy: healthy() };
+        }
+        finally {
+            controller.abort();
+            if (this.controller === controller)
+                this.controller = null;
+        }
+    }
+    /** One sync, retried with bounded backoff; a sync that keeps failing is logged and the stream stays up. */
+    async syncWithRetry() {
+        try {
+            await retryBounded(() => this.deps.sync(), {
+                attempts: SYNC_ATTEMPTS,
+                sleep: this.sleep,
+                shouldStop: () => this.stopRequested,
+            });
+        }
+        catch (err) {
+            this.deps.log?.(`[danx-dashboard-mcp] tool list refresh failed after ${SYNC_ATTEMPTS} attempts, tools stay as they are until the next connect: ${err.message}`);
+        }
+    }
+}
+function endReason(data) {
+    try {
+        return JSON.parse(data).reason;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/session-access.js

@@ -89,6 +89,10 @@ export class SessionAccess {
     isSignedIn() {
         return this.credential !== null && this.revoked === null;
     }
+    /** DX-4523: the key this session holds now, or "" when it holds none (the permission stream opens with it). */
+    currentToken() {
+        return this.credential === null || this.revoked !== null ? "" : this.credential.token;
+    }
     /** DX-4418: the stop halt once a person revoked the key, else null. */
     revokedHalt() {
         return this.revoked === null ? null : keyRevokedHalt(this.revoked.revocation, this.revoked.dispatched);

package/dist/tool-access.js

@@ -0,0 +1,87 @@
+/**
+ * DX-4523 (parent DX-4522) - which MCP tool a session is shown, decided in ONE place.
+ *
+ * A session sees a tool only when it can call it. Every tool is declared here with what makes it callable, and
+ * `toolsFor` is the one function that turns what a session holds into the tool names it advertises. The server
+ * (`tool-surface.ts`) applies it, and the danxbot service's budgets (`src/tokens/mcp-surface.ts`) measure it, so no
+ * second list of "which session gets which tool" exists anywhere.
+ *
+ * Three kinds of tool, by what makes them usable:
+ *
+ *   - bootstrap   `{permission: null, callback: null}` - what a session needs BEFORE it holds a key, or to ask for more:
+ *                 `plan_connect` (sign in, bind to a plan), `request_permission`, and the `danxbot_api` trio.
+ *   - permission  `{permission}` - the dashboard route the tool calls needs this permission, so a key without it can
+ *                 never succeed. Shown once the key holds it, which includes a grant a person approves mid-session.
+ *   - callback    `{callback}` - the tool posts to a per-dispatch URL the worker injected (`lifecycle.ts`). The worker
+ *                 authenticates it with the dispatch's own agent token, so no dashboard permission is involved: the tool
+ *                 is usable exactly when its URL exists. A tool whose route is a dashboard route also names its
+ *                 `permission` (both must hold).
+ *
+ * This module is pure data and one function, with no imports, because the danxbot service imports it directly and
+ * cannot take this package's MCP-SDK or zod dependencies.
+ */
+/**
+ * The environment variable a worker sets to inject each callback's URL. `lifecycle.ts` reads them, and the worker's overlay
+ * (`src/dispatch/dispatch-callbacks.ts`) writes them, so the name of a callback exists once.
+ */
+export const CALLBACK_ENV = {
+    stop: "DANXBOT_STOP_URL",
+    slackReply: "DANXBOT_SLACK_REPLY_URL",
+    slackUpdate: "DANXBOT_SLACK_UPDATE_URL",
+    linkThreadToIssue: "DANXBOT_LINK_THREAD_TO_ISSUE_URL",
+    slackRecoveryList: "DANXBOT_SLACK_RECOVERY_LIST_URL",
+    slackRecoveryMessage: "DANXBOT_SLACK_RECOVERY_MESSAGE_URL",
+    slackRecoveryCreateOrLink: "DANXBOT_SLACK_RECOVERY_CREATE_OR_LINK_URL",
+    qualityGate: "DANXBOT_QUALITY_GATE_URL",
+    requestCodeReview: "DANXBOT_REQUEST_CODE_REVIEW_URL",
+    evaluatorSummary: "DANXBOT_EVALUATOR_SUMMARY_URL",
+    saveTemplateApp: "DANXBOT_TEMPLATE_APP_SAVE_URL",
+    loadTemplateApp: "DANXBOT_TEMPLATE_APP_LOAD_URL",
+};
+const BOOTSTRAP = { permission: null, callback: null };
+const needs = (permission) => ({ permission, callback: null });
+const postsTo = (callback) => ({ permission: null, callback });
+const needsAndPostsTo = (permission, callback) => ({ permission, callback });
+/**
+ * Every tool this server registers, with what makes it usable. `index.ts` refuses to register a tool that is not
+ * here, and `tool-access.test.ts` fails when an entry names no registered tool.
+ */
+export const TOOL_ACCESS = {
+    plan_connect: BOOTSTRAP,
+    request_permission: BOOTSTRAP,
+    danxbot_api: BOOTSTRAP,
+    danxbot_api_list: BOOTSTRAP,
+    danxbot_api_spec: BOOTSTRAP,
+    // `POST /api/issues/:id/attachments`
+    attach_file: needs("cards.edit"),
+    // The dispatch's own terminal and sign-off calls: worker routes, authenticated by the dispatch's agent token.
+    danxbot_complete: postsTo("stop"),
+    quality_gate_complete: postsTo("qualityGate"),
+    request_code_review: postsTo("requestCodeReview"),
+    danxbot_set_evaluator_summary: postsTo("evaluatorSummary"),
+    save_template_app: postsTo("saveTemplateApp"),
+    load_template_app: postsTo("loadTemplateApp"),
+    // Dashboard callback routes; each route's own policy names the permission (`route-policies/index.ts`).
+    danxbot_slack_reply: needsAndPostsTo("slack.threads.post", "slackReply"),
+    danxbot_slack_post_update: needsAndPostsTo("slack.threads.post", "slackUpdate"),
+    link_thread_to_issue: needsAndPostsTo("cards.edit", "linkThreadToIssue"),
+    slack_recovery_list: needsAndPostsTo("slack.recovery.manage", "slackRecoveryList"),
+    slack_recovery_message: needsAndPostsTo("slack.recovery.manage", "slackRecoveryMessage"),
+    slack_recovery_create_or_link: needsAndPostsTo("slack.recovery.manage", "slackRecoveryCreateOrLink"),
+};
+/** True when a session holding `grant` can call the tool declared by `access`. */
+export function isUsable(access, grant) {
+    if (access.permission !== null && !grant.permissions.has(access.permission))
+        return false;
+    if (access.callback !== null && !grant.callbacks.has(access.callback))
+        return false;
+    return true;
+}
+/** The ONE mapping from what a session holds to the tool names it advertises, sorted. */
+export function toolsFor(grant) {
+    return Object.keys(TOOL_ACCESS).filter((name) => isUsable(TOOL_ACCESS[name], grant)).sort();
+}
+/** The bootstrap set: usable with no key and no callback. */
+export function bootstrapTools() {
+    return toolsFor({ permissions: new Set(), callbacks: new Set() });
+}

package/dist/tool-surface.js

@@ -0,0 +1,61 @@
+/**
+ * DX-4523 - applies `toolsFor` (`tool-access.ts`) to the tools this server registered, and keeps it applied as what the
+ * session holds changes: at boot, when sign-in completes, and when a person approves a `request_permission` grant.
+ *
+ * A changed tool list makes Claude Code refetch it (`notifications/tools/list_changed`) and invalidates the prompt cache, so the
+ * surface switches a tool ONLY when its visibility really changes and announces the change ONCE per apply: a grant that adds no
+ * tool, or a repeated sync, sends nothing. The SDK's own `enable()` / `disable()` each send a notification, so the surface sets
+ * `RegisteredTool.enabled` (a plain field the SDK's list handler reads) and calls `onChanged` once instead.
+ */
+import { toolsFor } from "./tool-access.js";
+export class ToolSurface {
+    tools;
+    callbacks;
+    onChanged;
+    constructor(tools, callbacks, 
+    /** Announces that the tool list changed: the server's `sendToolListChanged` (a no-op until a client is connected). */
+    onChanged) {
+        this.tools = tools;
+        this.callbacks = callbacks;
+        this.onChanged = onChanged;
+    }
+    /** Show exactly the tools `permissions` and this dispatch's callbacks allow. Returns the names whose visibility changed. */
+    apply(permissions) {
+        const wanted = new Set(toolsFor({ permissions, callbacks: this.callbacks }));
+        const changed = [];
+        for (const [name, tool] of this.tools) {
+            const want = wanted.has(name);
+            if (tool.enabled === want)
+                continue;
+            tool.enabled = want;
+            changed.push(name);
+        }
+        if (changed.length > 0)
+            this.onChanged();
+        return changed.sort();
+    }
+    /** The tool names currently shown. */
+    advertised() {
+        return [...this.tools].filter(([, tool]) => tool.enabled).map(([name]) => name).sort();
+    }
+}
+/** Re-reads the key's permissions and applies them. Calls run one at a time, so two triggers never interleave. */
+export class ToolAccessSync {
+    deps;
+    queue = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Resolves with the names whose visibility changed. A failed read rejects: the caller decides how loud that is. */
+    sync() {
+        const run = this.queue.then(async () => {
+            const permissions = (await this.deps.readPermissions()) ?? new Set();
+            const changed = this.deps.surface.apply(permissions);
+            if (changed.length > 0)
+                this.deps.log?.(`[danx-dashboard-mcp] tool list changed: ${changed.join(", ")}`);
+            return changed;
+        });
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.249",
+  "version": "0.1.250",
   "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, danxbot_complete, and other per-dispatch lifecycle callbacks) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",