@thehammer/danx-dashboard-mcp 0.1.287 → 0.1.289

package/README.md

@@ -63,7 +63,7 @@ Card and plan reads/writes go through `danxbot_api` against the issue/plan route
 
 A program calls this, not a person: the danxbot Claude Code plugin's relay loop, inside the session, calls it over and over on the session's own danx-dashboard MCP server and hands every event it gets to the session. A plan-orchestrator dispatch (a headless session that works one plan) has no plugin relay, so it keeps ONE background waiter sub-agent that loops on this tool until events exist and returns them with the last cursor, and the orchestrator passes that cursor to the next waiter it arms (DX-4667); the `plan-orchestrator` profile alone is granted the tool on a dispatch (it is an opt-in tool). The `bridge` subcommand is gone: no process is spawned, no `npx` cold start, and nothing outlives the session, because the stream lives in the MCP server, which ends with its session.
 
-Input `{plan_id: number, cursor: string | null, timeout_ms: 1000..30000, transcript_path?: string}`. Answer, one of:
+Input `{plan_id: number | null, cursor: string | null, timeout_ms: 1000..30000, transcript_path?: string}`. `plan_id` is `null` for a signed-in session on no plan (DX-4882): its stream still carries the pacing and resume messages of its Claude account, and it receives no plan events. A move between a plan and `null` starts clean like a move between plans: the plan-scoped records of the plan left are dropped, the session-scoped ones kept. Answer, one of:
 
 - `{events: [{cursor: string, text: string, urgent: boolean}]}`: every record the caller has not delivered, in arrival order (empty at the timeout). Each record carries the cursor to store once THAT record is delivered. There is no `id`: the caller compares nothing. `urgent` (DX-4721) is decided in one place by the record's kind (`src/urgent-records.ts`): true for a critical usage-pacing stop and the revoked-key notice, false for everything else (activity events, nudge, resume message, digest, the relay's failure notice, an unreadable line). The caller adds an urgent record to a running turn at once and delivers any other after the turn ends; `urgent` never changes order, seq or acknowledgement. The dashboard writes no operator-stop record yet; when it does, it becomes one more kind in that function.
 - `{stopped: {reason, detail, fix}}`: a terminal outcome (`not_connected`, `plan_archived`, `unauthorized`, `key_revoked`, `mint_refused`, `mint_bad_response`, `session_is_worker`, `superseded`, `replaced`, `revoked`, `refused`, `credential_unavailable`, `relay_failed`). `fix` is the remedy text (`STOP_FIXES`, `src/stop-fixes.ts`). The next call starts from scratch.

package/dist/index.js

