@thehammer/danx-dashboard-mcp 0.1.172 → 0.1.173

package/dist/background-work.js

@@ -1,5 +1,5 @@
 /**
- * `danx-dashboard-mcp background-work <count|clear>` — the ONE-SHOT client of
+ * `danx-dashboard-mcp background-work <count|clear> <event-at>` — the ONE-SHOT client of
  * `PUT /api/plan-sessions/me/background-work` (DX-3367).
  *
  * WHO RUNS IT. The danxbot Claude Code plugin's `Stop` / `SubagentStop` /
@@ -29,10 +29,15 @@
  *     no-op — `{"ok":false,"reason":"no_connection_record"}` — the plugin
  *     hook simply does not forward anything further in this case, exactly
  *     what "no-op when the session isn't plan-connected" means in practice;
- *   - on success, `{"ok":true,"count":<number|null>}` echoes the `count`
- *     that was SUBMITTED for storage, not a re-read of the row — see
- *     `recordBackgroundWork`'s own doc (`db/plan-session-background-work.ts`)
- *     for why a plain no-op write is indistinguishable from a real one here;
+ *   - on success, `{"ok":true,"count":<number|null>,"applied":<boolean>}`
+ *     echoes the SUBMITTED `count`; `applied` is the server's answer to
+ *     whether it was stored (DX-3676: `false` for an out-of-order report
+ *     older than the one already on file — the caller must not treat it as
+ *     the dashboard's current count);
+ *   - DX-3676 — `<event-at>` is the ISO-8601 UTC time the reporting HOOK
+ *     fired, captured by the caller, never this process's own clock: the
+ *     hooks are async and can finish out of order, and the server orders
+ *     reports by this time;
  *   - human-readable diagnostics go to stderr only, never stdout.
  *
  * THE CREDENTIAL — the SAME resolver `bridge` and `plan-state` use, via
@@ -56,7 +61,7 @@ export const BACKGROUND_WORK_SUBCOMMAND = "background-work";
 export const BACKGROUND_WORK_PATH = "/api/plan-sessions/me/background-work";
 /** How long this one-shot call may take before it counts as a timeout. */
 export const BACKGROUND_WORK_REQUEST_TIMEOUT_MS = 5_000;
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BACKGROUND_WORK_SUBCOMMAND} <non-negative-integer|clear>`;
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BACKGROUND_WORK_SUBCOMMAND} <non-negative-integer|clear> <event-at ISO-8601 UTC>`;
 /**
  * Parse the ONE positional argument: `clear`, or a non-negative integer
  * string. Anything else is a usage error — never guessed or floored.
@@ -68,6 +73,15 @@ export function parseCountArg(raw) {
         return { error: `count must be "clear" or a non-negative integer, got "${raw}"` };
     return Number.parseInt(raw, 10);
 }
+/** DX-3676 — an ISO-8601 UTC instant, as `Date#toISOString` writes it (the server accepts exactly this). */
+const ISO_UTC_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+/** Parse the event-time argument (DX-3676). Never substituted with this process's clock. */
+export function parseEventAtArg(raw) {
+    if (!ISO_UTC_INSTANT.test(raw) || Number.isNaN(Date.parse(raw))) {
+        return { error: `event-at must be an ISO-8601 UTC timestamp (e.g. 2026-09-30T00:00:00.000Z), got "${raw}"` };
+    }
+    return raw;
+}
 /**
  * One authenticated PUT, with a hard timeout, classified into the output
  * shape this subcommand always prints — never a throw, never a non-2xx
@@ -81,8 +95,8 @@ export function parseCountArg(raw) {
  * (no `409 session_not_connected` equivalent), so status alone decides
  * whether a body read is even attempted.
  */
-export async function putBackgroundWork(options, count, deps) {
-    const sent = await sendSessionRequest(options, BACKGROUND_WORK_PATH, { method: "PUT", body: JSON.stringify({ count }) }, deps);
+export async function putBackgroundWork(options, report, deps) {
+    const sent = await sendSessionRequest(options, BACKGROUND_WORK_PATH, { method: "PUT", body: JSON.stringify({ count: report.count, eventAt: report.eventAt }) }, deps);
     if ("reason" in sent)
         return sent;
     const { status, text } = sent;
@@ -99,10 +113,12 @@ export async function putBackgroundWork(options, count, deps) {
     if (typeof body !== "object" ||
         body === null ||
         !("count" in body) ||
-        (body.count !== null && typeof body.count !== "number")) {
+        (body.count !== null && typeof body.count !== "number") ||
+        typeof body.applied !== "boolean") {
         return { ok: false, reason: "bad_response" };
     }
-    return { ok: true, count: body.count };
+    const shaped = body;
+    return { ok: true, count: shaped.count, applied: shaped.applied };
 }
 /** The bin's `background-work` subcommand, wired to the real process. Always resolves to exit code 0. */
 export async function runBackgroundWorkCommand(argv, env = process.env, 
@@ -111,7 +127,7 @@ resolveFrom = {}) {
     const write = (output) => {
         process.stdout.write(`${JSON.stringify(output)}\n`);
     };
-    if (argv.length !== 1) {
+    if (argv.length !== 2) {
         write({ ok: false, reason: "usage" });
         process.stderr.write(`${USAGE}\n`);
         return 0;
@@ -123,6 +139,12 @@ resolveFrom = {}) {
         return 0;
     }
     const count = parsed;
+    const eventAt = parseEventAtArg(argv[1]);
+    if (typeof eventAt === "object") {
+        write({ ok: false, reason: "usage" });
+        process.stderr.write(`${eventAt.error}\n${USAGE}\n`);
+        return 0;
+    }
     const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
     if (!resolved.ok) {
         // A session that never `plan_connect`-ed has no connection record — this
@@ -132,7 +154,7 @@ resolveFrom = {}) {
         process.stderr.write(`${resolved.detail}\n`);
         return 0;
     }
-    const output = await putBackgroundWork(resolved.options, count, {
+    const output = await putBackgroundWork(resolved.options, { count, eventAt }, {
         fetch: (input, init) => fetch(input, init),
         requestTimeoutMs: BACKGROUND_WORK_REQUEST_TIMEOUT_MS,
     });

package/dist/listen.js

@@ -284,6 +284,11 @@ function cardList(cards) {
  * this signal cannot support. See `evaluateIdleNudge`'s own doc comment
  * (`src/issues/db/session-idle-nudge.ts`) for why a sub-agent-awareness
  * special case was rejected instead of this wording fix.
+ *
+ * DX-3676 — every named card clears every dispatch gate, so if the session
+ * still cannot work one, the card's recorded state is wrong (DX-3400 sat in
+ * ToDo with its real blocker only in a comment). The line therefore ends by
+ * naming each state-correcting move, which is also what stops the nudge.
  */
 export function formatNudgeLine(event) {
     const invalid = invalidNudgeReason(event);
@@ -294,7 +299,9 @@ export function formatNudgeLine(event) {
         parts.push(`startable: ${cardList(event.startable)}`);
     if (event.held.length > 0)
         parts.push(`held: ${cardList(event.held)}`);
-    return oneLine(`${LINE_PREFIX} this session has not made an MCP call in ${event.idleMinutes}m — ${parts.join("; ")}`);
+    return oneLine(`${LINE_PREFIX} this session has not made an MCP call in ${event.idleMinutes}m — ${parts.join("; ")}. ` +
+        "Work these cards; any you cannot work, update to its true state: open a problem, add depends_on or " +
+        "conflict_on, block it with the real reason, or rollback_pickup.");
 }
 /**
  * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and

package/package.json

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