@thehammer/danx-dashboard-mcp 0.1.223 → 0.1.224

package/README.md

@@ -9,12 +9,20 @@ Stdio MCP server fronting danxbot's dashboard HTTP API. Since DX-3465 it exposes
 | Var | Purpose |
 |---|---|
 | `DANXBOT_DASHBOARD_URL` | Dashboard base, e.g. `http://danxbot-dashboard:5555` (inside compose) or `http://localhost:5555` (host) |
-| `DANXBOT_DASHBOARD_TOKEN_FILE` **or** `DANX_DASHBOARD_CREDENTIAL` | The credential, declared exactly one of two ways (DX-2862, `src/credential.ts`). A FILE holding the bearer (a leading `~` is the user's home) — how an interactive operator session declares one, since its `.mcp.json` is git-tracked and can never carry the token itself. Or the bearer VERBATIM — how a dispatch declares one, substituted from its overlay. A declared file is AUTHORITATIVE and its failure is FATAL: an inherited `DANX_DASHBOARD_CREDENTIAL` is never consulted instead, because on an operator machine that value routinely names a different (local-dev) dashboard, which answers healthily and empty. The same resolver serves the `bridge` subcommand below, so a session's tools and its event stream can never sign in as two different identities |
+| `DANX_DASHBOARD_CREDENTIAL` | A DISPATCH's credential: the bearer verbatim, substituted into the materialized `.mcp.json` from its overlay (DX-2862, `src/credential.ts`). Authoritative when set; it never signs out. An operator session sets nothing: with no credential the server boots SIGNED OUT, every tool except `plan_connect` returns one "not signed in" halt, and `plan_connect` requests access (below). The same resolver serves the `bridge` subcommand, so a session's tools and its event stream can never sign in as two different identities |
 | `DANX_REPO_NAME` | Repo half of the qualified board id |
 | `DANXBOT_BOARD_NAME` | Board-slug half of the qualified board id (the dispatch injects `board.slug` here) |
 
 BOARD-ONLY (DX-1171): board is the first-level concept; repo is DERIVED from board server-side, never passed. At boot the package composes the dispatch's qualified board id `<repo>:<slug>` from `DANX_REPO_NAME` + `DANXBOT_BOARD_NAME` and appends it as `?board=<id>` (and `body.board` on create) to every `/api/issues/*` request. Each tool exposes an optional `board` arg — a FULL qualified id `<repo>:<slug>` (e.g. `platform:the-supply-operations-hub`) — that overrides it per-call for cross-board reads/writes (unknown board → 404). The dashboard owns board→repo resolution; this package never sends `repo`.
 
+## Signing in (DX-4390): request and approve
+
+An operator session has no stored credential. Signed out, `plan_connect` (optionally with `title`, the session's own Claude title) posts `POST /api/access-requests` and answers at once `{state: "approval_required", approvalUrl, confirmCode, expiresAt, instruction}`: show the user the code and open the URL; they approve in the dashboard. The server polls `POST /api/access-requests/claim` in the background, so the key is stored when the approval lands; the next `plan_connect` waits up to about 45 seconds for it, then connects, or answers `approval_pending`. One tool call never blocks for minutes. `denied` is reported once; a request that lapsed (the dashboard deletes it within about a minute of expiry, so a claim answers 404) starts a fresh one on the next call.
+
+- **Storage.** `~/.config/danxbot/session-keys/<sha12(dashboard url)>/<session id>.json`, mode 0600, written write-then-rename, pruned after 7 days. One file per dashboard and per session; the bridge reads the same file through the `session-key` credential source and proves the fingerprint. The key lapses on the dashboard after 24 hours without use (every authenticated call, and the bridge's heartbeat, renew it), and is revocable from the account page.
+- **A 401 on the stored key** deletes the file and returns the sign-in halt (in `plan_connect`: a new request in the same call). **A 404 on create** means the dashboard predates request-and-approve and says so.
+- A dispatch's `DANX_DASHBOARD_CREDENTIAL` skips all of this. There is no token-file credential source.
+
 ## 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:
@@ -39,7 +47,7 @@ A program runs this, not an agent: the danxbot Claude Code plugin's plan event b
 CLAUDE_CODE_SESSION_ID=<session> npx -y @thehammer/danx-dashboard-mcp@<version> bridge [--resume-ids <id>,<id>,...]
 ```
 
-- **Credential — the session's own, never the ambient one (DX-2862).** The session id is the only thing `bridge` takes from its environment; `--resume-ids` is the only argument and holds no secret. Everything else comes from the connection record this session's own danx-dashboard MCP server wrote on `plan_connect` (`src/session-connection.ts`): the dashboard URL, the credential's SOURCE, and its FINGERPRINT. `bridge` resolves that source through the same resolver the server used and refuses to run unless the result fingerprints identically — `credential_mismatch`. Before that fix it used whatever `DANX_DASHBOARD_CREDENTIAL` the session's environment held, and on a machine where that differed from the server's credential the dashboard admitted the stream and dropped every event, with nothing logged anywhere.
+- **Credential — the session's own, never the ambient one (DX-2862).** The session id is the only thing `bridge` takes from its environment; `--resume-ids` is the only argument and holds no secret. Everything else comes from the connection record this session's own danx-dashboard MCP server wrote on `plan_connect` (`src/session-connection.ts`): the dashboard URL, the credential's SOURCE (a session key file, or the env var name), and its FINGERPRINT. `bridge` resolves that source through the same resolver the server used and refuses to run unless the result fingerprints identically — `credential_mismatch`. Before that fix it used whatever `DANX_DASHBOARD_CREDENTIAL` the session's environment held, and on a machine where that differed from the server's credential the dashboard admitted the stream and dropped every event, with nothing logged anywhere.
 - **No client-side reach check (DX-2920).** `bridge` used to prove board reach itself, before ever opening the stream (`GET /api/plans/mine?fields=cards` + a per-board `GET /api/issues/:id/problems`). That check is DELETED. The dashboard briefly enforced the identical requirement server-side (DX-2863: refusing a mint or stream admission with `403 issuer_cannot_read_plan_boards`, and ending a live stream `{"reason":"scope_narrowed","boards":[…]}`), but DX-3468 removed that mechanism too — DX-3409 made every credential team-bound, so a plan session's issuer and every board its connected plan covers are always in the same team, and the check could never fire any more. `bridge` no longer independently verifies board reach at all, client- or server-side. Once a ticket is minted, `bridge` emits, once, `{"type":"ready"}` — no `boards` field, since reach is no longer proven client-side.
 - **Ticket.** `bridge` mints the session's listener ticket (`POST /api/plan-sessions/me/stream-ticket`, 10 s timeout) and keeps it in the process. A ticket authorizes reading that one session's event stream and nothing else, and is only issued while the session is connected to a plan. Minting a new one ends the previous listener.
 - **Output — JSON Lines.** One `{"type":"event","id":<id|null>,"text":"…"}` per event on the connected plan's cards, where `text` is `[DX-8 "Title" repo:board] newms87 answered "Which rollout order?": chose "Pause E2E" — note: "only this week"`, `… answered "…": "<free-form answer>"`, `… commented: "…"`, `… opened a problem: "…"`, `… blocked the card: "…"`, or `… unblocked the card`. An event it cannot read still produces one, with a `could not read event` text. Nothing for keep-alives, reconnects or re-mints. The session's own writes are never echoed back to it.

package/dist/access-request.js

@@ -0,0 +1,90 @@
+import { assertVersionFloorSatisfied, MCP_MIN_VERSION_HEADER } from "./version-floor.js";
+function baseOf(dashboardUrl) {
+    return dashboardUrl.replace(/\/+$/, "");
+}
+async function postPublic(fetchImpl, url, body) {
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        throw new Error(`[danx-dashboard-mcp] network failure on POST ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    assertVersionFloorSatisfied(res.headers.get(MCP_MIN_VERSION_HEADER));
+    const text = await res.text();
+    if (res.status >= 500) {
+        throw new Error(`[danx-dashboard-mcp] server error ${res.status} on POST ${url}: ${text.slice(0, 500)}`);
+    }
+    let json = null;
+    if (text !== "") {
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`[danx-dashboard-mcp] non-JSON response (status ${res.status}) from POST ${url}: ${text.slice(0, 200)}`);
+        }
+    }
+    return { status: res.status, headers: res.headers, json };
+}
+/** When a 429 carries no usable `Retry-After`, wait this long before the next try. */
+const DEFAULT_RETRY_AFTER_SECONDS = 1;
+function retryAfterSeconds(headers) {
+    const seconds = Number(headers.get("retry-after"));
+    return Number.isFinite(seconds) && seconds > 0 ? seconds : DEFAULT_RETRY_AFTER_SECONDS;
+}
+function isCreated(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.publicId === "string" &&
+        typeof v.secret === "string" &&
+        typeof v.confirmCode === "string" &&
+        typeof v.approvalUrl === "string" &&
+        typeof v.expiresAt === "string" &&
+        Number.isFinite(Date.parse(v.expiresAt)) &&
+        typeof v.pollMs === "number");
+}
+export async function createAccessRequest(fetchImpl, dashboardUrl, input) {
+    const url = `${baseOf(dashboardUrl)}/api/access-requests`;
+    const { status, headers, json } = await postPublic(fetchImpl, url, input);
+    if (status === 201) {
+        if (!isCreated(json)) {
+            throw new Error(`[danx-dashboard-mcp] POST ${url} answered 201 without the access request fields: ${JSON.stringify(json)}`);
+        }
+        return { kind: "created", request: json };
+    }
+    if (status === 404)
+        return { kind: "dashboard_outdated" };
+    if (status === 429)
+        return { kind: "rate_limited", retryAfterSeconds: retryAfterSeconds(headers) };
+    return { kind: "refused", status, body: json };
+}
+export async function claimAccessRequest(fetchImpl, dashboardUrl, secret) {
+    const url = `${baseOf(dashboardUrl)}/api/access-requests/claim`;
+    const { status, headers, json } = await postPublic(fetchImpl, url, { secret });
+    if (status === 404)
+        return { kind: "not_found" };
+    if (status === 429)
+        return { kind: "rate_limited", retryAfterSeconds: retryAfterSeconds(headers) };
+    if (status !== 200)
+        return { kind: "refused", status, body: json };
+    const body = json;
+    switch (body?.status) {
+        case "pending":
+        case "denied":
+        case "expired":
+        case "claimed":
+            return { kind: body.status };
+        case "approved":
+            if (typeof body.apiKey !== "string" || body.apiKey === "") {
+                throw new Error(`[danx-dashboard-mcp] POST ${url} answered approved without an apiKey`);
+            }
+            return { kind: "approved", apiKey: body.apiKey };
+        default:
+            throw new Error(`[danx-dashboard-mcp] POST ${url} answered an unknown status: ${JSON.stringify(json)}`);
+    }
+}

