@thehammer/danx-dashboard-mcp 0.1.286 → 0.1.289

package/dist/session-options.js

@@ -1,9 +1,9 @@
 /**
- * DX-2862 / DX-4233 - how a one-shot client of the dashboard (`activity`, `background-work`, `ready-cards`, and the
- * predecessor lookup of `restart_notice`) learns WHICH dashboard to call and AS WHOM: the connection record this session's own MCP server wrote when
- * it connected a plan (`session-connection.ts`), resolved through the same credential resolver the server used, and refused
- * unless it fingerprints identically. (The in-process relay behind `plan_events_wait` needs none of this: it lives inside the
- * server that holds the credential.)
+ * DX-2862 / DX-4233 - how `restart_notice` (`restart-notice.ts`, this file's only caller) learns which dashboard to call and
+ * as whom when it asks about an earlier session. It reads the connection record that session's own MCP server wrote when it
+ * connected a plan (`session-connection.ts`), resolves the credential the record names through the same resolver the server
+ * used, and refuses unless it fingerprints identically. The in-process relay behind `plan_events_wait` needs none of this: it
+ * lives inside the server that holds the credential.
  */
 import { homedir } from "node:os";
 import { credentialFingerprint, describeCredentialSource, readCredential } from "./credential.js";
@@ -52,7 +52,7 @@ export function resolveDashboardAuth(sessionId, env, options = {}) {
     const fingerprint = credentialFingerprint(token);
     if (fingerprint !== record.fingerprint) {
         throw new SessionStartError("credential_mismatch", `${describeCredentialSource(record.source)} now yields credential ${fingerprint}, but this session's ` +
-            `danx-dashboard MCP server is using ${record.fingerprint} — a one-shot call would authenticate as somebody else`, fixForStop("credential_mismatch"));
+            `danx-dashboard MCP server is using ${record.fingerprint} — a lookup would authenticate as somebody else`, fixForStop("credential_mismatch"));
     }
     return { dashboardUrl: record.dashboardUrl.replace(/\/+$/, ""), token, sessionId };
 }

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

