@thehammer/danx-dashboard-mcp 0.1.334 → 0.1.336

package/dist/heartbeat-reporter.js

@@ -13,6 +13,11 @@ import { DIGEST_PREFIX } from "./digest-hold.js";
 import { HEARTBEAT_SILENT_FAILURE_THRESHOLD, HEARTBEAT_SUSTAINED_OUTAGE_MS, sendHeartbeat, } from "./session-stream.js";
 import { OperatorSessionStats } from "./session-stats.js";
 import { TranscriptTitleReader } from "./session-title.js";
+/** DX-5415: how long a stop waits for the final settle (drain + one stats flush) before giving up; shutdown must stay bounded. */
+export const FINAL_SETTLE_BOUND_MS = 10_000;
+function settleBound() {
+    return AbortSignal.timeout(FINAL_SETTLE_BOUND_MS);
+}
 export class HeartbeatReporter {
     deps;
     sessionStats;
@@ -42,21 +47,38 @@ export class HeartbeatReporter {
      */
     useTranscript(path) {
         if (path === undefined || path === this.transcriptPath)
-            return;
-        this.sessionStats.stop();
+            return null;
+        const previous = this.sessionStats;
         this.transcriptPath = path;
         this.sessionStats = new OperatorSessionStats(path, this.deps.makeStatsWatcher);
         this.titleReader = new TranscriptTitleReader(path);
         this.dashboardTitle = undefined;
         this.lastTitleError = null;
+        // DX-5415: the old transcript's held finals are stored before this returns; the swap above is synchronous so a second call sees the new path.
+        return previous.stop(this.send(undefined), settleBound());
     }
     /** A fresh connect cycle earns a clean slate for the silent-failure count. */
     resetFailureStreak() {
         this.failureStreak = 0;
     }
-    /** Stop tailing the transcript. Idempotent. */
-    stop() {
-        this.sessionStats.stop();
+    /** DX-5415: settle the collector's held sub-agent finals (bounded), then stop tailing the transcript. Idempotent. */
+    async stop() {
+        await this.sessionStats.stop(this.send(undefined), settleBound());
+    }
+    /** One heartbeat as the reporter sends it: the carried answer's title and revocation are applied here. */
+    send(title) {
+        return async (stats) => {
+            const answer = await sendHeartbeat(this.deps.auth(), this.deps.http, this.deps.connection(), stats, title);
+            if (answer.landed)
+                this.dashboardTitle = answer.title ?? undefined;
+            // DX-4418 - a person revoked this session's key: tell the session to stop, at once and only once. Its next
+            // dashboard call says the same.
+            if (answer.revocation !== null && !this.revocationAnnounced) {
+                this.revocationAnnounced = true;
+                this.deps.announce(keyRevokedHalt(answer.revocation, false), "key_revoked");
+            }
+            return answer;
+        };
     }
     titleToReport() {
         if (this.titleReader === null || this.dashboardTitle === undefined)
@@ -80,18 +102,7 @@ export class HeartbeatReporter {
     tick() {
         const title = this.titleToReport();
         void this.sessionStats
-            .tick(async (stats) => {
-            const answer = await sendHeartbeat(this.deps.auth(), this.deps.http, this.deps.connection(), stats, title);
-            if (answer.landed)
-                this.dashboardTitle = answer.title ?? undefined;
-            // DX-4418 - a person revoked this session's key: tell the session to stop, at once and only once. Its next
-            // dashboard call says the same.
-            if (answer.revocation !== null && !this.revocationAnnounced) {
-                this.revocationAnnounced = true;
-                this.deps.announce(keyRevokedHalt(answer.revocation, false), "key_revoked");
-            }
-            return answer;
-        })
+            .tick(this.send(title))
             .then((landed) => {
             const now = this.deps.now();
             if (landed) {

package/dist/index.js

@@ -866,9 +866,11 @@ async function main() {
     stopWhenSessionEnds({
         server: server.server,
         stdin: process.stdin,
+        signals: process,
+        exit: (code) => process.exit(code),
         stop: () => {
             permissionWatch.stop();
-            planEventRelay.close();
+            return planEventRelay.close();
         },
     });
     const transport = new StdioServerTransport();

package/dist/plan-events-relay.js

@@ -115,6 +115,10 @@ export class PlanEventRelay {
     lastActivityAt = 0;
     heartbeat = null;
     reporter = null;
+    /** DX-5415: the stop of the last suspended reporter (its final settle); resolved when none is running. */
+    settling = null;
+    /** DX-5415: set by `close()` (the server's shutdown) and never cleared: a call paused across the close, or made after it, answers empty and starts nothing. */
+    closed = false;
     digest = new DigestHold((event) => this.accept(event));
     constructor(deps) {
         this.deps = deps;
@@ -124,8 +128,14 @@ export class PlanEventRelay {
         // Parsed first: a cursor this server did not issue is refused before it changes anything.
         const cursor = args.cursor === null ? null : parseCursor(args.cursor);
         // DX-4233: a request already cancelled (a plugin reload) touches nothing and starts nothing.
-        if (signal?.aborted)
+        if (signal?.aborted || this.closed)
             return { events: [] };
+        // DX-5415: a suspend still storing the old collector's held finals ends before this call starts a new one (bounded inside).
+        if (this.settling !== null) {
+            await this.settling;
+            if (signal?.aborted || this.closed)
+                return { events: [] };
+        }
         // 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).
@@ -144,7 +154,13 @@ export class PlanEventRelay {
             this.buffer = this.buffer.map((r) => ({ ...r, recent: boundedIds([...cursor.ids, ...r.recent]) }));
         }
         this.touch();
-        this.ensureReporter(args.transcriptPath);
+        const switching = this.ensureReporter(args.transcriptPath);
+        if (switching !== null) {
+            await switching;
+            // DX-5415 / DX-4233: the pause let a close() or a cancel through; a close already let go of the stream, heartbeat and reporter, so none is started again.
+            if (signal?.aborted || this.closed)
+                return { events: [] };
+        }
         this.buffer = this.buffer.filter((r) => !acknowledged(r.seq, cursor));
         if (this.pendingStop !== null) {
             const stopped = this.pendingStop;
@@ -175,8 +191,9 @@ export class PlanEventRelay {
     }
     /** Stop everything: the pending call, the stream, the heartbeat, the transcript tailer. For the server's shutdown. */
     close() {
+        this.closed = true;
         this.supersedeWaiter();
-        this.suspend();
+        return this.suspend();
     }
     // ---------------------------------------------------------------------------------------------------------------- calls
     finishCall(waiter, answer) {
@@ -267,10 +284,8 @@ export class PlanEventRelay {
     }
     /** Creates the heartbeat reporter on the first call; a later call's transcript path (a resumed session) is handed to it. */
     ensureReporter(transcriptPath) {
-        if (this.reporter !== null) {
-            this.reporter.useTranscript(transcriptPath);
-            return;
-        }
+        if (this.reporter !== null)
+            return this.reporter.useTranscript(transcriptPath);
         this.reporter = new HeartbeatReporter({
             auth: () => {
                 const auth = this.deps.auth();
@@ -287,6 +302,7 @@ export class PlanEventRelay {
             announce: (text, source) => this.digest.route({ type: "event", id: null, text, origin: null, scope: "session", urgent: isUrgent({ source }) }),
             forceReconnect: () => this.run?.forceReconnect?.(),
         }, transcriptPath ?? null);
+        return null;
     }
     /** Mark the relay in use and make sure the heartbeat is scheduled. */
     touch() {
@@ -298,7 +314,7 @@ export class PlanEventRelay {
         if (this.waiter === null && this.deps.now() - this.lastActivityAt > HEARTBEAT_ACTIVITY_WINDOW_MS) {
             // Nobody is reading this session's events any more: stop heartbeating (the dashboard then reads the listener not
             // healthy) and let go of the stream. The next call starts it again from its cursor; the dashboard replays what it missed.
-            this.suspend();
+            void this.suspend();
             return;
         }
         const auth = this.deps.auth();
@@ -328,7 +344,15 @@ export class PlanEventRelay {
         this.heartbeat = null;
         this.run?.abort.abort();
         this.run = null;
-        this.reporter?.stop();
+        // DX-5415: the reporter's stop settles its collector's held sub-agent finals first; callers that can wait (shutdown, the next call) do.
+        const stopping = this.reporter?.stop() ?? null;
+        if (stopping !== null) {
+            const settling = Promise.all([this.settling, stopping]).then(() => {
+                if (this.settling === settling)
+                    this.settling = null;
+            });
+            this.settling = settling;
+        }
         this.reporter = null;
         this.digest.reset();
         this.dropPlanScoped();
@@ -339,6 +363,7 @@ export class PlanEventRelay {
         this.connectionState = "reconnecting";
         this.stoppedReason = null;
         this.lastInventoryError = null;
+        return this.settling ?? Promise.resolve();
     }
     // ------------------------------------------------------------------------------------------------- the mint / stream loop
     start(cursor) {

package/dist/session-stats.js

@@ -85,19 +85,32 @@ export class OperatorSessionStats {
                 this.begin(answer.stats);
             return answer.landed;
         }
-        let carried = false;
-        let landed = true;
-        let planless = false;
-        await this.usage.flush({
+        const { carried, landed, planless } = await this.flushVia(send);
+        if (planless) {
+            // DX-4892: re-queueing would resend this batch on every tick for as long as the session stays planless. Drop the collector instead:
+            // the plain heartbeats that follow start collection again from the stored cursors once an answer carries stats (the session is bound).
+            this.watcher?.stop();
+            this.watcher = null;
+            this.usage = newCollector();
+            return landed;
+        }
+        if (carried)
+            return landed;
+        return (await send(undefined)).landed;
+    }
+    /** One collector flush carried by `send`; a refused or unlanded batch throws inside the collector, which re-queues it. */
+    async flushVia(send) {
+        const outcome = { carried: false, landed: true, planless: false };
+        const flushed = await this.usage.flush({
             applyStats: async (_dispatchId, payload) => {
-                carried = true;
+                outcome.carried = true;
                 const answer = await send(payload);
                 if (!answer.landed) {
-                    landed = false;
+                    outcome.landed = false;
                     throw new Error("stats heartbeat did not reach the dashboard");
                 }
                 if (answer.statsNotStored === "no_plan") {
-                    planless = true;
+                    outcome.planless = true;
                     throw new Error("stats heartbeat refused: the session is on no plan, so the dashboard stores no stats for it");
                 }
                 if (answer.stats === null) {
@@ -106,22 +119,52 @@ export class OperatorSessionStats {
                 return answer.stats;
             },
         }, OPERATOR_DISPATCH_REF);
-        if (planless) {
-            // DX-4892: re-queueing would resend this batch on every tick for as long as the session stays planless. Drop the collector instead:
-            // the plain heartbeats that follow start collection again from the stored cursors once an answer carries stats (the session is bound).
-            this.watcher?.stop();
-            this.watcher = null;
-            this.usage = newCollector();
-            return landed;
-        }
-        if (carried)
-            return landed;
-        return (await send(undefined)).landed;
+        return { ...outcome, outcome: flushed };
     }
-    /** Stop tailing. Idempotent; a stopped collector never starts again. */
-    stop() {
+    /**
+     * Stop tailing. Idempotent; a stopped collector never starts again.
+     *
+     * DX-5415: a sub-agent's final report is held until its end signal is read, and confirmed only by a LATER poll (DX-5413), so a bare
+     * `watcher.stop()` lost any final still held or whose signal was read in the last poll. A collecting watcher is therefore settled first:
+     * `drainFinal()`, then one flush carried by `send`, and only then stopped. The bound only stops WAITING: when it fires, `stop` returns
+     * and stops the watcher, but the drain and the flush already under way keep running to their own end (each dashboard request is
+     * bounded by its own request timeout), so shutdown never hangs and a cut-off settle can still land late. A drain that throws, a flush
+     * that fails or is refused, or a settle cut off costs only what it had not yet delivered, said on stderr.
+     */
+    async stop(send, bound) {
+        if (this.stopped)
+            return;
         this.stopped = true;
-        this.watcher?.stop();
+        const watcher = this.watcher;
+        if (watcher === null)
+            return;
+        const cutOff = new Promise((resolve) => {
+            if (bound.aborted)
+                resolve("cut");
+            else
+                bound.addEventListener("abort", () => resolve("cut"), { once: true });
+        });
+        try {
+            const settled = (async () => {
+                await watcher.drainFinal();
+                // DX-5415: a failed or refused flush re-queues nothing for a collector that is stopping, so it says what it costs.
+                const flushed = (await this.flushVia(send)).outcome;
+                if (flushed !== "ok")
+                    process.stderr.write(`operator session stats: the final flush was ${flushed}; held sub-agent finals may be lost
+`);
+                return "settled";
+            })();
+            settled.catch(() => undefined); // a cut-off settle's late failure is already reported by the race below
+            if ((await Promise.race([settled, cutOff])) === "cut") {
+                process.stderr.write("operator session stats: the final settle was cut off by its bound; held sub-agent finals may be lost\n");
+            }
+        }
+        catch (err) {
+            process.stderr.write(`operator session stats: final settle failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        finally {
+            watcher.stop();
+        }
     }
     begin(stored) {
         // `this.watcher !== null`: the relay fires `tick` without awaiting it, so

package/dist/shutdown.js

@@ -2,11 +2,24 @@
  * DX-4523 / DX-4233 - what the server lets go of when its session ends: the permission watch's open stream and the plan event
  * relay (its pending call, stream, heartbeat and tailer), so nothing keeps the process alive after the client is gone.
  *
- * Two triggers, both needed: the transport's `onclose` (an orderly close of the connection) and the end of stdin. The SDK's stdio
- * transport does not watch stdin for its end (only a transport `close()` reaches `onclose`), so a client that simply exits
- * would leave the process running without the second one.
+ * Three triggers, all needed: the transport's `onclose` (an orderly close of the connection), the end of stdin (the SDK's stdio
+ * transport does not watch stdin for its end, so a client that simply exits would leave the process running without it), and a
+ * SIGTERM / SIGINT.
+ *
+ * DX-5415: `stop` returns the relay's bounded final settle (a sub-agent's held final report is stored before the collector stops).
+ * The first two triggers leave the process to end on its own once nothing keeps it alive, so the settle completes. A signal would
+ * kill it mid-settle, so its handler awaits `stop` and only then exits. `once`: a second signal finds no listener and takes the
+ * default action, the way out when the settle is slow.
  */
 export function stopWhenSessionEnds(wiring) {
     wiring.server.onclose = wiring.stop;
     wiring.stdin.once("end", wiring.stop);
+    const exitAfterStop = () => {
+        void Promise.resolve(wiring.stop()).then(() => wiring.exit(0), (err) => {
+            process.stderr.write(`danx-dashboard-mcp: shutdown failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            wiring.exit(1);
+        });
+    };
+    wiring.signals.once("SIGTERM", exitAfterStop);
+    wiring.signals.once("SIGINT", exitAfterStop);
 }

package/package.json

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