@thehammer/danx-dashboard-mcp 0.1.172 → 0.1.175

package/dist/background-work.js

@@ -1,12 +1,12 @@
 /**
- * `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` /
  * `SessionStart` / `StopFailure` hooks (`danxbot/hooks/hooks.json` in
  * claude-plugins), via the SAME `npx -y @thehammer/danx-dashboard-mcp`
- * MECHANISM the plugin already uses for `bridge` and `plan-state` — no
- * separate install, no deep import of this package's `dist/` internals.
+ * MECHANISM the plugin already uses for `bridge` — no separate install, no
+ * deep import of this package's `dist/` internals.
  * DX-3367 fix-up — that does NOT mean the SAME PINNED VERSION: `npx -y
  * <pkg>` resolves whatever version string that ONE hook's own invocation
  * names, and this plugin's hooks pin each call independently (verified
@@ -18,9 +18,8 @@
  * sending `clear` on `SessionStart`/`StopFailure`); this module only
  * delivers the report.
  *
- * THE CONTRACT, mirroring `plan-state.ts`'s (binding the same way, so a
- * future plugin build against this module can trust it without re-reading
- * this file):
+ * THE CONTRACT (binding, so a future plugin build against this module can
+ * trust it without re-reading this file):
  *   - print EXACTLY ONE JSON line on stdout, and ALWAYS exit 0 — success or
  *     failure alike, because a hook must stay silent rather than spam the
  *     session's own turn with a stack trace;
@@ -29,34 +28,39 @@
  *     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
- * `resolveBridgeOptions` (`bridge.ts`): the dashboard URL, credential
- * source, and credential come from the connection record this session's OWN
- * danx-dashboard MCP server wrote on its last successful `plan_connect`
- * (`session-connection.ts`), never from this process's own ambient env —
- * the identical DX-2862 reasoning `plan-state.ts` already gives for itself.
+ * THE CREDENTIAL — the SAME resolver `bridge` uses, via `resolveBridgeOptions`
+ * (`bridge.ts`): the dashboard URL, credential source, and credential come
+ * from the connection record this session's OWN danx-dashboard MCP server
+ * wrote on its last successful `plan_connect` (`session-connection.ts`),
+ * never from this process's own ambient env (DX-2862).
  *
  * A HARD TIMEOUT — `BACKGROUND_WORK_REQUEST_TIMEOUT_MS`. A `Stop` hook
  * blocks the session's turn boundary, so this call must never hang: a slow
  * or wedged dashboard is `{ok:false, reason:"timeout"}`, not a stuck hook.
  *
- * THE REQUEST/RUN SCAFFOLDING IS SHARED WITH `plan-state.ts`
- * (`one-shot-session-request.ts`, DX-3367 fix-up) — the two subcommands no
- * longer maintain independent copies of the authenticated-fetch-with-
- * timeout logic or the session/credential resolution boilerplate.
+ * THE REQUEST/RUN SCAFFOLDING (`one-shot-session-request.ts`, DX-3367
+ * fix-up) is shared, general-purpose plumbing for any one-shot subcommand
+ * shaped like this one — not maintained as an independent copy of the
+ * authenticated-fetch-with-timeout logic or the session/credential
+ * resolution boilerplate.
  */
 import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
 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 +72,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
@@ -76,13 +89,13 @@ export function parseCountArg(raw) {
  * DX-3367 fix-up — STATUS IS CHECKED BEFORE THE BODY IS EVER PARSED. A 5xx
  * (or any other non-2xx) response can carry an HTML error page instead of
  * JSON; parsing first would misreport that as `bad_response` when the true
- * classification is `http_error`. Unlike `plan-state.ts`'s `fetchTurnState`,
- * this subcommand has no status that needs the BODY inspected to classify
- * (no `409 session_not_connected` equivalent), so status alone decides
- * whether a body read is even attempted.
+ * classification is `http_error`. This subcommand has no status that needs
+ * the BODY inspected to classify (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 +112,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 +126,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 +138,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 +153,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/event-text.js

@@ -10,11 +10,10 @@
  * collapse into the one hook + this one subcommand). `<event>` is one of
  * `session_start` | `session_resume` | `after_compaction` |
  * `sub_agent_start` — the SAME `npx -y @thehammer/danx-dashboard-mcp@<pin>`
- * path the plugin's other dashboard calls already use (`plan-state`,
- * `bridge`) — never a separate install, never a deep import of this
- * package's `dist/` internals.
+ * path the plugin's other dashboard calls already use (`bridge`) — never a
+ * separate install, never a deep import of this package's `dist/` internals.
  *