@@ -1,8 +1,8 @@
 /**
  * DX-4233 - the remedy a session is shown for each way its dashboard event stream can stop, in ONE place.
  *
- * The client that ends in these texts is the in-process relay behind `plan_events_wait` (`plan-events-relay.ts`); the one-shot
- * subcommands use `fixForStop` for a start they cannot make. Pure data and one function with no imports.
+ * The client that ends in these texts is the in-process relay behind `plan_events_wait` (`plan-events-relay.ts`); `session-options.ts` uses
+ * `fixForStop` for a start it cannot make. Pure data and one function with no imports.
  */
 /**
  * The remedy per terminal reason. ONE map, so the message a session is shown and the message a log carries can never drift.
@@ -15,16 +15,16 @@
 const RESTART_NOTICE_STOP_LEAD = "continue without it";
 const RESTART_NOTICE_STOP_TAIL = "call plan_connect to connect this session to a plan";
 export const STOP_FIXES = {
-    no_connection_record: "call plan_connect again in this session — its danx-dashboard MCP server records the connection a hook command needs " +
+    no_connection_record: "call plan_connect again in this session — its danx-dashboard MCP server records the connection that restart_notice and the listener reminder read " +
         "(a server older than the one that introduced the record writes none)",
     credential_unavailable: "call plan_connect again to request access: this session's key file is missing or unreadable",
-    credential_mismatch: "restart this Claude Code session so its MCP server and the plugin's hook commands pick up the same credential, then call plan_connect again",
+    credential_mismatch: "restart this Claude Code session so its MCP server resolves its credential afresh, 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 (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.286",
+  "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",

package/dist/activity.js

@@ -1,260 +0,0 @@
-/**
- * `danx-dashboard-mcp activity <SubagentStart|SubagentStop|PostToolUse> <event-at>` — the
- * ONE-SHOT client of `POST /api/plan-sessions/me/activity` (DX-3284).
- *
- * WHO RUNS IT. The danxbot Claude Code plugin's `SubagentStart`, `SubagentStop` and
- * `PostToolUse` (matcher `Bash`) hooks (`danxbot/scripts/activity-report.mjs` in
- * claude-plugins), all registered `async: true`. The plugin runs the INSTALLED package
- * with `node` (DX-3811), never a cold `npx`, and pipes the hook's own JSON envelope on
- * stdin. This module owns what each event MEANS for the session's running set; the plugin
- * decides only whether to call at all (a plan-connected session, a background Bash call).
- *
- * THE THREE EVENTS (the Claude Code hooks reference, `code.claude.com/docs/en/hooks`):
- *
- * | Event          | Reports                                                          | Key                        |
- * |----------------|------------------------------------------------------------------|----------------------------|
- * | `SubagentStart`| an `agent` activity, running                                     | `agent-<agent_id>`         |
- * | `SubagentStop` | the same activity, FINISHED                                      | `agent-<agent_id>`         |
- * | `PostToolUse`  | a `bash` activity, running — only for `Bash` with                | `tool_use_id`              |
- * |                | `tool_input.run_in_background: true`                             |                            |
- *
- * THE SUB-AGENT KEY. A sub-agent's transcript is `<session>/subagents/agent-<agent_id>.jsonl`,
- * and the transcript producer (`createActivityObserver`) keys its row on that file's
- * basename, `agent-<agent_id>`. Reporting the bare `agent_id` would upsert a SECOND row for
- * the same sub-agent, so the hook-side key is the same basename: the two producers converge
- * on one row. The hooks docs disagree on whether `agent_id` already carries the `agent-`
- * prefix, so {@link subagentActivityId} normalizes both forms to the one key.
- *
- * KNOWN LIMITS (DX-3284, pinned in `plan-session-activity.test.ts`):
- *   - a sub-agent RESUMED after its SubagentStop reports a second start, but the server's
- *     first finish wins, so the row stays closed;
- *   - a SubagentStop with no `agent_id` (Claude Code's internal agents) is refused below, and
- *     the plugin leaves a failure trace. One WITH an id but no recorded start is
- *     indistinguishable from a stop that beat its (async) start, so it is recorded as an
- *     already-finished row — it never counts as running. (`transcript_path` cannot supply it: on these events it is the MAIN session's
- * transcript — only `SubagentStop`'s `agent_transcript_path` names the sub-agent's own, and
- * it is used below to REFUSE a mismatch, never to guess one.)
- *
- * THERE IS NO "BACKGROUND SHELL FINISHED" EVENT. None of the documented hook events fires
- * when a `run_in_background` Bash command ends (verified against the full event list on
- * DX-2954's Step 0 note; `TaskCreated` / `TaskCompleted` are the `TaskCreate` tool, not a
- * shell). A `bash` activity therefore gets a start here and no finish: its end comes from
- * the dispatch's own terminal write (`finishOpenActivities`), never from inferring one out
- * of transcript lines. Until then it reads as running and silent, which is the honest
- * signal. Do not "fix" this with a proxy event.
- *
- * THE EVENT TIME is the hook's own, captured by the plugin when the hook FIRED and passed
- * as `<event-at>` — never this process's clock, which starts only after the (possibly
- * cold) install step. The server's upsert is monotone in every field, so hooks that finish
- * out of order, or one that fires twice, still reach the same row.
- *
- * THE CONTRACT (identical to `background-work`, so the plugin treats both alike):
- *   - print EXACTLY ONE JSON line on stdout and ALWAYS exit 0 — a hook has no business
- *     spamming the session with a stack trace;
- *   - `{"ok":true,"runningActivities":<n>}` on success;
- *   - `{"ok":false,"reason":"<why>"}` otherwise. `no_connection_record` and
- *     `session_not_connected` are the ordinary "this session is not on a plan" answers;
- *   - human-readable diagnostics go to stderr only.
- *
- * THE CREDENTIAL — the SAME resolver `plan_events_wait` uses (`resolveSessionOptions`): the URL,
- * credential source and credential come from the connection record this session's own MCP
- * server wrote on `plan_connect`, never from this process's ambient env (DX-2862).
- */
-import { win32 } from "node:path";
-import { readFileSync } from "node:fs";
-import { labelOf } from "@thehammer/danx-session-telemetry";
-import { parseEventAtArg } from "./background-work.js";
-import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
-export const ACTIVITY_SUBCOMMAND = "activity";
-export const ACTIVITY_PATH = "/api/plan-sessions/me/activity";
-/** How long this one-shot call may take before it counts as a timeout. */
-export const ACTIVITY_REQUEST_TIMEOUT_MS = 5_000;
-/** The hook events this subcommand accepts, exactly as Claude Code names them in `hook_event_name`. */
-export const ACTIVITY_HOOK_EVENTS = ["SubagentStart", "SubagentStop", "PostToolUse"];
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${ACTIVITY_SUBCOMMAND} <${ACTIVITY_HOOK_EVENTS.join("|")}> <event-at ISO-8601 UTC>  (the hook's JSON envelope on stdin)`;
-const SUBAGENT_PREFIX = "agent-";
-/**
- * A sub-agent's transcript file basename — the key `createActivityObserver` reports it under.
- *
- * DX-3284: the hooks documentation shows `agent_id` BOTH ways — SubagentStart's example carries
- * the `agent-` prefix (`agent-abc123`), SubagentStop's does not (`def456`, against the file
- * `agent-def456.jsonl`). The key is `agent-` + the id with ONE leading `agent-` stripped, so both
- * forms converge on the transcript producer's row; keying on the raw id would leave a phantom
- * `agent-agent-<id>` row that no stop ever closes.
- */
-export function subagentActivityId(agentId) {
-    const bare = agentId.startsWith(SUBAGENT_PREFIX) ? agentId.slice(SUBAGENT_PREFIX.length) : agentId;
-    return `${SUBAGENT_PREFIX}${bare}`;
-}
-/**
- * DX-4498 — the facts only a transcript knows (the spawning sub-agent, effort, current tool call, how a background task
- * ended, the card its spawning `Agent` call names). A hook envelope carries none of them, so it reports each as unknown; the server's merge
- * never lets an unknown erase a value the transcript producer stored. A `SubagentStop` names no status either: its
- * finish reads as `done` unless a task notification says otherwise.
- */
-const NO_TRANSCRIPT_FACTS = {
-    parentActivityId: null,
-    effort: null,
-    currentActivity: null,
-    endStatus: null,
-    briefIssueId: null,
-};
-function nonEmptyString(value) {
-    return typeof value === "string" && value !== "";
-}
-/**
- * One hook envelope -> the ONE `ActivityChange` it stands for, or the reason it stands for
- * none. Pure: `eventAtMs` is the hook's own event time.
- */
-export function activityChangeFromHook(event, envelope, eventAtMs) {
-    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) {
-        return { ok: false, reason: "bad_envelope" };
-    }
-    const e = envelope;
-    // The envelope names the event it was fired for; a mismatch is a wiring bug, not data.
-    if (e.hook_event_name !== undefined && e.hook_event_name !== event) {
-        return { ok: false, reason: "event_mismatch" };
-    }
-    if (event === "PostToolUse") {
-        const input = e.tool_input;
-        if (e.tool_name !== "Bash" || typeof input !== "object" || input === null) {
-            return { ok: false, reason: "not_background_bash" };
-        }
-        const toolInput = input;
-        if (toolInput.run_in_background !== true)
-            return { ok: false, reason: "not_background_bash" };
-        if (!nonEmptyString(e.tool_use_id))
-            return { ok: false, reason: "no_tool_use_id" };
-        return {
-            ok: true,
-            change: {
-                kind: "bash",
-                activityId: e.tool_use_id,
-                agentType: null,
-                // DX-4498 — agent-written free text, so it is redacted like every label that reaches the running set.
-                description: labelOf(toolInput.description),
-                startedAt: eventAtMs,
-                // No hook ever refreshes or ends a background shell (see the module docblock), so
-                // its liveness is its start and `finishedAt` stays null until the dispatch ends.
-                lastActivityAt: eventAtMs,
-                finishedAt: null,
-                ...NO_TRANSCRIPT_FACTS,
-            },
-        };
-    }
-    // A SubagentStop from one of Claude Code's own internal agents carries no `agent_id`: it names
-    // no activity, so it is refused here (the plugin leaves a failure trace) and nothing is
-    // written — a stop must never invent a row.
-    if (!nonEmptyString(e.agent_id) || e.agent_id === SUBAGENT_PREFIX)
-        return { ok: false, reason: "no_agent_id" };
-    const activityId = subagentActivityId(e.agent_id);
-    if (event === "SubagentStop" && e.agent_transcript_path !== undefined) {
-        // The one place the hook names the sub-agent's own file: if it disagrees with the
-        // key derived from `agent_id`, this process would upsert a duplicate row. Refuse.
-        const file = typeof e.agent_transcript_path === "string" ? win32.basename(e.agent_transcript_path, ".jsonl") : null;
-        if (file !== activityId)
-            return { ok: false, reason: "agent_id_mismatch" };
-    }
-    return {
-        ok: true,
-        change: {
-            kind: "agent",
-            activityId,
-            agentType: nonEmptyString(e.agent_type) ? e.agent_type : null,
-            description: null,
-            startedAt: eventAtMs,
-            lastActivityAt: eventAtMs,
-            finishedAt: event === "SubagentStop" ? eventAtMs : null,
-            ...NO_TRANSCRIPT_FACTS,
-        },
-    };
-}
-/**
- * One authenticated POST, with a hard timeout, classified into the output shape this
- * subcommand always prints — never a throw. Status is checked before any body is parsed
- * (an HTML 5xx page must read as `http_error`, not `bad_response`); only a 409 needs its
- * body, to tell "no plan" from "a worker's session".
- */
-export async function postActivity(options, change, deps) {
-    const sent = await sendSessionRequest(options, ACTIVITY_PATH, { method: "POST", body: JSON.stringify({ activities: [change] }) }, deps);
-    if ("reason" in sent)
-        return sent;
-    const { status, text } = sent;
-    if (status === 401 || status === 403)
-        return { ok: false, reason: "unauthorized" };
-    if (status === 409) {
-        const parsed = tryParseJsonBody(text);
-        const error = parsed.ok ? parsed.body?.error : undefined;
-        if (error === "session_not_connected" || error === "session_is_worker")
-            return { ok: false, reason: error };
-        return { ok: false, reason: "http_error" };
-    }
-    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 body = parsed.body;
-    if (typeof body?.runningActivities !== "number")
-        return { ok: false, reason: "bad_response" };
-    return { ok: true, runningActivities: body.runningActivities };
-}
-/** The bin's `activity` subcommand, wired to the real process. Always resolves to exit code 0. */
-export async function runActivityCommand(argv, env = process.env, 
-/** Test seam: the home the session's connection record is read from. */
-resolveFrom = {}, 
-/** Test seam: the hook envelope's text (the real process reads stdin). */
-readEnvelope = () => readFileSync(0, "utf8")) {
-    const write = (output) => {
-        process.stdout.write(`${JSON.stringify(output)}\n`);
-    };
-    const usageFailure = (detail) => {
-        write({ ok: false, reason: "usage" });
-        process.stderr.write(`${detail}\n${USAGE}\n`);
-        return 0;
-    };
-    if (argv.length !== 2)
-        return usageFailure("expected exactly two arguments");
-    const event = ACTIVITY_HOOK_EVENTS.includes(argv[0]) ? argv[0] : null;
-    if (event === null)
-        return usageFailure(`unknown hook event "${argv[0]}"`);
-    const eventAt = parseEventAtArg(argv[1]);
-    if (typeof eventAt === "object")
-        return usageFailure(eventAt.error);
-    let envelope;
-    try {
-        envelope = JSON.parse(readEnvelope());
-    }
-    catch {
-        write({ ok: false, reason: "bad_envelope" });
-        process.stderr.write("the hook envelope on stdin is not JSON\n");
-        return 0;
-    }
-    const mapped = activityChangeFromHook(event, envelope, Date.parse(eventAt));
-    if (!mapped.ok) {
-        write(mapped);
-        process.stderr.write(`${event} envelope reports no activity: ${mapped.reason}\n`);
-        return 0;
-    }
-    // The connection record is this session's: an envelope for ANOTHER session must never
-    // be reported under it.
-    const envelopeSession = envelope.session_id;
-    if (envelopeSession !== undefined && envelopeSession !== env.CLAUDE_CODE_SESSION_ID) {
-        write({ ok: false, reason: "session_mismatch" });
-        process.stderr.write("the envelope's session_id is not CLAUDE_CODE_SESSION_ID\n");
-        return 0;
-    }
-    const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
-    if (!resolved.ok) {
-        // A session that never `plan_connect`-ed has no connection record: the ordinary
-        // "not on a plan" case, silent for the plugin.
-        write(resolved.output);
-        process.stderr.write(`${resolved.detail}\n`);
-        return 0;
-    }
-    write(await postActivity(resolved.options, mapped.change, {
-        fetch: (input, init) => fetch(input, init),
-        requestTimeoutMs: ACTIVITY_REQUEST_TIMEOUT_MS,
-    }));
-    return 0;
-}