package/dist/bridge.js

@@ -216,11 +216,11 @@ const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${B
 export const STOP_FIXES = {
     no_connection_record: "call plan_connect again in this session — its danx-dashboard MCP server records the connection the bridge needs " +
         "(a server older than the one that introduced the record writes none)",
-    credential_unavailable: "fix the credential this session's danx-dashboard MCP server declares, then call plan_connect again",
+    credential_unavailable: "call plan_connect again to request access: this session's key file is missing or unreadable",
     credential_mismatch: "restart this Claude Code session so its MCP server and its bridge pick up the same credential, then call plan_connect again",
     not_connected: "call plan_connect to connect this session to a plan",
     plan_archived: "the plan was archived or deleted, so this session was disconnected; ask the operator to restore it, then call plan_connect again",
-    unauthorized: "give this session's danx-dashboard MCP server a dashboard credential that is accepted, then call plan_connect again",
+    unauthorized: "the dashboard no longer accepts this session's key (revoked, or lapsed after a day unused): call plan_connect again to request access",
     mint_refused: "check that this session is connected to a plan on the dashboard its MCP server points at, then call plan_connect again",
     mint_bad_response: "check that DANXBOT_DASHBOARD_URL for this session's MCP server points at a danxbot dashboard",
     // A newer ticket exists (superseded) or another connection is already using
@@ -300,13 +300,13 @@ function resolveInstanceId(env) {
 }
 /**
  * DX-3028 — the on-disk paths this bridge's authentication depends on, for
- * `BridgeOptions.watchedPaths` (see its docblock). A `file`-sourced
+ * `BridgeOptions.watchedPaths` (see its docblock). A `session-key`
  * credential adds its own path; an `env`-sourced one has no file
  * (`credential.ts` ~47-48, ~90-95).
  */
 function watchedPathsFor(record, home) {
     const paths = [sessionConnectionPath(record.sessionId, home)];
-    if (record.source.kind === "file")
+    if (record.source.kind === "session-key")
         paths.push(record.source.path);
     return paths;
 }

package/dist/credential.js

@@ -1,50 +1,34 @@
 /**
- * DX-2862 — the ONE resolver for this package's dashboard credential.
+ * DX-2862 / DX-4390 - the ONE resolver for this package's dashboard credential.
  *
- * WHY IT IS ONE FUNCTION AND NOT TWO. Two processes speak to the dashboard for
- * the same Claude Code session: the MCP SERVER (the session's card + plan tools)
- * and `danx-dashboard-mcp bridge` (the session's event stream, run by the
- * danxbot plugin's plan event bridge). Before this module they resolved their
- * credential independently — the server through danxbot's operator launcher,
- * which read a token file, and the bridge from whatever credential variable
- * happened to be in the session's environment. On a machine where those two
- * differ (DX-2862: `ffe9f8a882f0…` in the environment, `6f9bc6e94b83…` in
- * `~/.config/danxbot/dashboard-token-gpt`) the session's tools worked, the
- * bridge's stream was admitted, and every operator comment was dropped with no
- * error anywhere. So resolution lives HERE, both callers go through it, and the
- * bridge additionally PROVES it holds the server's credential by comparing
- * fingerprints (`session-connection.ts`).
+ * WHY IT IS ONE FUNCTION AND NOT TWO. Two processes speak to the dashboard for the same Claude
+ * Code session: the MCP SERVER (the session's card + plan tools) and `danx-dashboard-mcp bridge`
+ * (the session's event stream, run by the danxbot plugin's plan event bridge). When they resolved
+ * their credential independently they could differ (DX-2862): the session's tools worked, the
+ * bridge's stream was admitted, and every operator comment was dropped with no error anywhere.
+ * So resolution lives HERE, both callers go through it, and the bridge additionally PROVES it
+ * holds the server's credential by comparing fingerprints (`session-connection.ts`).
  *
- * THE DECLARATION. A server's env declares where its credential comes from:
+ * A credential comes from exactly one of two places:
  *
- *   - `DANXBOT_DASHBOARD_TOKEN_FILE` — a path (a leading `~` is this user's
- *     home). The file's trimmed contents are the credential. This is how an
- *     interactive operator session declares one, because its `.mcp.json` is
- *     git-tracked and can never carry the bearer itself.
- *   - `DANX_DASHBOARD_CREDENTIAL` — the credential verbatim. This is how a
- *     DISPATCH declares one: the worker substitutes it into the materialized
- *     `.mcp.json` from the dispatch overlay.
+ *   - `DANX_DASHBOARD_CREDENTIAL` - the bearer verbatim. A DISPATCH declares it: the worker
+ *     substitutes it into the materialized `.mcp.json` from the dispatch overlay. Authoritative
+ *     when set, and it never signs out.
+ *   - a SESSION KEY (`session-key.ts`) - the key a user approved for this one session through
+ *     `plan_connect`. An operator session has no other credential: with neither of these it boots
+ *     signed out, and `plan_connect` asks for access.
  *
- * A DECLARED FILE IS AUTHORITATIVE, AND ITS FAILURE IS FATAL. When the file
- * variable is set, `DANX_DASHBOARD_CREDENTIAL` is never consulted — not even when
- * the file is missing or empty. That is the DX-2483 rule, moved here from the
- * launcher it used to live in: an operator machine routinely carries an
- * inherited env credential naming the LOCAL dev dashboard, which
- * answers healthily and empty for a board it does not carry, so preferring it
- * after a failed file read would turn a loud, fixable error into exactly the
- * silent wrong-dashboard answer this whole module exists to prevent.
+ * There is no token-file source (DX-4390): a long-lived bearer placed on disk by hand is exactly
+ * what request-and-approve replaces.
  */
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
-export const CREDENTIAL_FILE_ENV = "DANXBOT_DASHBOARD_TOKEN_FILE";
+import { SessionKeyAbsentError, readSessionKeyFile, sessionKeyPath, } from "./session-key.js";
 export const CREDENTIAL_TOKEN_ENV = "DANX_DASHBOARD_CREDENTIAL";
 /**
- * A credential that cannot be resolved. Carries the remedy beside the reason,
- * because both of this module's callers report failures to a human who is not
- * reading a log: the server exits with it on stderr, and the bridge posts it
- * into the session's inbox.
+ * A credential that cannot be resolved. Carries the remedy beside the reason, because both of this
+ * module's callers report failures to a human who is not reading a log: the server prints it to
+ * stderr, and the bridge posts it into the session's inbox.
  */
 export class CredentialError extends Error {
     fix;
@@ -54,72 +38,68 @@ export class CredentialError extends Error {
         this.fix = fix;
     }
 }
-const DECLARE_ONE = `declare the credential in this MCP server's env: ${CREDENTIAL_FILE_ENV}=<path to a file holding the ` +
-    `dashboard bearer> (an operator session), or ${CREDENTIAL_TOKEN_ENV}=<the bearer> (a dispatch)`;
-/** `~` / `~/x` / `~\x` mean this user's home; every other path is returned as given. */
-export function expandHome(path, home = homedir()) {
-    if (path === "~")
-        return home;
-    if (path.startsWith("~/") || path.startsWith("~\\"))
-        return join(home, path.slice(2));
-    return path;
-}
 function readEnv(env, name) {
     const value = env[name];
     return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
 }
-/**
- * WHICH source this environment declares. Throws `CredentialError` when it
- * declares none — never a guess, and never an anonymous client.
- */
-export function declaredCredentialSource(env, home = homedir()) {
-    const file = readEnv(env, CREDENTIAL_FILE_ENV);
-    if (file !== null) {
-        const expanded = expandHome(file, home);
-        return { kind: "file", path: isAbsolute(expanded) ? expanded : resolve(expanded) };
-    }
-    if (readEnv(env, CREDENTIAL_TOKEN_ENV) !== null)
-        return { kind: "env", name: CREDENTIAL_TOKEN_ENV };
-    throw new CredentialError(`no dashboard credential is declared (neither ${CREDENTIAL_FILE_ENV} nor ${CREDENTIAL_TOKEN_ENV} is set)`, DECLARE_ONE);
-}
 /** One line naming a source, for a message a human reads. Holds no secret. */
 export function describeCredentialSource(source) {
-    return source.kind === "file" ? `the token file ${source.path}` : `the environment variable ${source.name}`;
+    return source.kind === "session-key"
+        ? `the session key file ${source.path}`
+        : `the environment variable ${source.name}`;
 }
 /** The credential a source yields. Every failure is fatal and named. */
 export function readCredential(source, env) {
     if (source.kind === "env") {
         const token = readEnv(env, source.name);
         if (token === null) {
-            throw new CredentialError(`${describeCredentialSource(source)} is unset or empty in this process`, `set ${source.name} for this process, or declare ${CREDENTIAL_FILE_ENV} instead`);
+            throw new CredentialError(`${describeCredentialSource(source)} is unset or empty in this process`, `set ${source.name} for this process`);
         }
         return token;
     }
-    let contents;
     try {
-        contents = readFileSync(source.path, "utf-8");
+        return readSessionKeyFile(source.path);
     }
     catch (err) {
-        throw new CredentialError(`cannot read ${describeCredentialSource(source)}: ${err.message}`, `create that file holding this dashboard's bearer token, or point ${CREDENTIAL_FILE_ENV} at one that exists`);
-    }
-    const token = contents.trim();
-    if (token === "") {
-        throw new CredentialError(`${describeCredentialSource(source)} is empty`, `write this dashboard's bearer token into that file`);
+        throw new CredentialError(`cannot read ${describeCredentialSource(source)}: ${err.message}`, "call plan_connect to request access again; the key file is written when the request is approved");
     }
-    return token;
 }
 /**
- * A credential's IDENTITY, for comparing two processes' credentials without
- * either of them handling the other's. The first 12 hex of SHA-256 — 48 bits,
- * enough that two distinct 48-character tokens colliding is not a thing that
- * happens, and nothing an attacker can invert.
+ * A credential's IDENTITY, for comparing two processes' credentials without either of them
+ * handling the other's. The first 12 hex of SHA-256 - 48 bits, enough that two distinct tokens
+ * colliding is not a thing that happens, and nothing an attacker can invert.
  */
 export function credentialFingerprint(token) {
     return createHash("sha256").update(token).digest("hex").slice(0, 12);
 }
-/** Declare, read, fingerprint — what the MCP server does at boot. */
-export function resolveDeclaredCredential(env, home = homedir()) {
-    const source = declaredCredentialSource(env, home);
-    const token = readCredential(source, env);
-    return { source, token, fingerprint: credentialFingerprint(token) };
+/**
+ * This session's stored key, or `null` (never signed in here). A key file that is there but
+ * unusable throws `SessionKeyUnusableError`: the caller decides what to do with the file, nothing
+ * is guessed here. Never reads the environment: an operator tool that must authenticate as the
+ * session (`make finish-worktree`) uses this alone, so an inherited dispatch credential cannot win.
+ */
+export function resolveSessionKeyCredential(where) {
+    if (where.sessionId === undefined)
+        return null;
+    const path = sessionKeyPath(where.dashboardUrl, where.sessionId, where.home ?? homedir());
+    try {
+        const key = readSessionKeyFile(path);
+        return { source: { kind: "session-key", path }, token: key, fingerprint: credentialFingerprint(key) };
+    }
+    catch (err) {
+        if (err instanceof SessionKeyAbsentError)
+            return null;
+        throw err;
+    }
+}
+/**
+ * What this server boots with: the dispatch credential when the env declares one, else this
+ * session's stored key, else `null` (signed out).
+ */
+export function resolveBootCredential(env, where) {
+    const token = readEnv(env, CREDENTIAL_TOKEN_ENV);
+    if (token !== null) {
+        return { source: { kind: "env", name: CREDENTIAL_TOKEN_ENV }, token, fingerprint: credentialFingerprint(token) };
+    }
+    return resolveSessionKeyCredential(where);
 }

package/dist/http-client.js

@@ -10,7 +10,18 @@ export class DashboardHttpClient {
         this.config = config;
         this.fetchImpl = fetchImpl;
     }
+    /**
+     * DX-4390 — the bearer this client stamps. A session signs in (or out) while the server runs, so
+     * the key is not fixed at construction; "" means signed out.
+     */
+    setToken(token) {
+        this.config.token = token;
+    }
     async request(args) {
+        if (this.config.token === "") {
+            // DX-4390 — a caller reaches here only past the sign-in halt; a bearer-less call is a bug.
+            throw new Error("[danx-dashboard-mcp] request attempted while signed out");
+        }
         const url = this.buildUrl(args.method, args.path, args.query, args.board, args.basePath);
         const headers = {
             Authorization: `Bearer ${this.config.token}`,

package/dist/index.js

@@ -49,15 +49,13 @@
  *
  * Env at boot (validated fail-loud — missing → process.exit(1)):
  *   DANXBOT_DASHBOARD_URL   dashboard base (e.g. http://danxbot-dashboard:5555)
- *   the CREDENTIAL, declared exactly one of two ways and resolved by the ONE
- *   resolver this package's event bridge also uses (`credential.ts`, DX-2862):
- *     DANXBOT_DASHBOARD_TOKEN_FILE  a file holding the bearer (an operator
- *                           session, whose `.mcp.json` is git-tracked and so
- *                           can never carry one); authoritative when set, and
- *                           its failure is fatal — an inherited
- *                           DANX_DASHBOARD_CREDENTIAL is never consulted instead
+ *   the CREDENTIAL (DX-4390), resolved by the ONE resolver this package's event bridge
+ *   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`)
  *   DANX_REPO_NAME          repo half of the qualified board id
  *   DANXBOT_BOARD_NAME      board-slug half of the qualified board id
  *                           (the dispatch injects `board.slug` here);
@@ -78,7 +76,10 @@ import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./backgrou
 import { ACTIVITY_SUBCOMMAND, runActivityCommand } from "./activity.js";
 import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
 import { RESTART_NOTICE_SUBCOMMAND, runRestartNoticeCommand } from "./restart-notice.js";
-import { resolveDeclaredCredential } from "./credential.js";
+import { resolveBootCredential } from "./credential.js";
+import { SessionKeyUnusableError, deleteSessionKey } from "./session-key.js";
+import { SessionAccess } from "./session-access.js";
+import { readOwnVersion } from "./version-floor.js";
 import { projectKeyOf, recordSessionConnectionAfterConnect, removeSessionConnectionAfterLeave } from "./session-connection.js";
 import { createListenerReminder, isPlanConnectedOnThisMachine, } from "./listener-reminder.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -121,12 +122,12 @@ let client;
 // DX-3997 — late-bound with `client`; see `listener-reminder.ts`.
 let listenerReminder;
 /**
- * DX-2862 — what this server would tell the session's plan event bridge about
- * how to reach the dashboard AS THIS SERVER: the URL, where the credential came
- * from, and the credential's fingerprint. Never the credential itself. Written
- * to the session's connection record on a successful `plan_connect`.
+ * DX-4390 — this server's credential: a dispatch's env bearer, this session's approved key, or
+ * none (signed out). It also tells the session's plan event bridge how to reach the dashboard AS
+ * THIS SERVER (`access.connection()`: the URL, where the credential is, its fingerprint; never the
+ * credential itself), written to the session's connection record on a successful `plan_connect`.
  */
-let connection;
+let access;
 /**
  * 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
@@ -135,25 +136,32 @@ let connection;
  * Both halves are fail-loud required (Core Principle 1 — no fallback).
  */
 function boot() {
-    const credential = resolveCredentialOrDie();
+    const dashboardUrl = readEnvOrDie("DANXBOT_DASHBOARD_URL");
+    const repo = readEnvOrDie("DANX_REPO_NAME");
+    const session = readSessionConfig();
     config = {
-        baseUrl: readEnvOrDie("DANXBOT_DASHBOARD_URL"),
-        token: credential.token,
-        board: `${readEnvOrDie("DANX_REPO_NAME")}:${readEnvOrDie("DANXBOT_BOARD_NAME")}`,
+        baseUrl: dashboardUrl,
+        // DX-4390 — set by `SessionAccess` below; "" while signed out.
+        token: "",
+        board: `${repo}:${readEnvOrDie("DANXBOT_BOARD_NAME")}`,
         // 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: readSessionConfig(),
-    };
-    connection = {
-        dashboardUrl: config.baseUrl.replace(/\/+$/, ""),
-        source: credential.source,
-        fingerprint: credential.fingerprint,
+        session,
     };
     client = new DashboardHttpClient(config);
     const dashboardClient = client;
+    access = new SessionAccess({
+        dashboardUrl,
+        sessionId: session?.id,
+        repo,
+        clientVersion: readOwnVersion(),
+        setToken: (token) => dashboardClient.setToken(token),
+        initial: resolveInitialCredential(dashboardUrl, session?.id),
+        log: (line) => console.error(line),
+    });
     listenerReminder = createListenerReminder({
         sessionId: config.session?.id,
         fetchHealth: () => dashboardClient.request({ method: "GET", basePath: "", path: "/api/plans", query: { limit: 1 } }),
@@ -171,19 +179,22 @@ function boot() {
     applyLifecycleVisibility(lifecycleTools, readLifecycleUrlsFromEnv());
 }
 /**
- * DX-2862 — the credential, through the ONE resolver the `bridge` subcommand
- * also uses, so a session's tools and its event stream can never sign in as two
- * different identities. A credential that cannot be resolved exits non-zero
- * naming the remedy, never a degraded or anonymous server.
+ * 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
+ * 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 resolveCredentialOrDie() {
+function resolveInitialCredential(dashboardUrl, sessionId) {
     try {
-        return resolveDeclaredCredential(process.env);
+        return resolveBootCredential(process.env, { dashboardUrl, sessionId });
     }
     catch (err) {
-        const credentialError = err;
-        console.error(`[danx-dashboard-mcp] ${credentialError.message}\n  Fix: ${credentialError.fix}`);
-        process.exit(1);
+        if (!(err instanceof SessionKeyUnusableError) || sessionId === undefined)
+            throw err;
+        console.error(`[danx-dashboard-mcp] ${err.message}; deleting it, this session must request access again`);
+        deleteSessionKey(err.path);
+        return null;
     }
 }
 /**
@@ -261,6 +272,21 @@ export const server = new McpServer({
 function haltResult(text) {
     return { content: [{ type: "text", text }], isError: true };
 }
+/**
+ * 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) {
+    if (ready.signedIn)
+        return jsonResult({ state: "signed_in", ...(note ? { note } : {}) });
+    const answer = note ? { ...ready.answer, note } : ready.answer;
+    return ready.isError ? haltResult(JSON.stringify(answer, null, 2)) : jsonResult(answer);
+}
+/** DX-4390 — a tool's dashboard call behind the sign-in halt (and the 401 sign-out). */
+async function guardedJson(run) {
+    const guarded = await access.guard(run);
+    return "halt" in guarded ? haltResult(guarded.halt) : jsonResult(guarded.result);
+}
 function jsonResult(value) {
     return {
         content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
@@ -371,7 +397,10 @@ async (args) => {
     const refused = termsAcceptanceCallHalt(args, config.baseUrl);
     if (refused)
         return haltResult(refused);
-    const result = await danxbotApi(client, args);
+    const guarded = await access.guard(() => danxbotApi(client, args));
+    if ("halt" in guarded)
+        return haltResult(guarded.halt);
+    const result = guarded.result;
     const halt = termsHaltFor(result);
     if (halt)
         return haltResult(halt);
@@ -382,7 +411,7 @@ strictTool("danxbot_api_list",
 // DX-3528 — the list is filtered by the same permission check every request takes.
 "Lists the dashboard API routes your credential may call: `[{method, path, summary, permission}]`, each " +
     "`path` a route template (`/api/issues/:id/transition`), the form `danxbot_api_spec` takes. A route not " +
-    "listed is not callable by you.", {}, async () => jsonResult(await danxbotApiList(client)));
+    "listed is not callable by you.", {}, async () => guardedJson(() => danxbotApiList(client)));
 // ---------------- danxbot_api_spec (DX-3465, PLN-11 R-25) ----------------
 strictTool("danxbot_api_spec", 
 // DX-3527 — the contract is generated from the route table.
@@ -391,7 +420,7 @@ strictTool("danxbot_api_spec",
     '(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),
-}, async (args) => jsonResult(await danxbotApiSpec(client, args)));
+}, async (args) => guardedJson(() => danxbotApiSpec(client, args)));
 // ---------------- attach_file (DX-3465 A4, checklist item 36140) ----------------
 //
 // The "25 MB" ceiling quoted below tracks the backend route's
@@ -404,8 +433,9 @@ strictTool("danxbot_api_spec",
 // might hold locally, e.g. the Slack recovery agent's CSV path).
 strictTool("attach_file", "Attach a LOCAL file to a card. This server reads and uploads the bytes, so they never pass through your " +
     "context. The attachment mirrors to the card's linked Trello card and Slack thread. 25 MB limit (413). " +
-    "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 " +
+    "Returns `{issue, attachment_id, s3_key}`: the entry of `issue.attachments` with that `attachment_id` " +
+    "carries a permanent `url`: 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.", {
     card_id: z.string().min(1).describe("The card id to attach the file to."),
     path: z
@@ -415,7 +445,7 @@ strictTool("attach_file", "Attach a LOCAL file to a card. This server reads and
     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."),
     ...boardField,
-}, async (args) => jsonResult(await attachFile(client, args)));
+}, async (args) => guardedJson(() => attachFile(client, args)));
 // ---------------- 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
@@ -429,14 +459,22 @@ strictTool("attach_file", "Attach a LOCAL file to a card. This server reads and
 strictTool("plan_connect", 
 // 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.
-"Connect THIS session to a plan; one call is enough to start. The reply carries `missedEvents` (operator " +
+// 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). Signed in, the reply carries `missedEvents` (operator " +
     "events on the plan that no session had been told about, oldest first: read them first), " +
     "`browserInstruction` (do it now), `briefing` (the plan's goals, rules, caveats, architecture section " +
     "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, and `movedFrom` names the " +
     "plan it left. Afterwards a `danxbot_api` call to a `/api/plans/mine/...` route acts on this plan and " +
     "takes no plan id.", {
-    plan_id: z.number().int().positive().describe("The plan id, from the plans list (`danxbot_api` `GET /api/plans`)."),
+    plan_id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("The plan id, from the plans list (`danxbot_api` `GET /api/plans`). Omit only to sign in."),
     title: z
         .string()
         .min(1)
@@ -449,7 +487,25 @@ strictTool("plan_connect",
 // session may have configured, the one that connected the plan is the one
 // whose credential the stream must be minted with.
 async (args) => {
-    const result = await planConnect(client, 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) {
+        return jsonResult({
+            state: "signed_in",
+            instruction: "This session is signed in. Call `plan_connect` with `plan_id` to connect it to a plan.",
+        });
+    }
+    const result = await planConnect(client, { ...args, plan_id: args.plan_id });
+    // 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()) {
+        return accessReply(await access.ensureAccess(args.title), "the dashboard no longer accepted this session's key");
+    }
     // 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).
@@ -457,6 +513,9 @@ async (args) => {
         removeSessionConnectionAfterLeave(result, config.session?.id);
         return jsonResult(result);
     }
+    const connection = access.connection();
+    if (connection === null)
+        throw new Error("plan_connect: no credential after a successful connect");
     return jsonResult({
         ...result,
         ...recordSessionConnectionAfterConnect(result, {

package/dist/session-access.js

@@ -0,0 +1,265 @@
+/**
+ * DX-4390 (PLAN-17 section 96) - how this server gets, holds and loses its dashboard credential.
+ *
+ * Three states, none of them a process exit:
+ *
+ *   - `env`         a dispatch declared `DANX_DASHBOARD_CREDENTIAL`; this never signs out.
+ *   - `session-key` a user approved this session's access request; the key is stored per session
+ *                   (`session-key.ts`) and a 401 on it deletes the file (`dropKey`).
+ *   - signed out    no credential. Every tool but `plan_connect` halts; `plan_connect` asks.
+ *
+ * ASKING NEVER BLOCKS FOR MINUTES. The first signed-out `plan_connect` posts the request and
+ * answers at once with the approval URL and confirm code. From then on THIS object polls claim in
+ * the background, so the key is stored the moment the user approves, and the next `plan_connect`
+ * waits at most `awaitMs` (about 45s) for it before answering `approval_pending`. The secret the
+ * poll needs lives only in this process's memory; a restarted session asks again.
+ */
+import { existsSync } from "node:fs";
+import { hostname } from "node:os";
+import { claimAccessRequest, createAccessRequest } from "./access-request.js";
+import { credentialFingerprint } from "./credential.js";
+import { deleteSessionKey, writeSessionKey } from "./session-key.js";
+import { McpOutdatedError } from "./version-floor.js";
+/** Longest a `plan_connect` call waits for an approval already asked for. */
+export const AWAIT_APPROVAL_MS = 45_000;
+/** The server reaps a lapsed request about a minute after expiry; polling past that finds nothing. */
+const POLL_GRACE_MS = 90_000;
+/** A live server rewrites its key file this often, so an in-use key never ages out of the 7-day prune. */
+const KEEP_KEY_FILE_EVERY_MS = 60 * 60 * 1000;
+/** The request's title when the agent gave none: the session id's first characters. */
+const TITLE_FALLBACK_LENGTH = 8;
+export const SIGN_IN_HALT = "Not signed in to the danxbot dashboard. Call `plan_connect` (with `title`: your session's own " +
+    "title) to request access; the user approves it in their browser, then this tool works.";
+export const REVOKED_HALT = "The dashboard no longer accepts this session's key (it was revoked, or it lapsed after a day " +
+    "unused), so this session is signed out. " +
+    SIGN_IN_HALT;
+const APPROVAL_REQUIRED_INSTRUCTION = "Show the user the confirm code and open the approval URL in their browser; they check the code " +
+    "matches and approve. Then call `plan_connect` again: it waits up to about 45 seconds for the approval.";
+const APPROVAL_PENDING_INSTRUCTION = "Still waiting for the user to approve. Remind them of the confirm code and the URL, then call " +
+    "`plan_connect` again.";
+const DENIED_INSTRUCTION = "The user denied the request. Do not retry unless they ask; a new `plan_connect` makes a new request.";
+const DASHBOARD_OUTDATED_ERROR = "this dashboard does not support request-and-approve yet (POST /api/access-requests answered 404): " +
+    "it must be updated before this session can sign in";
+const RATE_LIMITED_ERROR = "too many access requests from this address; wait, then call plan_connect again";
+const NO_SESSION_ID_ERROR = "this server has no CLAUDE_CODE_SESSION_ID, so it cannot request a session key";
+const CLAIMED_LOST_ERROR = "the dashboard says this request was already claimed, but this process never received the key; " +
+    "start a new request";
+const EXPIRED_NOTE = "The previous request expired before it was approved.";
+const defaultSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms).unref();
+});
+const notReady = (answer, isError) => ({
+    signedIn: false,
+    answer,
+    isError,
+});
+export class SessionAccess {
+    deps;
+    credential;
+    pending = null;
+    // DX-4390: two concurrent signed-out plan_connect calls must not each post a request.
+    ensureQueue = Promise.resolve();
+    lastKeyFileWrite = 0;
+    fetchImpl;
+    now;
+    sleep;
+    awaitMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.credential = deps.initial;
+        this.fetchImpl = deps.fetch ?? fetch;
+        this.now = deps.now ?? Date.now;
+        this.sleep = deps.sleep ?? defaultSleep;
+        this.awaitMs = deps.awaitMs ?? AWAIT_APPROVAL_MS;
+        deps.setToken(deps.initial?.token ?? "");
+    }
+    isSignedIn() {
+        return this.credential !== null;
+    }
+    /** Where the current credential comes from and its fingerprint, for the bridge's connection record. */
+    connection() {
+        if (this.credential === null)
+            return null;
+        return {
+            dashboardUrl: this.deps.dashboardUrl.replace(/\/+$/, ""),
+            source: this.credential.source,
+            fingerprint: this.credential.fingerprint,
+        };
+    }
+    /**
+     * The dashboard answered 401 to this session's key: drop it. A dispatch credential is never
+     * dropped (the dispatch owns it). True when this signed the session out.
+     */
+    dropKey() {
+        if (this.credential === null || this.credential.source.kind !== "session-key")
+            return false;
+        deleteSessionKey(this.credential.source.path);
+        this.credential = null;
+        this.pending = null; // DX-4390: a settled request of the dropped key must not read as "expired"
+        this.deps.setToken("");
+        return true;
+    }
+    /**
+     * Run a dashboard call for a tool: halted while signed out, and signed out (key file deleted)
+     * when the dashboard answers 401 to this session's key.
+     */
+    async guard(run) {
+        if (this.credential === null)
+            return { halt: SIGN_IN_HALT };
+        const result = await run();
+        if (result.status === 401 && this.dropKey())
+            return { halt: REVOKED_HALT };
+        this.keepKeyFile();
+        return { result };
+    }
+    /**
+     * DX-4390: the stored file is the bridge's only way to the key, and the 7-day prune ages out
+     * a file by when it was last written. A server in use rewrites it (atomically) at most hourly,
+     * which also restores a file someone deleted while this process still holds the key.
+     */
+    keepKeyFile() {
+        const credential = this.credential;
+        if (credential === null || credential.source.kind !== "session-key")
+            return;
+        const now = this.now();
+        if (now - this.lastKeyFileWrite < KEEP_KEY_FILE_EVERY_MS && existsSync(credential.source.path))
+            return;
+        try {
+            writeSessionKey({ dashboardUrl: this.deps.dashboardUrl, sessionId: this.deps.sessionId, apiKey: credential.token }, { home: this.deps.home, now });
+            this.lastKeyFileWrite = now;
+        }
+        catch (err) {
+            this.deps.log?.(`[danx-dashboard-mcp] could not refresh the session key file: ${err.message}`);
+        }
+    }
+    /**
+     * Make sure this session holds a key. Signed in: `{signedIn: true}`. Otherwise the answer
+     * `plan_connect` returns: the request just made, the one still pending (after waiting up to
+     * `awaitMs` for it), or why there is none. Calls run one at a time.
+     */
+    ensureAccess(title) {
+        const run = this.ensureQueue.then(() => this.ensureAccessNow(title));
+        this.ensureQueue = run.catch(() => undefined);
+        return run;
+    }
+    async ensureAccessNow(title) {
+        if (this.credential !== null)
+            return { signedIn: true };
+        const sessionId = this.deps.sessionId;
+        if (sessionId === undefined || sessionId === "") {
+            return notReady({ state: "no_session_id", error: NO_SESSION_ID_ERROR }, true);
+        }
+        let note;
+        if (this.pending !== null) {
+            const pending = this.pending;
+            const outcome = await Promise.race([pending.settled, this.sleep(this.awaitMs).then(() => null)]);
+            if (outcome === null)
+                return notReady(this.requestAnswer("approval_pending", pending.request), false);
+            this.pending = null;
+            switch (outcome.kind) {
+                case "approved":
+                    return { signedIn: true };
+                case "denied":
+                    return notReady({ state: "denied", instruction: DENIED_INSTRUCTION }, false);
+                case "failed":
+                    return notReady({ state: "request_failed", error: outcome.error }, true);
+                case "expired":
+                    note = EXPIRED_NOTE;
+            }
+        }
+        return this.createRequest(sessionId, title, note);
+    }
+    async createRequest(sessionId, title, note) {
+        const created = await createAccessRequest(this.fetchImpl, this.deps.dashboardUrl, {
+            kind: "session",
+            labelId: sessionId,
+            title: title ?? sessionId.slice(0, TITLE_FALLBACK_LENGTH),
+            repo: this.deps.repo,
+            machine: this.deps.machine ?? hostname(),
+            clientVersion: this.deps.clientVersion,
+        });
+        switch (created.kind) {
+            case "dashboard_outdated":
+                return notReady({ state: "dashboard_outdated", error: DASHBOARD_OUTDATED_ERROR }, true);
+            case "rate_limited":
+                return notReady({ state: "rate_limited", retryAfterSeconds: created.retryAfterSeconds, error: RATE_LIMITED_ERROR }, true);
+            case "refused":
+                return notReady({ state: "request_refused", status: created.status, body: created.body }, true);
+            case "created":
+                this.pending = { request: created.request, settled: this.pollUntilSettled(created.request) };
+                return notReady({ ...this.requestAnswer("approval_required", created.request), ...(note ? { note } : {}) }, false);
+        }
+    }
+    requestAnswer(state, request) {
+        return {
+            state,
+            approvalUrl: request.approvalUrl,
+            confirmCode: request.confirmCode,
+            expiresAt: request.expiresAt,
+            instruction: state === "approval_required" ? APPROVAL_REQUIRED_INSTRUCTION : APPROVAL_PENDING_INSTRUCTION,
+        };
+    }
+    async pollUntilSettled(request) {
+        const giveUpAt = Date.parse(request.expiresAt) + POLL_GRACE_MS;
+        let waitMs = request.pollMs;
+        for (;;) {
+            await this.sleep(waitMs);
+            waitMs = request.pollMs;
+            if (this.now() > giveUpAt)
+                return { kind: "expired" };
+            let claim;
+            try {
+                claim = await claimAccessRequest(this.fetchImpl, this.deps.dashboardUrl, request.secret);
+            }
+            catch (err) {
+                // A claim the dashboard could not answer is retried until the request lapses; an outdated
+                // MCP will never get a different answer, so that one ends it.
+                if (err instanceof McpOutdatedError)
+                    return { kind: "failed", error: err.message };
+                this.deps.log?.(`[danx-dashboard-mcp] access request poll failed, retrying: ${err.message}`);
+                continue;
+            }
+            switch (claim.kind) {
+                case "pending":
+                    continue;
+                case "rate_limited":
+                    waitMs = Math.max(request.pollMs, claim.retryAfterSeconds * 1000);
+                    continue;
+                case "approved":
+                    return this.storeKey(claim.apiKey);
+                case "denied":
+                    return { kind: "denied" };
+                case "expired":
+                case "not_found":
+                    return { kind: "expired" };
+                case "claimed":
+                    return { kind: "failed", error: CLAIMED_LOST_ERROR };
+                case "refused":
+                    return {
+                        kind: "failed",
+                        error: `the dashboard refused the claim (${claim.status}): ${JSON.stringify(claim.body)}`,
+                    };
+            }
+        }
+    }
+    storeKey(apiKey) {
+        const now = this.now();
+        try {
+            const path = writeSessionKey({ dashboardUrl: this.deps.dashboardUrl, sessionId: this.deps.sessionId, apiKey }, { home: this.deps.home, now });
+            this.credential = {
+                source: { kind: "session-key", path },
+                token: apiKey,
+                fingerprint: credentialFingerprint(apiKey),
+            };
+            this.lastKeyFileWrite = now;
+            this.deps.setToken(apiKey);
+            return { kind: "approved" };
+        }
+        catch (err) {
+            return {
+                kind: "failed",
+                error: `the request was approved but storing the key failed: ${err.message}; start a new request`,
+            };
+        }
+    }
+}

package/dist/session-connection.js

@@ -10,7 +10,7 @@
  * the server's, every event was dropped silently (the card's incident).
  *
  * WHAT IS WRITTEN, AND WHAT IS NOT. On a successful `plan_connect` the server
- * writes the dashboard URL, the credential SOURCE (a file path, or the name of
+ * writes the dashboard URL, the credential SOURCE (a session key file path, or the name of
  * an env var — never a credential) and the credential's FINGERPRINT. The bridge
  * reads that record, resolves the SAME source through the same resolver
  * (`credential.ts`), and refuses to run unless what it resolved fingerprints
@@ -36,7 +36,9 @@ import { join, resolve, win32 } from "node:path";
 // DX-3928 — v2 adds `projectKey`, the directory the connecting session ran in, so a
 // restarted session (a NEW session id, no record of its own) can find which plan the
 // previous session of the same project was on (`findPredecessorCandidates`).
-export const SESSION_CONNECTION_SCHEMA_VERSION = 2;
+export const SESSION_CONNECTION_SCHEMA_VERSION = 3;
+// DX-4390 — v3: the credential source is `session-key` (an approved per-session key file) or `env`;
+// the v2 `file` source (a hand-placed token file) no longer exists.
 export const STALE_RECORD_MS = 7 * 24 * 60 * 60 * 1000;
 /**
  * DX-3928 — the one definition of "the same project": the resolved working
@@ -54,15 +56,21 @@ export function projectKeyOf(cwd) {
 export function sessionConnectionDir(home = homedir()) {
     return join(home, ".config", "danxbot", "plan-sessions");
 }
-/** A session id is a path segment here, so an odd one is refused rather than turned into a path. */
-export function sessionConnectionPath(sessionId, home = homedir()) {
+/**
+ * A session id is a path segment (here and in `session-key.ts`), so an odd one is refused rather than
+ * turned into a path.
+ */
+export function assertSessionIdSegment(sessionId) {
     if (typeof sessionId !== "string" || !/^[A-Za-z0-9_-]+$/.test(sessionId)) {
         throw new Error(`session id is missing or has unexpected characters: ${JSON.stringify(sessionId)}`);
     }
+}
+export function sessionConnectionPath(sessionId, home = homedir()) {
+    assertSessionIdSegment(sessionId);
     return join(sessionConnectionDir(home), `${sessionId}.json`);
 }
-/** Remove records nothing has touched for `STALE_RECORD_MS`. */
-export function pruneStaleConnections(dir, now) {
+/** Remove the per-session `.json` files in `dir` that nothing has touched for `STALE_RECORD_MS`. */
+export function pruneStaleSessionFiles(dir, now) {
     let names;
     try {
         names = readdirSync(dir);
@@ -93,7 +101,7 @@ export function writeSessionConnection(record, options = {}) {
     const file = sessionConnectionPath(record.sessionId, home);
     const dir = sessionConnectionDir(home);
     mkdirSync(dir, { recursive: true });
-    pruneStaleConnections(dir, now);
+    pruneStaleSessionFiles(dir, now);
     const full = {
         schemaVersion: SESSION_CONNECTION_SCHEMA_VERSION,
         ...record,
@@ -196,7 +204,7 @@ export function invalidRecordReason(value) {
     const source = r.source;
     if (typeof source !== "object" || source === null)
         return "source is not an object";
-    if (source.kind === "file")
+    if (source.kind === "session-key")
         return typeof source.path === "string" && source.path !== "" ? null : "source.path is not a path";
     if (source.kind === "env")
         return typeof source.name === "string" && source.name !== "" ? null : "source.name is not a variable name";

package/dist/session-key.js

@@ -0,0 +1,111 @@
+/**
+ * DX-4390 (PLAN-17 section 96) - the dashboard key a user approved for ONE agent session, kept on
+ * this machine so the session's MCP server and its event bridge both authenticate with it.
+ *
+ * One file per dashboard and per session:
+ * `~/.config/danxbot/session-keys/<sha12(dashboard url)>/<session id>.json`, mode 0600. The key
+ * lapses on the dashboard after 24 hours without use (it slides on every authenticated call), so
+ * this file is a cache of a revocable, short-lived credential, not a standing secret: a 401 on it
+ * deletes it (`SessionAccess`), and files nothing has touched for a week are pruned on the next
+ * write (`pruneStaleSessionFiles`, shared with the session connection record). A live server
+ * rewrites its file at least hourly (`SessionAccess.guard`), so only an unused session's file
+ * ages out. The session id picks the file but never selects a key on the dashboard.
+ *
+ * Written write-then-rename, like the session connection record, so a bridge reading
+ * concurrently sees the old file or the new one, never a torn one.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { assertSessionIdSegment, pruneStaleSessionFiles } from "./session-connection.js";
+/** One canonical shape (CLAUDE.md Core Principle 1): a file of any other version is refused. */
+export const SESSION_KEY_SCHEMA_VERSION = 1;
+const dashboardHash = (dashboardUrl) => createHash("sha256").update(dashboardUrl.replace(/\/+$/, "")).digest("hex").slice(0, 12);
+export function sessionKeyRoot(home = homedir()) {
+    return join(home, ".config", "danxbot", "session-keys");
+}
+export function sessionKeyDir(dashboardUrl, home = homedir()) {
+    return join(sessionKeyRoot(home), dashboardHash(dashboardUrl));
+}
+export function sessionKeyPath(dashboardUrl, sessionId, home = homedir()) {
+    assertSessionIdSegment(sessionId);
+    return join(sessionKeyDir(dashboardUrl, home), `${sessionId}.json`);
+}
+/** Store a freshly claimed key for this session; returns the file's path. */
+export function writeSessionKey(input, options = {}) {
+    const home = options.home ?? homedir();
+    const now = options.now ?? Date.now();
+    const file = sessionKeyPath(input.dashboardUrl, input.sessionId, home);
+    const dir = sessionKeyDir(input.dashboardUrl, home);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    pruneStaleSessionFiles(dir, now);
+    const record = {
+        schemaVersion: SESSION_KEY_SCHEMA_VERSION,
+        dashboardUrl: input.dashboardUrl.replace(/\/+$/, ""),
+        sessionId: input.sessionId,
+        apiKey: input.apiKey,
+        savedAt: new Date(now).toISOString(),
+    };
+    const tmp = `${file}.${process.pid}.${now}.tmp`;
+    writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+    renameSync(tmp, file);
+    return file;
+}
+/** Why a key file cannot be used, or `null`. */
+function invalidKeyReason(value) {
+    if (typeof value !== "object" || value === null)
+        return "it is not an object";
+    const r = value;
+    if (r.schemaVersion !== SESSION_KEY_SCHEMA_VERSION) {
+        return `schemaVersion is ${JSON.stringify(r.schemaVersion)}, not ${SESSION_KEY_SCHEMA_VERSION}`;
+    }
+    for (const field of ["dashboardUrl", "sessionId", "apiKey", "savedAt"]) {
+        if (typeof r[field] !== "string" || r[field] === "")
+            return `${field} is not a non-empty string`;
+    }
+    return null;
+}
+/** The thrown shape of an absent file, so a caller can tell "no key" from "a key I cannot read". */
+export class SessionKeyAbsentError extends Error {
+    constructor(path) {
+        super(`there is no session key at ${path}`);
+        this.name = "SessionKeyAbsentError";
+    }
+}
+/** A key file that is there but unreadable or of another shape. */
+export class SessionKeyUnusableError extends Error {
+    path;
+    constructor(path, why) {
+        super(`the session key file ${path} is unusable: ${why}`);
+        this.path = path;
+        this.name = "SessionKeyUnusableError";
+    }
+}
+/** The key in `path`. Absent and unusable are different errors: only the first means "never signed in". */
+export function readSessionKeyFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            throw new SessionKeyAbsentError(path);
+        throw new SessionKeyUnusableError(path, err.message);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new SessionKeyUnusableError(path, `not JSON (${err.message})`);
+    }
+    const invalid = invalidKeyReason(parsed);
+    if (invalid !== null)
+        throw new SessionKeyUnusableError(path, invalid);
+    return parsed.apiKey;
+}
+/** Delete a key file (a revoked or lapsed key). Never throws for an absent file. */
+export function deleteSessionKey(path) {
+    rmSync(path, { force: true });
+}

package/package.json

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