- * THE CREDENTIAL — the SAME resolver `bridge` / `plan-state` use
+ * THE CREDENTIAL — the SAME resolver `bridge` uses
  * (`resolveBridgeOptions`, `bridge.ts`): the dashboard URL, credential source
  * and credential all come from the connection record this session's OWN
  * danx-dashboard MCP server wrote on its last successful `plan_connect`
@@ -37,8 +36,8 @@
  *     stderr, exit 1. `event-hook.sh` is the one that decides what to print
  *     for the agent — this module only reports whether the fetch worked.
  *
- * A HARD TIMEOUT (mirrors `plan-state.ts`) — a SessionStart hook must never
- * hang on a wedged dashboard.
+ * A HARD TIMEOUT — a SessionStart hook must never hang on a wedged
+ * dashboard.
  */
 import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
 export const EVENT_TEXT_SUBCOMMAND = "event-text";

package/dist/index.js

@@ -74,7 +74,6 @@
  */
 import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
-import { PLAN_STATE_SUBCOMMAND, runPlanStateCommand } from "./plan-state.js";
 import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./background-work.js";
 import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
 import { resolveDeclaredCredential } from "./credential.js";
@@ -460,22 +459,14 @@ async function main() {
 // symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
 // spawns, not just a direct `node dist/index.js`.
 //
-// `bridge` and `plan-state` are the two subcommands. `bridge` is the session
-// event stream client the danxbot plugin's plan event bridge runs. It never
-// boots the MCP server; its only input is `CLAUDE_CODE_SESSION_ID` (read from
-// its environment) plus `--resume-ids` — the dashboard URL, credential source,
-// and credential itself come from the session-connection record this server's
-// own `plan_connect` wrote (`session-connection.ts`), never from the bridge's
-// own environment (DX-2862: a bridge trusting its own ambient
-// `DANXBOT_DISPATCH_TOKEN` is the exact bug this repo fixed).
-//
-// `plan-state` (DX-2921) is the ONE-SHOT client of
-// `GET /api/plan-sessions/me/turn-state`, run by the DX-2888 plugin's
-// turn-start / turn-end hooks — see `plan-state.ts`'s own doc comment for the
-// full contract. It ALWAYS exits 0 (success or failure alike: the hook must
-// stay silent), so even an unexpected rejection here is caught and reported
-// the same `{ok:false, reason}` way rather than propagating a non-zero exit
-// or an uncaught stack trace into the hook.
+// `bridge` is the session event stream client the danxbot plugin's plan
+// event bridge runs. It never boots the MCP server; its only input is
+// `CLAUDE_CODE_SESSION_ID` (read from its environment) plus `--resume-ids` —
+// the dashboard URL, credential source, and credential itself come from the
+// session-connection record this server's own `plan_connect` wrote
+// (`session-connection.ts`), never from the bridge's own environment
+// (DX-2862: a bridge trusting its own ambient `DANXBOT_DISPATCH_TOKEN` is the
+// exact bug this repo fixed).
 //
 // Any OTHER argument is refused rather than ignored, so a typo cannot
 // silently start an MCP server on stdio where a subcommand was meant to run.
@@ -487,13 +478,6 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(1);
         });
     }