package/dist/background-work.js

@@ -1,162 +0,0 @@
-/**
- * `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 `plan_events_wait` — 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
- * against production drift, comment 7102 on the card: the background-work
- * hooks pinned `0.1.136` while `plan_events_wait` was still pinned `0.1.95`) — a
- * version bump to one hook's pin never moves the others. The plugin decides
- * WHAT to report (parsing `Stop`/`SubagentStop`'s own `background_tasks`
- * snapshot, counting only `shell` / `subagent` / `workflow` entries,
- * sending `clear` on `SessionStart`/`StopFailure`); this module only
- * delivers the report.
- *
- * 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;
- *   - a session with no connection record (never `plan_connect`-ed, e.g. an
- *     operator session that never joined a plan) is a silent, expected
- *     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>,"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 `plan_events_wait` uses, via `resolveDashboardAuth`
- * (the relay): 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 (`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> <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.
- */
-export function parseCountArg(raw) {
-    if (raw === "clear")
-        return null;
-    if (!/^\d+$/.test(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
- * bubbling past this function.
- *
- * 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`. 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, 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;
-    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 body = parsed.body;
-    if (typeof body !== "object" ||
-        body === null ||
-        !("count" in body) ||
-        (body.count !== null && typeof body.count !== "number") ||
-        typeof body.applied !== "boolean") {
-        return { ok: false, reason: "bad_response" };
-    }
-    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, 
-/** 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 !== 2) {
-        write({ ok: false, reason: "usage" });
-        process.stderr.write(`${USAGE}\n`);
-        return 0;
-    }
-    const parsed = parseCountArg(argv[0]);
-    if (typeof parsed === "object" && parsed !== null && "error" in parsed) {
-        write({ ok: false, reason: "usage" });
-        process.stderr.write(`${parsed.error}\n${USAGE}\n`);
-        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
-        // is the ORDINARY "not plan-connected" case, not an error the plugin
-        // should surface: it simply forwards nothing further this turn.
-        write(resolved.output);
-        process.stderr.write(`${resolved.detail}\n`);
-        return 0;
-    }
-    const output = await putBackgroundWork(resolved.options, { count, eventAt }, {
-        fetch: (input, init) => fetch(input, init),
-        requestTimeoutMs: BACKGROUND_WORK_REQUEST_TIMEOUT_MS,
-    });
-    write(output);
-    return 0;
-}

package/dist/one-shot-session-request.js

@@ -1,105 +0,0 @@
-/**
- * DX-3367 fix-up — shared scaffolding for a "one-shot session request"
- * 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:
- *   - `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 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
- *     `resolveDashboardAuth`, with `SessionStartError` narrowed by
- *     `instanceof` rather than an unchecked `as SessionStartError` cast, so
- *     an error of some OTHER shape (a bug in the resolver, a thrown
- *     non-Error) still comes back as a reported reason instead of a value
- *     whose `.reason`/`.message`/`.fix` fields are silently `undefined`.
- */
-import { boundRequest } from "./request-bound.js";
-import { SESSION_ID_HEADER, resolveDashboardAuth, SessionStartError } from "./session-options.js";
-/**
- * One authenticated HTTP call to this session's dashboard, with a hard
- * timeout. Never throws — a network failure or an abort is reported as
- * `OneShotFailure`, exactly like any other classified failure the caller
- * might produce from the status/body it gets back on success.
- */
-export async function sendSessionRequest(options, path, init, deps) {
-    const bound = boundRequest(deps.requestTimeoutMs, deps.signal);
-    try {
-        try {
-            const response = await deps.fetch(`${options.dashboardUrl}${path}`, {
-                method: init.method,
-                headers: {
-                    Authorization: `Bearer ${options.token}`,
-                    Accept: "application/json",
-                    ...(init.body !== undefined ? { "Content-Type": "application/json" } : {}),
-                    [SESSION_ID_HEADER]: options.sessionId,
-                },
-                body: init.body,
-                signal: bound.signal,
-            });
-            const text = await response.text();
-            return { status: response.status, text };
-        }
-        catch {
-            // DX-3367 fix-up — the caught value is never inspected (an aborted
-            // fetch's own rejection shape varies by runtime), so binding it to a
-            // name the code never reads was dead weight the linter never caught.
-            return { ok: false, reason: bound.aborted() ? "timeout" : "request_failed" };
-        }
-    }
-    finally {
-        bound.release();
-    }
-}
-/** `JSON.parse`, classified rather than thrown — the ONE shared parse point
- *  every caller uses once it has decided (from `status`) that the body is
- *  worth reading at all. */
-export function tryParseJsonBody(text) {
-    try {
-        return { ok: true, body: text === "" ? null : JSON.parse(text) };
-    }
-    catch {
-        return { ok: false };
-    }
-}
-/**
- * Resolve this process's session id + dashboard credential, the identical
- * first step every one-shot subcommand's `runXCommand` takes before it can
- * make its own request. `detail` is the stderr-only human-readable line the
- * caller prints alongside `output` — never part of the stdout JSON contract.
- */
-export async function resolveSessionOptions(env, resolveFrom, usage) {
-    const sessionId = env.CLAUDE_CODE_SESSION_ID;
-    if (!sessionId) {
-        return { ok: false, output: { ok: false, reason: "no_session_id" }, detail: usage };
-    }
-    try {
-        const options = resolveDashboardAuth(sessionId, env, resolveFrom);
-        return { ok: true, options };
-    }
-    catch (err) {
-        // DX-3367 fix-up — `instanceof`, never an unchecked `as SessionStartError`
-        // cast: `resolveDashboardAuth` throws exactly `SessionStartError` today,
-        // but a cast reports a fabricated reason/message/fix (all `undefined`)
-        // for any OTHER thrown shape instead of a real one, silently.
-        if (err instanceof SessionStartError) {
-            return {
-                ok: false,
-                output: { ok: false, reason: err.reason },
-                detail: `${err.reason}: ${err.message}. Fix: ${err.fix}.`,
-            };
-        }
-        const message = err instanceof Error ? err.message : String(err);
-        return { ok: false, output: { ok: false, reason: "start_failed" }, detail: `start_failed: ${message}` };
-    }
-}