@thehammer/danx-dashboard-mcp 0.1.224 → 0.1.225

package/README.md

@@ -20,7 +20,7 @@ BOARD-ONLY (DX-1171): board is the first-level concept; repo is DERIVED from boa
 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 401 on the stored key** deletes the file and returns the sign-in halt (in `plan_connect`: a new request in the same call). That is a key that lapsed. A key a PERSON revoked is answered `401 key_revoked` (DX-4418): the key file is deleted and EVERY dashboard tool, `plan_connect` included, returns one stop halt (who revoked it and when; commit work in progress and end; a dispatched agent ends with `danxbot_complete`), for the rest of the process. No access request is made. `danxbot_complete` and the other worker lifecycle tools do not use the dashboard key, so a dispatched agent can still end. The session's event bridge ends with the stop reason `key_revoked` the same way. **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)

package/dist/bridge.js

@@ -69,6 +69,7 @@
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { errorCodeOf } from "./json-body.js";
+import { keyRevocationOf, keyRevokedHalt } from "./key-revoked-halt.js";
 import { oneLine } from "./one-line.js";
 import { credentialFingerprint, describeCredentialSource, readCredential, } from "./credential.js";
 import { readSessionConnection, sessionConnectionPath } from "./session-connection.js";
@@ -220,7 +221,9 @@ export const STOP_FIXES = {
     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: "the dashboard no longer accepts this session's key (revoked, or lapsed after a day unused): call plan_connect again to request access",
+    unauthorized: "the dashboard no longer accepts this session's key (it lapsed after a day unused): call plan_connect again to request access",
+    key_revoked: "stop all work now, commit your work in progress and end this session: the person who owns this session's access revoked it; " +
+        "do not call plan_connect or request access again",
     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
@@ -439,6 +442,12 @@ export async function mintTicket(options, deps) {
     if (status === 409 && errorCodeOf(body) === "session_is_worker") {
         return { kind: "terminal", reason: "session_is_worker", detail: "this session id belongs to a worker dispatch, not an operator plan session" };
     }
+    // DX-4418 - a key a person revoked is not a lapsed one: the detail IS the stop halt (who revoked it, what to do), so the record
+    // the plugin relays to the session says it in full.
+    const revocation = keyRevocationOf({ ok: false, status, body });
+    if (revocation !== null) {
+        return { kind: "terminal", reason: "key_revoked", detail: keyRevokedHalt(revocation, false) };
+    }
     if (status === 401 || status === 403) {
         return { kind: "terminal", reason: "unauthorized", detail: `ticket mint HTTP ${status} ${oneLine(text, 300)}` };
     }
@@ -545,6 +554,8 @@ const EXIT_NEVER_RESTART_LIST = [
     "superseded",
     "replaced",
     "session_is_worker",
+    // DX-4418 - a person revoked the key: the session stops for good, nothing retries.
+    "key_revoked",
 ];
 const EXIT_NEVER_RESTART = new Set(EXIT_NEVER_RESTART_LIST);
 const DEGRADE_NO_HEARTBEAT_LIST = ["credential_unavailable", "credential_mismatch"];
@@ -557,8 +568,9 @@ export function degradePolicyFor(reason) {
     return "degrade-server-fixable";
 }
 /**
- * One heartbeat POST. NEVER throws and NEVER stops the bridge on failure
- * (card AC1 — "a failed heartbeat never stops the bridge"): `request()`
+ * One heartbeat POST. Never throws on a failure of the request itself and NEVER stops the bridge on one
+ * (the one throw is a contract breach: a `key_revoked` answer that does not say who revoked the key, DX-4418; `heartbeatTick`'s
+ * `.catch` keeps it from taking the bridge down) (card AC1 — "a failed heartbeat never stops the bridge"): `request()`
  * itself already classifies every network/timeout/5xx failure as
  * `{kind:"transient"}` rather than throwing, and a 401/403 (a revoked
  * credential) simply comes back as an ordinary non-2xx answer this function
@@ -592,7 +604,7 @@ async function sendHeartbeat(options, deps, connection, stats) {
     // request never landed at all, which is exactly the signal the silent-
     // failure counter in `runBridge` below needs. Still never throws.
     if (outcome.kind !== "answer")
-        return { landed: false, status: null, stats: null };
+        return { landed: false, status: null, stats: null, revocation: null };
     // DX-2954 — the answer's `stats` (the operator dispatch's stored or
     // just-written totals and cursors) feed the session's stats collector.
     const ok = outcome.status >= 200 && outcome.status < 300;
@@ -610,7 +622,8 @@ async function sendHeartbeat(options, deps, connection, stats) {
         Object.values(statsBody.sourceCursors).every((cursor) => isRecord(cursor) && isClaimState(cursor.claims))
         ? statsBody
         : null;
-    return { landed: true, status: outcome.status, stats: answered };
+    // DX-4418 - the dashboard refuses the beat of a session whose key a person revoked, and says so.
+    return { landed: true, status: outcome.status, stats: answered, revocation: keyRevocationOf({ ok: false, status: outcome.status, body: outcome.body }) };
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -643,6 +656,8 @@ export async function runBridge(options, deps) {
     // `onConnectionAttempt` below; calling it after that attempt has already
     // ended is a harmless no-op.
     let heartbeatFailureStreak = 0;
+    // DX-4418 - the stop notice for a revoked key goes out once; every later beat is refused the same way.
+    let revocationAnnounced = false;
     let forceReconnect = null;
     // DX-2954 — the session's stats ride this same heartbeat. Created ONCE per
     // process, so an in-process re-mint never touches its state.
@@ -657,7 +672,16 @@ export async function runBridge(options, deps) {
     const heartbeatTick = () => {
         if (heartbeatSuppressed)
             return;
-        void sessionStats.tick((stats) => sendHeartbeat(options, deps, connectionNow(), stats)).then((landed) => {
+        void sessionStats.tick(async (stats) => {
+            const answer = await sendHeartbeat(options, deps, connectionNow(), stats);
+            // DX-4418 - a person revoked this session's key: tell the session to stop, at once and only once, as an ordinary event
+            // line (the same delivery the silent-failure notice below uses). Its next dashboard call says the same.
+            if (answer.revocation !== null && !revocationAnnounced) {
+                revocationAnnounced = true;
+                routeEvent({ type: "event", id: null, text: keyRevokedHalt(answer.revocation, false), origin: null });
+            }
+            return answer;
+        }).then((landed) => {
             // DX-3099 — only counts while THIS process still believes it is
             // streaming: that is the exact desync the card found (the client
             // believes it is fine; the dashboard has nothing recent for it). A

package/dist/index.js

@@ -279,6 +279,9 @@ function haltResult(text) {
 function accessReply(ready, note) {
     if (ready.signedIn)
         return jsonResult({ state: "signed_in", ...(note ? { note } : {}) });
+    // DX-4418: a person revoked this session's access: the one stop halt, verbatim, never a request.
+    if (ready.halt !== undefined)
+        return haltResult(ready.halt);
     const answer = note ? { ...ready.answer, note } : ready.answer;
     return ready.isError ? haltResult(JSON.stringify(answer, null, 2)) : jsonResult(answer);
 }
@@ -502,6 +505,10 @@ async (args) => {
         });
     }
     const result = await planConnect(client, { ...args, plan_id: args.plan_id });
+    // DX-4418 — a person revoked this key: the stop halt, and nothing asks again.
+    const revokedHalt = access.refusalHalt(result);
+    if (revokedHalt !== null)
+        return haltResult(revokedHalt);
     // DX-4390 — the dashboard no longer accepts the stored key: drop it and ask again in the same call.
     if (result.status === 401 && access.dropKey()) {
         return accessReply(await access.ensureAccess(args.title), "the dashboard no longer accepted this session's key");

package/dist/key-revoked-halt.js

@@ -0,0 +1,29 @@
+/**
+ * The revocation a `401 key_revoked` result carries, or null for any other result. A `key_revoked` refusal that does not
+ * say who revoked it and when is a contract breach and throws, like a terms refusal without its link.
+ */
+export function keyRevocationOf(result) {
+    if (result.ok || result.status !== 401)
+        return null;
+    const body = result.body;
+    if (body?.error !== "key_revoked")
+        return null;
+    if (typeof body.revokedBy !== "string" || typeof body.revokedAt !== "string") {
+        throw new Error("[danx-dashboard-mcp] a key_revoked refusal carried no revokedBy / revokedAt");
+    }
+    return { revokedBy: body.revokedBy, revokedAt: body.revokedAt };
+}
+/**
+ * The one halt. `dispatched` is a dispatch's own credential: it ends with `danxbot_complete` (a worker tool, which does not
+ * use the revoked key), and the worker records the end as revoked, not as the agent's failure. An operator session ends by
+ * telling the person; it has no tool that ends it.
+ */
+export function keyRevokedHalt(revocation, dispatched) {
+    const ending = dispatched
+        ? 'End this dispatch with danxbot_complete({status: "failed", summary: "<where your work is committed>"}); the worker records it as revoked, not as a failure.'
+        : "Then end this session: tell the person what you committed and stop.";
+    return (`STOP ALL WORK NOW. ${revocation.revokedBy} revoked your access to the danxbot dashboard at ${revocation.revokedAt}.\n\n` +
+        "Commit your work in progress now (commit what you have; do not run agent-finalize.sh and do not merge). " +
+        `${ending}\n\n` +
+        "Do not call plan_connect or any other danxbot dashboard tool again, do not request access again and do not look for another route.");
+}

package/dist/session-access.js

@@ -8,6 +8,11 @@
  *                   (`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.
  *
+ * DX-4418: a fourth state, REVOKED, ends all three for good. The dashboard answers `401 key_revoked` to a key a person revoked
+ * (as opposed to one that lapsed); this object then remembers it for the life of the process, every dashboard tool (and
+ * `plan_connect`) returns the one stop halt (`key-revoked-halt.ts`), and no new access request is made. A session's key file is
+ * deleted; a dispatch's credential is left to its dispatch, but the halt is the same.
+ *
  * 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`
@@ -18,6 +23,7 @@ import { existsSync } from "node:fs";
 import { hostname } from "node:os";
 import { claimAccessRequest, createAccessRequest } from "./access-request.js";
 import { credentialFingerprint } from "./credential.js";
+import { keyRevocationOf, keyRevokedHalt } from "./key-revoked-halt.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. */
@@ -30,8 +36,8 @@ const KEEP_KEY_FILE_EVERY_MS = 60 * 60 * 1000;
 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. " +
+/** DX-4418: the session's key lapsed (a day unused) or the dashboard does not know it; a PERSON's revoke is `keyRevokedHalt` instead. */
+export const KEY_LAPSED_HALT = "The dashboard no longer accepts this session's key (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.";
@@ -48,14 +54,17 @@ 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) => ({
+const notReady = (answer, isError, halt) => ({
     signedIn: false,
     answer,
     isError,
+    ...(halt === undefined ? {} : { halt }),
 });
 export class SessionAccess {
     deps;
     credential;
+    // DX-4418: set once the dashboard says a person revoked the key; never cleared (a restarted server is a new process).
+    revoked = null;
     pending = null;
     // DX-4390: two concurrent signed-out plan_connect calls must not each post a request.
     ensureQueue = Promise.resolve();
@@ -74,11 +83,27 @@ export class SessionAccess {
         deps.setToken(deps.initial?.token ?? "");
     }
     isSignedIn() {
-        return this.credential !== null;
+        return this.credential !== null && this.revoked === null;
+    }
+    /** 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);
+    }
+    /**
+     * DX-4418: a dashboard answer that says a person revoked the key behind it: remembered for good (a session's key file is
+     * deleted, a dispatch's credential is left to its dispatch) and answered as the stop halt. Null for every other answer.
+     */
+    refusalHalt(result) {
+        const revocation = keyRevocationOf(result);
+        if (revocation === null)
+            return null;
+        this.revoked ??= { revocation, dispatched: this.credential?.source.kind === "env" };
+        this.dropKey();
+        return this.revokedHalt();
     }
     /** Where the current credential comes from and its fingerprint, for the bridge's connection record. */
     connection() {
-        if (this.credential === null)
+        if (this.credential === null || this.revoked !== null)
             return null;
         return {
             dashboardUrl: this.deps.dashboardUrl.replace(/\/+$/, ""),
@@ -104,11 +129,17 @@ export class SessionAccess {
      * when the dashboard answers 401 to this session's key.
      */
     async guard(run) {
+        const revokedHalt = this.revokedHalt();
+        if (revokedHalt !== null)
+            return { halt: revokedHalt };
         if (this.credential === null)
             return { halt: SIGN_IN_HALT };
         const result = await run();
+        const refused = this.refusalHalt(result);
+        if (refused !== null)
+            return { halt: refused };
         if (result.status === 401 && this.dropKey())
-            return { halt: REVOKED_HALT };
+            return { halt: KEY_LAPSED_HALT };
         this.keepKeyFile();
         return { result };
     }
@@ -143,6 +174,10 @@ export class SessionAccess {
         return run;
     }
     async ensureAccessNow(title) {
+        // DX-4418: a person revoked this session's access; it never asks again.
+        const revokedHalt = this.revokedHalt();
+        if (revokedHalt !== null)
+            return notReady({ state: "access_revoked", instruction: revokedHalt }, true, revokedHalt);
         if (this.credential !== null)
             return { signedIn: true };
         const sessionId = this.deps.sessionId;

package/package.json

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