-    else if (subcommand === PLAN_STATE_SUBCOMMAND) {
-        runPlanStateCommand(rest).then((code) => process.exit(code), (err) => {
-            console.error(`[danx-dashboard-mcp] plan-state fatal: ${err.message}`);
-            process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
-            process.exit(0);
-        });
-    }
     else if (subcommand === BACKGROUND_WORK_SUBCOMMAND) {
         runBackgroundWorkCommand(rest).then((code) => process.exit(code), (err) => {
             console.error(`[danx-dashboard-mcp] background-work fatal: ${err.message}`);
@@ -502,12 +486,11 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
         });
     }
     else if (subcommand === EVENT_TEXT_SUBCOMMAND) {
-        // DX-3421 (was DX-3366's `mantra` subcommand) — unlike plan-state/
-        // background-work, a rejection here is a genuine fatal (never expected:
-        // runEventTextCommand itself already classifies every network/shape
-        // failure into its own {ok:false} exit 1), so it exits 1 too rather than
-        // the "always 0, stay silent" contract those two hook-only subcommands
-        // use.
+        // DX-3421 (was DX-3366's `mantra` subcommand) — unlike background-work, a
+        // rejection here is a genuine fatal (never expected: runEventTextCommand
+        // itself already classifies every network/shape failure into its own
+        // {ok:false} exit 1), so it exits 1 too rather than the "always 0, stay
+        // silent" contract background-work's hook-only subcommand uses.
         runEventTextCommand(rest).then((code) => process.exit(code), (err) => {
             console.error(`[danx-dashboard-mcp] event-text fatal: ${err.message}`);
             process.exit(1);
@@ -515,7 +498,7 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
     }
     else if (subcommand !== undefined) {
         console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BRIDGE_SUBCOMMAND}", "${PLAN_STATE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", and "${EVENT_TEXT_SUBCOMMAND}")`);
+            `"${BRIDGE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", and "${EVENT_TEXT_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

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/dist/one-shot-session-request.js

@@ -1,21 +1,22 @@
 /**
  * DX-3367 fix-up — shared scaffolding for a "one-shot session request"
- * subcommand: `plan-state` (`GET /api/plan-sessions/me/turn-state`) and
- * `background-work` (`PUT /api/plan-sessions/me/background-work`) each
- * duplicated this exact shape independently (`fetchTurnState` /
- * `putBackgroundWork`, `runPlanStateCommand` / `runBackgroundWorkCommand`).
- * This module is the ONE place that shape lives now; a future one-shot
- * subcommand extends it instead of copying either file again.
+ * subcommand. Extracted when `plan-state` (`GET /api/plan-sessions/me/turn-state`,
+ * removed by DX-3689 — it never had a caller) and `background-work`
+ * (`PUT /api/plan-sessions/me/background-work`) turned out to duplicate this
+ * exact shape independently (`fetchTurnState` / `putBackgroundWork`,
+ * `runPlanStateCommand` / `runBackgroundWorkCommand`). This module is the ONE
+ * place that shape lives now; a future one-shot subcommand extends it
+ * instead of copying `background-work.ts` again.
  *
- * Two pieces, matching the two duplicated concerns:
+ * Two pieces:
  *   - `sendSessionRequest` — the authenticated HTTP call itself: bearer +
  *     session header, a hard abort-timeout, and network-level failure
  *     classification (`timeout` / `request_failed`). Returns the raw
  *     `{status, text}` UNPARSED — each caller decides for itself which
- *     statuses need the body inspected (e.g. `plan-state`'s 409
- *     `session_not_connected`) and which don't, so a non-2xx status with an
- *     unparseable (e.g. HTML) body is classified from the status alone
- *     rather than colliding with "the JSON didn't parse" (`bad_response`).
+ *     statuses need the body inspected and which don't, so a non-2xx status
+ *     with an unparseable (e.g. HTML) body is classified from the status
+ *     alone rather than colliding with "the JSON didn't parse"
+ *     (`bad_response`).
  *   - `resolveSessionOptions` — session-id + credential resolution via
  *     `resolveBridgeOptions`, with `BridgeStartError` narrowed by
  *     `instanceof` rather than an unchecked `as BridgeStartError` cast, so

package/package.json

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

package/dist/plan-state.js

@@ -1,174 +0,0 @@
-/**
- * `danx-dashboard-mcp plan-state` — the ONE-SHOT client of
- * `GET /api/plan-sessions/me/turn-state` (DX-2921).
- *
- * WHO RUNS IT. The danxbot Claude Code plugin's DX-2888 turn-start /
- * turn-end hooks, via the plugin's existing `bridgeCommand()` npx path — the
- * SAME package pin, no separate install, no deep import of this package's
- * `dist/` internals (that was DX-2921's whole reason to exist: the DX-2888
- * architecture review found the first build of this logic vendored a private
- * copy of the MCP package and hardcoded the dashboard HTTP contract inside
- * the PLUGIN). The plugin decides what to DO with the answer (inject plan
- * numbers at turn start, refuse to let a turn end while the session could
- * legally start work and has nothing running); this module only fetches it.
- *
- * THE CONTRACT (agreed with the DX-2888 plugin side, issue comment 4245 on
- * DX-2921 — binding, because the plugin is already built against it):
- *   - print EXACTLY ONE JSON line on stdout, and ALWAYS exit 0 — success or
- *     failure alike, because the hook must stay silent rather than spam the
- *     session's own turn with a stack trace;
- *   - a session that is not connected to a plan prints
- *     `{"ok":false,"reason":"session_not_connected"}` — that EXACT literal,
- *     because the plugin keys its no-log-spam rule on it (it is also the
- *     dashboard's own 409 error code for this case — see
- *     `requireConnectedPlanId`, `plan-session-context.ts`);
- *   - on success, every count is a finite number, `plan` carries `id` +
- *     `name`, and every `startable` / `held` entry carries a string `id` +
- *     `title` — the plugin rejects anything else as `bad_response`, so this
- *     module validates the server's response BEFORE printing it, rather than
- *     trusting a 200 status to mean a well-shaped body;
- *   - human-readable diagnostics go to stderr only, never stdout.
- *
- * THE CREDENTIAL — the SAME resolver `bridge` uses (DX-2862 / DX-2921 AC),
- * via `resolveBridgeOptions` (`bridge.ts`): the dashboard URL, credential
- * source and credential all come from the connection record this session's
- * OWN danx-dashboard MCP server wrote on its last successful `plan_connect`
- * (`session-connection.ts`), never from this process's own ambient env. That
- * is deliberate here for the identical reason it is deliberate for `bridge`:
- * a hook process trusting whatever `DANXBOT_DISPATCH_TOKEN` happens to be in
- * its environment is precisely the DX-2862 bug (a hook's ambient credential
- * silently pointed at a different dashboard from the one the session's tools
- * actually use).
- *
- * A HARD TIMEOUT (AC 30672) — `PLAN_STATE_REQUEST_TIMEOUT_MS`. This call
- * blocks a turn boundary the plugin is holding open, so it must never hang:
- * a slow or wedged dashboard is `{ok:false, reason:"timeout"}`, not a stuck
- * hook.
- *
- * THE REQUEST/RUN SCAFFOLDING IS SHARED WITH `background-work.ts`
- * (`one-shot-session-request.ts`, DX-3367 fix-up).
- */
-import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
-export const PLAN_STATE_SUBCOMMAND = "plan-state";
-export const TURN_STATE_PATH = "/api/plan-sessions/me/turn-state";
-/** How long this one-shot call may take before it counts as a timeout. */
-export const PLAN_STATE_REQUEST_TIMEOUT_MS = 5_000;
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${PLAN_STATE_SUBCOMMAND}`;
-function errorCodeOf(body) {
-    return typeof body === "object" && body !== null && typeof body.error === "string"
-        ? body.error
-        : null;
-}
-function isFiniteNumber(v) {
-    return typeof v === "number" && Number.isFinite(v);
-}
-function isCardRef(v) {
-    return (typeof v === "object" &&
-        v !== null &&
-        typeof v.id === "string" &&
-        typeof v.title === "string");
-}
-/**
- * The strict shape check the contract pins (comment 4245): finite counts, a
- * `plan` with `id` + `name`, and a string `id` + `title` on every
- * `startable` / `held` entry. `null` on anything short of that — a 200 whose
- * body does not match is `bad_response`, exactly like a non-2xx.
- */
-export function parseTurnStateBody(body) {
-    if (typeof body !== "object" || body === null)
-        return null;
-    const b = body;
-    const plan = b.plan;
-    if (typeof plan !== "object" || plan === null)
-        return null;
-    const p = plan;
-    if (!isFiniteNumber(p.id) || typeof p.name !== "string")
-        return null;
-    const counts = b.counts;
-    if (typeof counts !== "object" || counts === null)
-        return null;
-    const c = counts;
-    if (!isFiniteNumber(c.open) || !isFiniteNumber(c.inProgress) || !isFiniteNumber(c.needsYou))
-        return null;
-    if (!Array.isArray(b.startable) || !b.startable.every(isCardRef))
-        return null;
-    if (!Array.isArray(b.held) || !b.held.every(isCardRef))
-        return null;
-    return {
-        plan: { id: p.id, name: p.name },
-        counts: { open: c.open, inProgress: c.inProgress, needsYou: c.needsYou },
-        startable: b.startable,
-        held: b.held,
-    };
-}
-/**
- * One authenticated GET, with a hard timeout, classified into the output
- * shape this subcommand always prints — never a throw, never a non-2xx
- * bubbling past this function.
- *
- * DX-3367 fix-up — status is checked BEFORE the body is parsed, except for
- * the ONE status (`409`) whose classification genuinely depends on the body
- * (`session_not_connected`). Any other non-2xx — including a 5xx that comes
- * back as an HTML error page instead of JSON — is `http_error` without ever
- * attempting to parse it, so a body-parse failure on those statuses can
- * never be misreported as `bad_response`.
- */
-export async function fetchTurnState(options, deps) {
-    const sent = await sendSessionRequest(options, TURN_STATE_PATH, { method: "GET" }, deps);
-    if ("reason" in sent)
-        return sent;
-    const { status, text } = sent;
-    if (status === 409) {
-        // The exact literal the plugin's no-log-spam rule keys on (AC 30672 /
-        // comment 4245) — the dashboard's own 409 error code for an unconnected
-        // session, passed through verbatim rather than renamed. A 409 whose body
-        // does NOT carry that code falls through to the ordinary `http_error`
-        // classification below, same as any other non-2xx.
-        const parsed409 = tryParseJsonBody(text);
-        if (parsed409.ok && errorCodeOf(parsed409.body) === "session_not_connected") {
-            return { ok: false, reason: "session_not_connected" };
-        }
-    }
-    if (status === 401 || status === 403) {
-        return { ok: false, reason: "unauthorized" };
-    }
-    if (status < 200 || status >= 300) {
-        return { ok: false, reason: "http_error" };
-    }
-    const parsed = tryParseJsonBody(text);
-    if (!parsed.ok)
-        return { ok: false, reason: "bad_response" };
-    const turnState = parseTurnStateBody(parsed.body);
-    if (turnState === null) {
-        return { ok: false, reason: "bad_response" };
-    }
-    return { ok: true, ...turnState };
-}
-/** The bin's `plan-state` subcommand, wired to the real process. Always resolves to exit code 0. */
-export async function runPlanStateCommand(argv, env = process.env, 
-/** Test seam: the home the session's connection record is read from. */
-resolveFrom = {}) {
-    const write = (output) => {
-        process.stdout.write(`${JSON.stringify(output)}\n`);
-    };
-    if (argv.length !== 0) {
-        // A malformed invocation is still a "the hook must stay silent" failure,
-        // not a crash — same ok:false/exit-0 contract as every other failure
-        // path here, with the usage line reserved for a human reading stderr.
-        write({ ok: false, reason: "usage" });
-        process.stderr.write(`${USAGE}\n`);
-        return 0;
-    }
-    const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
-    if (!resolved.ok) {
-        write(resolved.output);
-        process.stderr.write(`${resolved.detail}\n`);
-        return 0;
-    }
-    const output = await fetchTurnState(resolved.options, {
-        fetch: (input, init) => fetch(input, init),
-        requestTimeoutMs: PLAN_STATE_REQUEST_TIMEOUT_MS,
-    });
-    write(output);
-    return 0;
-}