@@ -768,7 +768,7 @@ async (args) => {
     await syncToolsAfterSignIn();
     // DX-3997 — a (re)connect starts or re-keys the plugin's relay loop; the next `danxbot_api` must re-read health.
     listenerReminder.invalidate();
-    // DX-2985 — a leave drops the local connection record (the relay's stream ends `not_connected`; a later connect writes a fresh one).
+    // DX-2985 — a leave drops the local connection record (its stream stays open, DX-4882: the relay keeps serving the session's pacing and resume messages; a later connect writes a fresh one).
     if (args.disconnect === true) {
         removeSessionConnectionAfterLeave(result, config.session?.id);
         return jsonResult(result);
@@ -789,20 +789,22 @@ async (args) => {
 });
 // ---------------- plan_events_wait (DX-4233) ----------------
 strictTool("plan_events_wait", 
+// DX-4882 - `plan_id` is null for a signed-in session on no plan: its stream still carries its account's pacing and resume messages.
 // DX-4233 - for the danxbot plugin's relay loop. DX-4667 - and for a background waiter sub-agent of a plan orchestrator, which
 // loops on it until events exist and returns them (and the cursor) to the orchestrator it wakes. It answers `events` (each
 // `{cursor, text, urgent}`; empty after `timeout_ms`), the cursor to send being the last delivered event's, or `stopped` with the remedy
 // to tell the session. General-audience text (DX-4550): nothing here names our own setup.
-"Waits for events on the plan this session is connected to. For a relay or a background waiter that calls it in a loop " +
-    "and hands every event to the session; do not call it for any other reason. `plan_id` is the plan the session is on (a " +
-    "different plan than the last call's starts clean). `cursor` is the `cursor` of the last event delivered, as answered (null " +
+"Waits for events for this session: the events of the plan it is connected to, and the messages about its usage. For a relay " +
+    "or a background waiter that calls it in a loop and hands every event to the session; do not call it for any other reason. " +
+    "`plan_id` is the plan the session is on, or null when it is on no plan (then only the usage messages arrive; a different " +
+    "plan than the last call's, or a move to or from null, starts clean). `cursor` is the `cursor` of the last event delivered, as answered (null " +
     "when none). Answers `{events: [{cursor, text, urgent}]}`, with `events` empty once `timeout_ms` passes, or `{stopped: " +
     "{reason, detail, fix}}` when the stream ended: tell the session the `fix`. An event stays until a later call's " +
     "`cursor` passes it. `urgent` is true for an event the session must hear at once (a critical usage limit, a revoked " +
     "key) and false for every other: deliver an urgent one to the session even while it is working, and any other once its " +
     "current turn ends. Only one wait is pending per session: a newer call ends the older. " +
     "`transcript_path` is the session's transcript file, for its usage and title.", {
-    plan_id: z.number().int().positive().describe("Id of the plan this session is connected to."),
+    plan_id: z.number().int().positive().nullable().describe("Id of the plan this session is connected to, or null when it is on no plan."),
     cursor: z
         .string()
         .nullable()

package/dist/json-body.js

@@ -1,20 +1,9 @@
 /**
  * DX-2920 — the ONE place that reads a JSON body's top-level `.error` string.
  *
- * WHY THIS EXISTS. the stream client (`session-stream.ts`, classifying a mint refusal) and `listen.ts`
- * (classifying a stream admission refusal) both need to answer "what error
- * code did this JSON body carry", and before this card each answered it a
- * different way: the mint code parsed the body directly, `listen.ts` never
- * looked past a flattened, human-readable detail string at all — a caller
- * that wanted to react to a SPECIFIC refusal (the admission-time 409 the
- * mint route also uses) had to regex-scrape that flattened string back apart,
- * a second, fragile source of truth for the same fact. This module is generic
- * — it knows nothing about "session_not_connected" or "stream_ticket_invalid",
- * only that a JSON object may carry a top-level string field named `error` —
- * so it can live in BOTH the domain-aware `session-stream.ts` and the deliberately
- * generic `listen.ts` (whose own docblock states it carries no domain
- * knowledge of the dashboard's specific error shapes) without either one
- * importing the other.
+ * WHY THIS EXISTS. the stream client (`session-stream.ts`, classifying a mint refusal such as `409 session_is_worker`) reads a refusal's
+ * error code from the parsed body, and this is the one place that decides what "carries an error code" means. Generic: it knows no
+ * dashboard error name, only that a JSON object may carry a top-level string field named `error`.
  */
 export function errorCodeOf(body) {
     return typeof body === "object" && body !== null && typeof body.error === "string"

package/dist/listen.js

@@ -16,16 +16,10 @@
  *     DX-4342's `resume` frame (`formatResumeLine`): all are advisory, written fresh by the dashboard's own keep-alive tick,
  *     and never replayed, so they ride this same shape with `id: null` rather
  *     than growing a THIRD output variant.
- *   - `{type:"stopped", reason, detail, refusal?}` — once, last. `reason`
+ *   - `{type:"stopped", reason, detail}` — once, last. `reason`
  *     is the dashboard's own end reason (`superseded`, `replaced`, `revoked`,
  *     `not_connected`), `refused` (the ticket was not admitted), or
- *     `lease_expired` (no healthy connection for the lease). DX-2920 —
- *     `refusal` is populated ONLY for `reason === "refused"`: `{status,
- *     errorCode, body}`, the admission response parsed ONCE here, so a
- *     consumer can recognize a SPECIFIC refusal (the dashboard's own
- *     `409 session_not_connected`, the same shape the mint route uses) by
- *     status + error code rather than re-deriving it from the flattened
- *     `detail` string. A wire `reason` value this build does not recognize (a
+ *     `lease_expired` (no healthy connection for the lease). A wire `reason` value this build does not recognize (a
  *     newer dashboard's reason an older client hasn't shipped yet)
  *     normalizes to `"unknown"` rather than passing the raw string through,
  *     so the closed set stays closed — `fixForStop`'s generic
@@ -48,7 +42,6 @@
  * (`src/issues/db/issue-activity.ts`); this published package cannot import
  * danxbot source.
  */
-import { errorCodeOf } from "./json-body.js";
 import { LINE_PREFIX, oneLine } from "./one-line.js";
 import { pacingRelayLine } from "./pacing-relay.js";
 import { isUrgent } from "./urgent-records.js";
@@ -490,8 +483,8 @@ export async function runListener(options, deps) {
     };
     for (const id of capResumeIds(options.resumeIds))
         remember(id);
-    function stop(reason, detail, code, extra) {
-        deps.write({ type: "stopped", reason, detail, refusal: extra?.refusal });
+    function stop(reason, detail, code) {
+        deps.write({ type: "stopped", reason, detail });
         return code;
     }
     /**
@@ -614,24 +607,7 @@ export async function runListener(options, deps) {
             const response = await deps.fetch(options.streamUrl, { headers, signal: controller.signal });
             if (response.status >= 400 && response.status < 500 && !RETRYABLE_CLIENT_STATUSES.has(response.status)) {
                 const text = await response.text();
-                // DX-2920 — parsed ONCE, here, into a structured outcome a consumer can
-                // classify by status + error code (the relay does, matching a specific
-                // admission refusal such as the dashboard's own `409 session_not_connected`)
-                // rather than re-deriving it from the flattened `detail` string below.
-                let body = null;
-                try {
-                    body = text === "" ? null : JSON.parse(text);
-                }
-                catch {
-                    body = null;
-                }
-                return {
-                    kind: "refused",
-                    status: response.status,
-                    errorCode: errorCodeOf(body),
-                    body,
-                    detail: `HTTP ${response.status} ${oneLine(text, 300)}`,
-                };
+                return { kind: "refused", detail: `HTTP ${response.status} ${oneLine(text, 300)}` };
             }
             if (!response.ok || response.body === null) {
                 await response.body?.cancel();
@@ -682,9 +658,7 @@ export async function runListener(options, deps) {
             return stop(outcome.reason, "the dashboard ended this listener", 1);
         }
         if (outcome.kind === "refused") {
-            return stop("refused", `the dashboard refused the listener ticket: ${outcome.detail}`, 1, {
-                refusal: { status: outcome.status, errorCode: outcome.errorCode, body: outcome.body },
-            });
+            return stop("refused", `the dashboard refused the listener ticket: ${outcome.detail}`, 1);
         }
         if (outcome.detail !== undefined)
             lastDropDetail = outcome.detail;

package/dist/plan-events-relay.js

@@ -30,8 +30,9 @@
  *      THE ACCEPTED GAP: an insert that commits more than that 30 s overlap after the event it follows is missed by a RESTART
  *      resume (the dashboard's own limit); a running relay never misses one. And a burst of more than `CURSOR_IDS_MAX` events
  *      inside the overlap can replay the oldest of them once (a duplicate, never a loss).
- *   3. ONE PLAN. A call names the plan the session is on (`planId`). A plan different from the last call's drops the
- *      PLAN-scoped records buffered or held for the plan it left, so a move starts clean. SESSION-scoped records (pacing, resume
+ *   3. ONE PLAN. A call names the plan the session is on (`planId`), or `null` for a signed-in session on no plan (DX-4882: its stream
+ *      still carries the pacing and resume messages of its account). A plan different from the last call's, to or from `null` included,
+ *      drops the PLAN-scoped records buffered or held for the plan it left, so a move starts clean. SESSION-scoped records (pacing, resume
  *      and the relay's own failure and revoked-key notices: they say nothing about a plan, and the dashboard never replays
  *      them) are kept, here and across the 40 s suspend below. The ids of a dropped record leave the cursors of the records that
  *      stay: delivering a kept record must not claim an event that was dropped undelivered. The stream stays on a move: it
@@ -55,7 +56,7 @@
 import { DigestHold } from "./digest-hold.js";
 import { HeartbeatReporter } from "./heartbeat-reporter.js";
 import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, INITIAL_BACKOFF_MS, MAX_BACKOFF_MS, runListener, } from "./listen.js";
-import { classifyAdmissionRefusal, fetchPlanInventory, HEARTBEAT_INTERVAL_MS, heartbeatConnection, MAX_REFUSED_TICKETS_IN_A_ROW, mintTicket, } from "./session-stream.js";
+import { fetchPlanInventory, HEARTBEAT_INTERVAL_MS, heartbeatConnection, MAX_REFUSED_TICKETS_IN_A_ROW, mintTicket, } from "./session-stream.js";
 import { fixForStop } from "./stop-fixes.js";
 import { isUrgent } from "./urgent-records.js";
 /** The shortest and longest wait one call may ask for; a short ceiling keeps an orphaned waiter's life short. */
@@ -91,7 +92,8 @@ export class PlanEventRelay {
     buffer = [];
     waiter = null;
     run = null;
-    lastPlanId = null;
+    /** The plan the last call named (`null` = a session on no plan); `undefined` before the first call, which has no plan to have moved from. */
+    lastPlanId = undefined;
     /** The last seq given: it continues from a presented cursor and survives a suspend, so a cursor stays valid across the gap. */
     seq = 0;
     /** The dashboard event ids that arrived (or were presented in a cursor), oldest first, bounded: the next record's `recent`. */
@@ -103,6 +105,8 @@ export class PlanEventRelay {
     connectionState = "reconnecting";
     stoppedReason = null;
     lastInventoryError = null;
+    /** DX-4882: whether the connected plan's inventory has been read in this run (a session on no plan has none to read). */
+    inventoryRead = false;
     lastActivityAt = 0;
     heartbeat = null;
     reporter = null;
@@ -120,8 +124,10 @@ export class PlanEventRelay {
         // DX-4233: one wait at a time; the older call answers empty so its caller is never left hanging.
         this.supersedeWaiter();
         // DX-4233: a plan move starts clean (the very first call has no last plan; after a suspend the last plan is still known, and `dropPlanScoped` already ran).
-        if (this.lastPlanId !== null && args.planId !== this.lastPlanId)
+        if (this.lastPlanId !== undefined && args.planId !== this.lastPlanId) {
             this.startClean();
+            this.planMovedInventory(args.planId);
+        }
         this.lastPlanId = args.planId;
         if (cursor !== null) {
             // DX-4233: a fresh relay (a restarted server) continues the caller's sequence and remembers the ids it was handed; a
@@ -224,6 +230,31 @@ export class PlanEventRelay {
         // dropped events belong to a plan the session left, and the dashboard replays only the session's current plan, so nothing
         // legitimate is replayed into the guard; and the gap, which does need them replayed, ends the run, so `start` builds a fresh `seenIds` from the next call's cursor.
     }
+    /** Whether the last call named a plan (not `null` = no plan, not `undefined` = no call yet). */
+    onAPlan() {
+        return typeof this.lastPlanId === "number";
+    }
+    /**
+     * DX-4882: the plan changed, so the inventory read for the old one no longer describes the session. On no plan there is nothing to read (and
+     * nothing to report as unavailable); on a plan, a live run reads it now (a run that is not live reads it when it starts).
+     */
+    planMovedInventory(planId) {
+        this.inventoryRead = false;
+        this.lastInventoryError = null;
+        const run = this.run;
+        const auth = this.deps.auth();
+        if (planId === null || run === null || auth === null)
+            return;
+        void this.readInventory(run, auth, { ...this.deps, signal: run.abort.signal });
+    }
+    /** The inventory is a property of the credential and the plan: read best effort, never a gate; a failed read is reported on the heartbeat (`inventory: unavailable`) and tried again at the next re-mint. */
+    async readInventory(run, auth, http) {
+        const inventory = await fetchPlanInventory(auth, http);
+        if (!this.current(run))
+            return;
+        this.inventoryRead = inventory.kind === "ok";
+        this.lastInventoryError = inventory.kind === "ok" ? null : inventory.detail;
+    }
     /** The session moved to another plan: drop what was buffered or held for the plan it left; session-scoped records stay. */
     startClean() {
         this.dropPlanScoped();
@@ -297,6 +328,7 @@ export class PlanEventRelay {
         // replays its 30 s overlap before the highest of them, so a replayed one is dropped and a never-delivered one is delivered.
         this.seenIds = capResumeIds([...(cursor?.ids ?? []), ...this.buffer.flatMap((r) => r.own)]);
         this.stoppedReason = null;
+        this.inventoryRead = false;
         const run = { abort: new AbortController(), forceReconnect: null };
         this.run = run;
         void this.loop(run).catch((err) => {
@@ -336,7 +368,6 @@ export class PlanEventRelay {
         const http = { ...this.deps, signal: run.abort.signal };
         let backoff = INITIAL_BACKOFF_MS;
         let refusedInRow = 0;
-        let inventoryRead = false;
         for (;;) {
             if (!this.current(run))
                 return;
@@ -356,14 +387,11 @@ export class PlanEventRelay {
                 backoff = Math.min(MAX_BACKOFF_MS, backoff * 2);
                 continue;
             }
-            // The inventory is a property of the credential and the plan: read best effort, never a gate. A failed read is reported
-            // on the heartbeat (`inventory: unavailable`), never silently healthy, and is tried again at the next re-mint.
-            if (!inventoryRead) {
-                const inventory = await fetchPlanInventory(auth, http);
+            // DX-4882: only a session on a plan has an inventory to read.
+            if (!this.inventoryRead && this.onAPlan()) {
+                await this.readInventory(run, auth, http);
                 if (!this.current(run))
                     return;
-                inventoryRead = inventory.kind === "ok";
-                this.lastInventoryError = inventory.kind === "ok" ? null : inventory.detail;
             }
             backoff = INITIAL_BACKOFF_MS;
             const attempt = { stopped: null, emitted: false };
@@ -412,9 +440,6 @@ export class PlanEventRelay {
                 continue;
             }
             if (stopped.reason === "refused") {
-                const classified = classifyAdmissionRefusal(stopped.refusal);
-                if (classified !== null)
-                    return this.terminal(run, classified.reason, classified.detail);
                 const provedHealthy = attempt.emitted || this.deps.now() - startedAt >= HEALTHY_CONNECTION_MS;
                 refusedInRow = provedHealthy ? 1 : refusedInRow + 1;
                 if (refusedInRow >= MAX_REFUSED_TICKETS_IN_A_ROW) {

package/dist/session-stream.js

@@ -133,9 +133,8 @@ export async function mintTicket(options, deps) {
     if (outcome.kind === "transient")
         return outcome;
     const { status, text, body } = outcome;
-    if (status === 409 && errorCodeOf(body) === "session_not_connected") {
-        return { kind: "terminal", reason: "not_connected", detail: "the session is not connected to a plan" };
-    }
+    // DX-4882: a session on no plan is minted a ticket like any other (its stream carries its account's pacing and resume messages), so
+    // `409 session_not_connected` is no longer an answer the mint gives.
     // DX-3028 (AC2) — matched BEFORE the generic mint_refused fallback below,
     // which every other 409 falls into: this session id belongs to a worker
     // dispatch (`SessionIsWorkerError`, the same shape the heartbeat route
@@ -219,28 +218,6 @@ export async function fetchPlanInventory(options, deps) {
     const b = body;
     return { kind: "ok", boards: b.boards, cardCount: b.card_count };
 }
-/**
- * DX-2920 — a stream admission refusal (`listen.ts`'s STRUCTURED `refused`
- * outcome — `{status, errorCode, body}`, parsed once in `connectOnce`) whose
- * shape matches one the mint route already gives its OWN name to: `409
- * session_not_connected`, the SAME shape the mint route uses for "no plan
- * connected" (`plan-session-stream.ts`, DX-2863 review finding M2). A session
- * with no plan connected is the identical terminal state whether the
- * dashboard says so at mint or at the stream's own admission check, and the
- * session should see ONE remedy either way.
- *
- * Classifies by STATUS + ERROR CODE, never by re-deriving them from the
- * flattened `detail` string — the second-source-of-truth shape this card's fix
- * round closed (the regex-based `isSessionNotConnectedRefusal` it replaced).
- */
-export function classifyAdmissionRefusal(refusal) {
-    if (refusal === undefined)
-        return null;
-    if (refusal.status === 409 && refusal.errorCode === "session_not_connected") {
-        return { reason: "not_connected", detail: "the session is not connected to a plan" };
-    }
-    return null;
-}
 /**
  * The one real `scheduleInterval`: a `setInterval` and its canceler, for the relay's heartbeat. Unref'd: a heartbeat never keeps
  * the MCP server alive after its session ended.

package/dist/stop-fixes.js

@@ -24,7 +24,7 @@ export const STOP_FIXES = {
     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_refused: "check that this session is signed in to 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 this one (replaced): THIS listener is ending
     // because the session is already served elsewhere, not because anything is broken.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.287",
+  "version": "0.1.289",
   "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, request_permission, attach_file, and danxbot_slack_reply) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",