@thehammer/danx-dashboard-mcp 0.1.52 → 0.1.54

package/README.md

@@ -33,6 +33,20 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `issue_requires_human` | `POST/DELETE /api/issues/:id/requires-human` | Set replaces step rows atomically; clear soft-deletes them. A successful set also returns `solutions_reminder: {solution_count, instruction}` |
 | `issue_retro` | `PUT /api/issues/:id/retro` | Requires terminal card; replace semantics |
 
+## `listen` — a working session's event listener
+
+`plan_connect` connects the session to a plan AND returns `listener: {command, persistent: true, instruction}`. The agent arms `command` with Claude Code's Monitor tool (`persistent: true`); every line the command prints becomes a notification that wakes the session.
+
+```bash
+npx -y @thehammer/danx-dashboard-mcp@<version> listen --stream <dashboard>/api/plan-sessions/stream --ticket <ticket> --lease-ms <ms>
+```
+
+All three flags come from the dashboard's own ticket response; `plan_connect` assembles the command, so never build it by hand.
+
+- **Credential.** `--ticket` is a listener ticket minted by `POST /api/plan-sessions/me/stream-ticket` for THIS session only. It authorizes reading that one session's event stream and nothing else, and stops the moment the credential that minted it is revoked — the MCP server's own token never appears in the command. Minting a new one (calling `plan_connect` again) ends the previous listener; a second connection with the same ticket replaces the first.
+- **Output.** Exactly one line per event on the connected plan's cards — `[DX-8 "Title" repo:board] newms87 answered: chose "Pause E2E" — note: "only this week"`, `… commented: "…"`, `… set requires_human: "…"`, `… cleared requires_human`, `… blocked the card: "…"`, `… unblocked the card`. Nothing for keep-alives or reconnects. The session's own writes are never echoed back to it. An event it cannot read still produces one `could not read event` line.
+- **Reconnect.** A read-idle timeout (three missed keep-alives) turns a silently dead connection into a drop. Capped exponential backoff (1s → 30s) that resets only after a healthy connection, with `Last-Event-ID`, so a dashboard restart replays what was missed and nothing is printed twice. One final `[danx-dashboard listen] …` line and exit when the ticket is refused or revoked (exit 1), when a newer listener takes over (exit 0), or after `--lease-ms` without a healthy connection (exit 1) — the remedy is always `plan_connect` again.
+
 ## Build + test
 
 ```bash

package/dist/handlers.js

@@ -721,6 +721,39 @@ export async function planGet(client, args = {}) {
         basePath: PLANS_BASE_PATH,
     });
 }
+function readIssuedTicket(body) {
+    const b = body;
+    return b !== null &&
+        typeof b.ticket === "string" &&
+        b.ticket !== "" &&
+        typeof b.streamPath === "string" &&
+        typeof b.leaseMs === "number"
+        ? { ticket: b.ticket, streamPath: b.streamPath, leaseMs: b.leaseMs }
+        : null;
+}
+/**
+ * The exact shell command a Monitor runs. The ticket is the only credential in
+ * it; the stream URL and lease come from the dashboard's own ticket response, so
+ * the listener carries no copy of either.
+ */
+export function listenCommand(target, issued) {
+    const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+    const streamUrl = `${target.baseUrl.replace(/\/+$/, "")}${issued.streamPath}`;
+    return (`npx -y ${target.packageSpec} listen --stream ${quote(streamUrl)} ` +
+        `--ticket ${quote(issued.ticket)} --lease-ms ${issued.leaseMs}`);
+}
+function listenerNotArmed(status, connected, ticketResponse) {
+    return {
+        ok: false,
+        status,
+        body: {
+            error: "listener_not_armed",
+            message: "This session IS now connected to the plan, but no listener ticket was issued, so no listener can be armed and this plan's events will NOT reach this session. Resolve the problem below and call plan_connect again.",
+            connected,
+            ticket_response: ticketResponse,
+        },
+    };
+}
 /**
  * Connect THIS session to a plan — the same write the operator's Connect
  * action performs, reaching the same server-side code path. `me` in the URL
@@ -729,22 +762,63 @@ export async function planGet(client, args = {}) {
  *
  * A session already on another plan is MOVED, and the response says which
  * plan it left (`movedFrom`).
+ *
+ * THEN IT ARMS THE LISTENER. A connected session must hear about its plan's
+ * cards the moment something happens, so the reply carries the exact Monitor
+ * command to run. The command holds a stream TICKET this server mints for the
+ * session — never this server's own long-lived token, which must not appear in
+ * a command line. Minting a ticket replaces the session's previous one, so
+ * re-connecting (after a restart, or to re-arm) leaves exactly one listener.
+ *
+ * A refused ticket is NOT reported as a successful connect: the binding did
+ * happen, but a session that believes it is listening when it is not would miss
+ * the operator's answer silently, so the whole call fails loud and says both.
  */
-export async function planConnect(client, args) {
-    return client.request({
+export async function planConnect(client, args, listener) {
+    const connected = await client.request({
         method: "POST",
         path: "/me/plan",
         basePath: PLAN_SESSIONS_BASE_PATH,
         body: { plan_id: args.plan_id },
     });
+    if (!connected.ok)
+        return connected;
+    let issued;
+    try {
+        issued = await client.request({
+            method: "POST",
+            path: "/me/stream-ticket",
+            basePath: PLAN_SESSIONS_BASE_PATH,
+        });
+    }
+    catch (err) {
+        // The binding already happened; a thrown ticket request must not erase that fact.
+        return listenerNotArmed(502, connected.body, { error: err instanceof Error ? err.message : String(err) });
+    }
+    const ticket = issued.ok ? readIssuedTicket(issued.body) : null;
+    if (ticket === null) {
+        return listenerNotArmed(issued.ok ? 502 : issued.status, connected.body, issued.body);
+    }
+    return {
+        ...connected,
+        listener: {
+            command: listenCommand(listener, ticket),
+            persistent: true,
+            instruction: "Arm this now with the Monitor tool (command above, persistent: true). Every comment, answer, requires_human change and block/unblock on this plan's cards will then arrive as a notification within seconds — do not poll for them. If the Monitor prints that it gave up or was ended, call plan_connect again and arm the new command.",
+        },
+    };
 }
-/** Add a goal, rule or caveat to the connected plan. */
+/** Add a goal, rule or caveat to the connected plan. `context` is sent only when given. */
 export async function planAddRecord(client, args) {
     return client.request({
         method: "POST",
         path: "/mine/records",
         basePath: PLANS_BASE_PATH,
-        body: { kind: args.kind, body: args.body },
+        body: {
+            kind: args.kind,
+            body: args.body,
+            ...(args.context === undefined ? {} : { context: args.context }),
+        },
     });
 }
 /** Add an existing card to the connected plan. */
@@ -813,7 +887,9 @@ export async function planGetRecord(client, args) {
  * `plan_get_record`; the server compares it against the row's current hash
  * and, on a mismatch, refuses the write ENTIRELY and fails loud with
  * `{ok: false, status: 409, body: {error: "stale_plan_record", currentHash,
- * currentBody}}` rather than overwriting whoever wrote in between.
+ * currentBody, currentContext}}` rather than overwriting whoever wrote in
+ * between. DX-2734: the hash covers body AND context, and `context` is sent
+ * only when given (omitted keeps the stored context, `null` clears it).
  * `currentBody` rides the SAME refusal — unlike the architecture document's
  * `stale_plan_architecture`, which carries only `currentHash` — so you can
  * merge and retry in ONE round trip without a second `plan_get_record` call.
@@ -825,7 +901,11 @@ export async function planUpdateRecord(client, args) {
         method: "PATCH",
         path: `/mine/records/${args.record_id}`,
         basePath: PLANS_BASE_PATH,
-        body: { body: args.body, content_hash: args.content_hash },
+        body: {
+            body: args.body,
+            content_hash: args.content_hash,
+            ...(args.context === undefined ? {} : { context: args.context }),
+        },
     });
 }
 /**

package/dist/index.js

@@ -74,8 +74,10 @@
  * agent reads `body.error` + structured fields to decide next action.
  * 5xx and network failures throw — never silently swallowed.
  */
+import { createRequire } from "node:module";
 import { basename } from "node:path";
 import { isEntrypointModule } from "./entrypoint.js";
+import { LISTEN_SUBCOMMAND, runListenCommand } from "./listen.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -161,6 +163,16 @@ function readSessionConfig() {
     const fallback = cwdName === "" ? `session ${id.slice(0, 8)}` : cwdName;
     return { id, title: readEnvOptional("DANX_SESSION_TITLE") ?? fallback };
 }
+/**
+ * This build's own npm spec. `plan_connect` hands out a `listen` command pinned to
+ * it, so the listener that runs is always the one written for the stream this
+ * server's dashboard speaks — never whatever `npx` happens to have cached.
+ * `package.json` sits one level above both `src/` (tsx) and `dist/` (the bin).
+ */
+const PACKAGE_SPEC = (() => {
+    const pkg = createRequire(import.meta.url)("../package.json");
+    return `${pkg.name}@${pkg.version}`;
+})();
 export const server = new McpServer({
     name: "danx-dashboard-mcp",
     version: "0.1.0",
@@ -298,7 +310,7 @@ server.tool("issue_get", "Fetch a single issue via GET /api/issues/:id. Board-sc
     ...boardField,
 }, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- issue_create ----------------
-server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-scoped; defaults to the dispatch\'s board. Pass `board` (a qualified id `<repo>:<slug>`) to create the card on another board (forwarded into body.board + ?board=; unknown board → 404). INVARIANT: type=Epic REQUIRES non-empty phase_children[] (epic-with-phases atomicity per DX-575) and the route atomically inserts the epic + every phase in ONE transaction. Non-Epic types REFUSE phase_children[] with 400. Status defaults to Review (no lifecycle timestamps stamped on create). parent_id optional. ac items take {title}; phase children inherit the new epic\'s id as parent_id. Optional list_id PLACES the card directly into a column in ONE call. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, emoji-tolerant — e.g. a queue name like "⚙️ Fulfillment Queue" or just "Fulfillment Queue") — the server resolves a name to its id.** The card lands DIRECTLY in that column with the matching lifecycle stamped automatically — a `ready`-type queue → ToDo, a `completed` list → Done, etc. **You do NOT need a separate issue_transition(ready) + issue_edit(list_id) afterward — just pass the queue name here and the card is created already in that column.** Omit list_id for the default (Review). NOT valid on type=Epic (Epic status derives from children) → 400. Unknown name/id → 400. **gate_decisions is REQUIRED whenever the board has any OPTIONAL quality gate for the card\'s type** (DX-1594): supply one `{gate, enabled, note}` per board-optional gate. The create FAILS CLOSED — a missing decision returns 400 `{error, required_gate_decisions:[...]}` enumerating exactly which gates to answer, so just retry with a decision for each listed gate. `required`/`disabled` board gates take no decision; a board with no optional gates needs no gate_decisions at all. **ALWAYS pass `triage_enabled` explicitly** (root card AND every phase_children[] entry): decide per card whether it should enter the automatic triage/dispatch pipeline — `true` only when auto-triage is expected without further human review; absent → false, the card is NEVER auto-triaged (explicit-only, reverting DX-1928 — auto-created cards must never silently enter the dispatch pipeline).', {
+server.tool("issue_create", 'Create a card via POST /api/issues on this dispatch\'s board, or another via `board` (`<repo>:<slug>`; unknown → 404). type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `gate_decisions` is REQUIRED when the board has an OPTIONAL quality gate for the card\'s type: a missing one fails closed with 400 `{error, required_gate_decisions:[...]}` naming each gate — retry with one `{gate, enabled, note}` per listed gate. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child: true only when it should enter automatic triage/dispatch without human review; absent → false.', {
     type: z.enum(ISSUE_TYPES),
     title: z.string().min(1).describe(TITLE_DESCRIBE),
     summary: z.string().min(1).optional().describe(SUMMARY_DESCRIBE),
@@ -315,7 +327,7 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
         effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
     }))
         .optional()
-        .describe('REQUIRED fail-closed quality-gate decisions (DX-1594 — replaces required_gates). One {gate, enabled, note} per board-OPTIONAL gate of the card\'s type: `enabled` answers whether the gate runs on this card, `note` records the rationale (persisted as the decision rationale, distinct from the reviewer verdict). The board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`): `required` runs always (NO decision — auto-on); `optional` REQUIRES a decision here (unanswered → the create 400s); `disabled` never runs (NO decision). Omit this only on a board with no optional gates; otherwise the 400 body\'s `required_gate_decisions` lists exactly which gates to answer — retry with {enabled, note} for each. A decision naming a non-optional gate is rejected 400. DX-1760: each entry also takes an OPTIONAL `effort_level` — a per-`(card, gate)` reviewer-rung override for a `plan-*` gate, persisted at seed time; omit for no override.'),
+        .describe("One {gate, enabled, note} per board-OPTIONAL gate of the card's type: `enabled` = does it run on this card, `note` = why. Board `required` gates always run and `disabled` never do; neither takes a decision (naming one → 400). Optional `effort_level` overrides a `plan-*` gate's reviewer rung."),
     phase_children: z
         .array(z.object({
         type: z.enum(NON_EPIC_TYPES),
@@ -336,21 +348,21 @@ server.tool("issue_create", 'Create a fresh card via POST /api/issues. Board-sco
             effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
         }))
             .optional()
-            .describe("Per-child fail-closed gate decisions — same shape + rule as the root gate_decisions (incl. the optional per-gate effort_level, DX-1760), resolved against THIS child's own type. Required when the child's type has board-optional gates."),
+            .describe("Same as the root gate_decisions, resolved against THIS child's type."),
         triage_enabled: z
             .boolean()
             .optional()
-            .describe("Per-child auto-triage opt-in (explicit-only, reverting DX-1928). ALWAYS pass explicitly per child — decide whether THIS child should enter the automatic triage pipeline. Absent → false (never auto-triaged). Never inherited from the root card."),
+            .describe("ALWAYS pass per child; absent → false (never auto-triaged). Not inherited from the root."),
     }))
         .optional(),
     triage_enabled: z
         .boolean()
         .optional()
-        .describe("DX-1895 (explicit-only — reverting DX-1928): per-card opt-in for the automatic triage dispatcher. ALWAYS pass this explicitly — decide per card whether auto-triage is expected. true = the card enters the automatic triage/dispatch pipeline without further human review; absent → false, the card is NEVER auto-triaged. Operator-directed POST /api/triage and direct issue_triage calls are NOT gated by this flag."),
+        .describe("ALWAYS pass explicitly. true = enters automatic triage/dispatch without further human review; absent → false. Operator POST /api/triage and issue_triage ignore it."),
     ...boardField,
 }, async (args) => jsonResult(await issueCreate(client, args, config.board)));
 // ---------------- issue_edit ----------------
-server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues/:id/edit. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type. ANY OTHER KEY (lifecycle timestamps, triage state, dependencies, retro, requires_human, blocked/dispatch gates) returns 400 with offending_keys[] and a pointer to the dedicated semantic handler — use issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro instead. TYPE (DX-2484): change the card\'s `type` via the `type` key — the route recomputes `dispatchable_derived` immediately when it changes. Changing type TO `Story`, `Bug`, or `Chore` makes the card eligible for autonomous pickup (subject to every other dispatch gate); changing it TO `Task` or a container (`Epic`/`Feature`) REMOVES that eligibility — a planning record or container is never dispatched, in ANY status. This is the way to promote a planning item into real work. PRIORITY (DX-1532): set card priority via the `priority` key — a tier WORD ("lowest"/"low"/"medium"/"high"/"very_high"/"critical", resolved to the tier midpoint) OR a raw number in [0,6). This is the ONLY way to change priority: the numeric `issues.priority` column is what the Trello priority label AND the dashboard badge read — editing a "Priority: <x>" line in the DESCRIPTION changes nothing downstream (a silent false-positive). To honor a "set priority" request, write `priority` here, do NOT edit description prose. CHECKLISTS (DX-1290, extended DX-2653): a card carries 0..N named checklists, each item ONE status `incomplete|failing|passing|cancelled|deferred` (terminal = passing|cancelled|deferred). `deferred` is the honest disposition for a criterion whose work is done but names a real-world/post-deploy check still outstanding — REQUIRES a non-empty `detail`; a criterion marked with the `📡` post-deploy-evidence prefix can never be `passing` at all (refused 409 at completion, resolve to `deferred` instead). `ac` is the 2-state CONVENIENCE onto the default "Acceptance Criteria" checklist (checked:true ↔ passing, false ↔ incomplete BY DEFAULT — pass `status` alongside `checked` to reach `cancelled`/`failing`/`deferred` instead) — each incoming item is DIFFED against that checklist\'s current live items (matched by the optional `check_item_id`, else by exact title) so an unchanged item keeps its id; only changed items are updated in place, new titles are inserted, and items missing from the array are removed. `checklists` is the GENERIC wholesale write path: it REPLACES every named checklist on the card with full status control (each `{name, items:[{label, detail?, status}]}`) — use it to author named checklists like "Feature Tests". Send EITHER `ac` OR `checklists`, NOT both (400). list_id (DX-1192 / DX-1200) PINS the card to a specific board list. **Pass EITHER a board_lists id OR the list\'s display NAME (case-insensitive, e.g. a queue name like "⚙️ Fulfillment Queue") — the server resolves a name to its id.** Its type MUST match the card\'s CURRENT derived-status list-type (so to route a ToDo card into a `ready`-type queue, ready it first; mismatch / unknown name or id → 400); pass null to clear the pin (back to default-for-type).', {
+server.tool("issue_edit", 'Patch a card via PATCH /api/issues/:id/edit. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type. Any other key (lifecycle, triage, dependencies, retro, requires_human, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_requires_human / issue_retro. `type`: Story/Bug/Chore makes a card eligible for autonomous pickup; Task or a container (Epic/Feature) removes that eligibility — how a planning item becomes work. `priority` (a tier word or a number) is the ONLY way to set priority; a "Priority:" line in the description changes nothing. CHECKLISTS: each item has one status `incomplete|failing|passing|cancelled|deferred`; `deferred` (work done, a real-world/post-deploy check outstanding) REQUIRES `detail`, and a `📡`-prefixed item can never be `passing`. `ac` edits the default "Acceptance Criteria" checklist (items matched by check_item_id, else exact title); `checklists` REPLACES every named checklist with full status control (`{name, items:[{label, detail?, status}]}`). Send `ac` OR `checklists`, not both (400). `list_id` pins the card to a list by id or display NAME; its type must match the card\'s current derived status (400 otherwise — ready a card before pinning it to a `ready` queue); null clears the pin.', {
     id: z.string().min(1),
     title: z.string().min(1).optional().describe(TITLE_DESCRIBE),
     summary: z
@@ -363,7 +375,7 @@ server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues
     type: z
         .enum(ISSUE_TYPES)
         .optional()
-        .describe("DX-2484 — change the card's type. Changing TO `Story`, `Bug`, or `Chore` makes the card eligible for autonomous pickup (dispatchable); changing TO `Task` or a container (`Epic`/`Feature`) removes that eligibility — a planning record or container is never dispatched, in ANY status. The route recomputes `dispatchable_derived` immediately."),
+        .describe("Story/Bug/Chore = dispatchable; Task/Epic/Feature = never dispatched, in any status."),
     ac: z
         .array(z.object({
         title: z.string(),
@@ -371,7 +383,7 @@ server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues
         status: z
             .enum(CHECKLIST_ITEM_STATUSES)
             .optional()
-            .describe('DX-2653 — optional full-status override. Omitted → derived from `checked` (`true`→passing, `false`→incomplete), same as before. Present → used verbatim, reaching `cancelled`/`failing`/`deferred` from this everyday convenience path instead of only via `checklists` or `issue_checklist`. `deferred` REQUIRES a non-empty `detail` naming the outstanding real-world/post-deploy check — a marker-prefixed ("📡") item can never be `passing` at all (refused 409 at completion).'),
+            .describe("Optional full status; omitted → from `checked`. `deferred` REQUIRES a non-empty `detail`; a 📡 item can never be `passing`."),
         detail: z
             .string()
             .optional()
@@ -379,10 +391,10 @@ server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues
         check_item_id: z
             .union([z.string(), z.number()])
             .optional()
-            .describe("OPTIONAL — the item's real checklist-item id (the same value issue_get returns as ac[].check_item_id). Each incoming item is correlated to the checklist's current live rows by this id when supplied, else by an exact title match. An item that matches and is byte-identical (title + checked/status/detail) to its stored row is left untouched and KEEPS its id; only items that actually changed are updated in place, a title with no match is inserted fresh, and a live row missing from this array is removed. Supply check_item_id only to disambiguate two AC items that share an identical title — every other call can omit it and rely on title matching."),
+            .describe("Optional id from issue_get's ac[].check_item_id. Only needed to tell apart two items with identical titles; otherwise items match by title."),
     }))
         .optional()
-        .describe("The 2-state convenience onto the default Acceptance Criteria checklist (checked:true ↔ passing, false ↔ incomplete BY DEFAULT — pass `status` to reach `cancelled`/`failing`/`deferred` instead). Diffed against the checklist's current live items — unchanged items keep their id, changed ones are updated in place, new titles are inserted, and existing items missing from this array are removed. See check_item_id below for disambiguating duplicate titles, and status/detail below for the full status vocabulary."),
+        .describe("The default Acceptance Criteria checklist: checked true → passing, false → incomplete, or pass `status`. Diffed against live items — unchanged items keep their id, new titles are inserted, missing ones removed."),
     checklists: z
         .array(z.object({
         name: z.string().min(1),
@@ -398,16 +410,16 @@ server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues
     priority: z
         .union([z.enum(PRIORITY_TIER_WORDS), z.number()])
         .optional()
-        .describe('Card priority (DX-1532). A tier WORD ("lowest"/"low"/"medium"/"high"/"very_high"/"critical") resolved to the tier midpoint, OR a raw number in [0,6). Writes the numeric `issues.priority` column the Trello label + dashboard badge read — set priority HERE, never via description prose (which no system reads for priority).'),
+        .describe('A tier word ("lowest"…"critical", resolved to the tier midpoint) or a number in [0,6). The only way to set priority.'),
     list_id: z.string().min(1).nullable().optional(),
     triage_enabled: z
         .boolean()
         .optional()
-        .describe("DX-1895 (explicit-only — reverting DX-1928): per-card opt-in for the DX-1886 auto-triage dispatcher. Default false — the create path stamps false unless the creator explicitly set it, so this edit field is the only post-create way to opt a card in or out. false = the automatic dispatcher trigger never selects this card, even when every other eligibility condition holds. This flag gates ONLY the automatic dispatcher; operator-directed POST /api/triage and direct issue_triage calls remain flag-independent."),
+        .describe("Per-card opt-in to the automatic triage dispatcher (default false = never auto-selected). Operator POST /api/triage and issue_triage ignore it."),
     ...boardField,
 }, async (args) => jsonResult(await issueEdit(client, args)));
 // ---------------- issue_transition ----------------
-server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issues/:id/transition. **THIS IS THE ONLY WAY TO MOVE A CARD'S LIFECYCLE STATE** — DX-835 separated card lifecycle (this tool) from dispatch finalization (`mcp__danxbot__danxbot_complete`). The worker no longer infers card moves from `danxbot_complete.status`; agents that want the card to move MUST call this tool BEFORE calling `danxbot_complete`. Actions: ready (Review→ToDo), pickup (ToDo→In Progress — server checks every dispatch gate: ready_at, blocked_at, requires_human_reason, depends_on partners terminal, conflict_on partners idle; refuses 409 with failed_gate naming the cause; pass manual:true for OPERATOR-SESSION self-pickup — stamps dispatch_kind 'manual', bypasses every card-flow gate except terminal/deleted/already-dispatched, and the worker NEVER auto-transitions the card: no orphan-heal rollback, no Epic auto-rollup — use this whenever the work happens in YOUR current session rather than a worker dispatch, DX-946), rollback_pickup, **complete** (stamps completed_at — moves card to Done; this is YOUR explicit decision, not a side effect of danxbot_complete; REFUSES 409 on Epic if any phase child non-terminal — see non_terminal_phases[]; ALSO refuses 409 with failed_gate 'quality_gate_post' + failed_post_gates[] while any required POST quality gate row != pass — DX-1177), cancel (stamps cancelled_at — terminal), **block** (requires non-empty reason — stamps blocked_at + blocked_reason + clears dispatch; USE THIS when the CARD itself cannot proceed without human intervention; distinct from env-fault dispatch failures which use `danxbot_complete({status:'failed'})`), unblock, archive (parks to Backlog, clears ready_at), reopen (terminal→active, clears completed_at/cancelled_at/archived_at). Terminal cards refuse every action except reopen. Ladder timestamps preserved — forward stamps never clear earlier ones (CLAUDE.md Core Principle 2). **DX-2282 — every path into In Progress now requires an identified claimer.** For `manual:true` pickup called from a DISPATCHED-AGENT session (this MCP tool, bearer = your dispatch token): you MUST pass `assigned_agent` set to YOUR resolved agent/profile name — omitting it, or passing the shared dispatch-token identity itself, is refused 409 `assigned_agent (required, distinguishing)`. A genuine human dashboard session may omit it (auto-resolved from the real logged-in user). Every pickup flavor (work/gate/manual) is refused 409 `assigned_agent (required)` if it would otherwise leave the card with no owner at all. **A manual pickup can now also be refused 409 `failed_gate: \"dispatch_id\"` — \"pickup refused — card claimed by another actor between read and write\" — when it loses a genuine race against a concurrent manual pickup of the same idle card.** Before this, two overlapping manual pickups of the same card could both return 200: the second write silently overwrote the first winner's claim with no error and no distinguishing status code. The claiming write is now atomic (fenced on `dispatch_id IS NULL`), so the loser gets this 409 instead of a false success — on this response, do NOT retry blindly; re-check the card's current `assigned_agent`/`dispatch_id` first, since another actor already has it. **A successful `block` returns a `solutions_reminder` beside the envelope** — `{solution_count, instruction}` — because blocking stops the card for a human: before you stop, EVERY viable solution must be listed on the card with issue_solution (the operator answers by picking one). A count of zero means you have listed none.", {
+server.tool("issue_transition", "Move a card's lifecycle via POST /api/issues/:id/transition — the ONLY way to; `danxbot_complete` never moves a card, so call this BEFORE it. Actions: ready (Review→ToDo); pickup (ToDo→In Progress; checks every dispatch gate — ready, blocked, requires_human, depends_on terminal, conflict_on idle — and refuses 409 with failed_gate naming the cause; `manual:true` is an operator-session self-pickup that bypasses card-flow gates and is never auto-rolled-back: use it when the work happens in YOUR session); rollback_pickup; complete (your explicit decision; refuses 409 on an Epic with non-terminal children, non_terminal_phases[], or while a required POST quality gate is not pass, failed_gate 'quality_gate_post' + failed_post_gates[]); cancel (terminal); block (non-empty reason; the CARD needs a human — env faults use `danxbot_complete({status:'failed'})` instead); unblock; archive (to Backlog, clears ready_at); reopen (terminal→active). Terminal cards refuse everything but reopen; forward stamps never clear earlier ones. Every path into In Progress needs an identified claimer: a dispatched agent's manual pickup MUST pass `assigned_agent` = your agent/profile name (409 otherwise). A manual pickup that loses a race is refused 409 `failed_gate: \"dispatch_id\"` — re-read the card's assigned_agent/dispatch_id, never retry blindly. A successful block returns `solutions_reminder: {solution_count, instruction}`: before stopping, list EVERY viable solution with issue_solution; zero means you listed none.", {
     id: z.string().min(1),
     action: z.enum(TRANSITION_ACTIONS),
     reason: z.string().optional(),
@@ -418,7 +430,7 @@ server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issu
         .string()
         .min(1)
         .optional()
-        .describe("DX-2282 — REQUIRED for a manual:true pickup called by a dispatched agent (this MCP tool): your resolved agent/profile name, identifying YOU as the claimer. Never supply the generic shared dispatch-token identity — that is refused. Optional for a human dashboard session (auto-resolved from the real logged-in user). Ignored for every other action."),
+        .describe("Required for a dispatched agent's manual:true pickup: your agent/profile name, never the shared dispatch-token identity. Optional for a human session; ignored by other actions."),
     ...boardField,
 }, async (args) => jsonResult(await issueTransition(client, args)));
 // ---------------- issue_triage ----------------
@@ -501,7 +513,7 @@ server.tool("issue_requires_human", "Set or clear the requires_human dispatch ga
     ...boardField,
 }, async (args) => jsonResult(await issueRequiresHuman(client, args)));
 // ---------------- issue_quality_gate ----------------
-server.tool("issue_quality_gate", "Toggle a single card's per-card quality-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the SAME write the dashboard drawer's Quality Gates tab performs (DX-1181). This is the ONLY post-create way to mark a gate required/not-required: `issue_create` carries `gate_decisions` at birth, and `issue_edit` REJECTS gate keys (400 offending_keys) — without this tool a card created without a gate can never have it turned on by an agent. `gate` is a registry name: `plan-dependency` | `plan-architecture` | `plan-tdd` | `code-test-quality` | `code-architecture` | `code-quality` (the PRE/plan- gates run before the work dispatch; the POST/code- gates block issue_transition complete). Unknown gate → 400 (never a silent no-op); a card with no seeded row for a registered gate → 500 (canonical corruption). NOTE board requirement is TRI-STATE per gate (`board_quality_gate_settings.default_state`, the Agents-tab surface), NOT a binary on/off: `required` = gate always runs (this flag irrelevant); `optional` = gate runs WHEN this per-card flag is true (per-card opt-in — `optional` is ENABLED, NOT off); `disabled` = never runs (this flag inert). So flipping `required:true` here LAUNCHES the gate when the board state is `required` OR `optional`; it is inert ONLY when the board state is `disabled`. Do not read `optional` as off. (Source of truth: `isGateEffectivelyRequired` in `src/issues/quality-gates/read.ts`.) DX-1760: optionally pass `effort_level` — a per-`(card, gate)` reviewer-rung override for a `plan-*` gate, written alongside `required`; omit to leave it untouched, pass `null` to clear a prior override. **The write itself ALWAYS succeeds and is echoed back** — the response is `{issue, applied: true, effective, reason}`, not just `{issue}`: `effective` is what `isGateEffectivelyRequired` resolves to for this (card, gate) right AFTER the write (accounts for the board tri-state above), and `reason` is `null` when `effective` matches the `required` value you just sent, or a plain-English explanation when the board's `required`/`disabled` state overrode it — READ `effective`/`reason`, not just the 200, to know whether this call actually changed whether the gate runs. Board-scoped; pass `board` (`<repo>:<slug>`) to target another board.", {
+server.tool("issue_quality_gate", "Set one card's per-gate `required` flag via POST /api/issues/:id/quality-gates/:gate {required} — the only post-create way (issue_create takes gate_decisions; issue_edit refuses gate keys). PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate → 400. The board state per gate is tri-state: `required` always runs, `optional` runs WHEN this flag is true (optional is NOT off), `disabled` never runs. Optional `effort_level` overrides a `plan-*` gate's reviewer rung (null clears it). The write always succeeds and returns `{issue, applied: true, effective, reason}` — read `effective` (does the gate now run) and `reason` (why the board overrode your value), not just the 200. Pass `board` to target another board.", {
     id: z.string().min(1),
     gate: z.enum([
         "plan-dependency",
@@ -619,8 +631,8 @@ server.tool("brief_set_page", 'Write one Brief page via PUT /api/brief/page?slug
 // plan id — and it can only ever bind the caller's own session. `plan_create`
 // also takes no plan id, but for a different reason: it MAKES a plan rather
 // than acting on one, so there is no existing plan for an id to name yet.
-server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped: a plan is a named, dated set of cards an operator assembled by hand, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). NOTE this is NOT the board Brief (`brief_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
-server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture document, the sessions working on it, and your own session state. One call, not five. Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. Returns `{plan, cards, boards, records: {goal: [], rule: [], caveat: []}, architecture: {content, contentHash, updatedAt, updatedBy}, sessions, session}`. ALWAYS `plan_get` immediately before `plan_set_architecture` and pass the returned `architecture.contentHash` back as `base_hash`.", {
+server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped: a plan is a named, dated set of cards an operator assembled by hand, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session, sessionListenerAttached}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). `sessionListenerAttached` says whether your event listener is running: `false` while connected to a plan means you will NOT hear about its cards — call `plan_connect` again and arm the Monitor it returns. NOTE this is NOT the board Brief (`brief_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
+server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture document, the sessions working on it, and your own session state. One call, not five. Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. Returns `{plan, cards, boards, records: {goal, rule, caveat} (each `[{id, ref, body, context, contentHash}]` — `context` is markdown detail or null), architecture: {content, contentHash, updatedAt, updatedBy}, sessions, session, sessionListenerAttached}` — `sessionListenerAttached: false` while connected means your event listener is not running; call `plan_connect` again and arm the Monitor it returns. ALWAYS `plan_get` immediately before `plan_set_architecture` and pass the returned `architecture.contentHash` back as `base_hash`.", {
     plan_id: z
         .number()
         .int()
@@ -631,30 +643,30 @@ server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — it
 server.tool("plan_create", "Create a new, empty plan via POST /api/plans (DX-2531). GLOBAL — a plan is not board-scoped, and this call adds no cards, no records, and no architecture document; it does NOT connect any session to the new plan (call `plan_connect` separately, exactly as adding a card to a plan is its own separate step). Returns `{ok, status, body: {plan: {id, name, createdAt}}}`. Use the returned `plan.id` with `plan_connect` to start working on it, or with `plan_get({plan_id})` to browse it.", {
     name: z.string().min(1).describe("The plan's name — shown in the Plans list."),
 }, async (args) => jsonResult(await planCreate(client, args)));
-server.tool("plan_connect", "Connect THIS session to a plan via POST /api/plan-sessions/me/plan (DX-2683) — the same binding the operator's Connect action writes, through the same server-side path. A session is connected to AT MOST ONE plan (enforced by the schema, not by convention); connecting while already on another plan MOVES you, and the response says which plan you left: `{ok, status, body: {session, movedFrom: {id, name} | null}}`. `movedFrom: null` means you were on no plan, or already on this one. It can only ever bind your OWN session — `me` is resolved from the session id this server forwards, never from anything you pass. After this, every plan WRITE tool acts on this plan, and no plan id is accepted anywhere.", {
+server.tool("plan_connect", "Connect THIS session to a plan via POST /api/plan-sessions/me/plan (DX-2683) — the same binding the operator's Connect action writes, through the same server-side path. A session is connected to AT MOST ONE plan (enforced by the schema, not by convention); connecting while already on another plan MOVES you, and the response says which plan you left: `{ok, status, body: {session, movedFrom: {id, name} | null}}`. `movedFrom: null` means you were on no plan, or already on this one. It can only ever bind your OWN session — `me` is resolved from the session id this server forwards, never from anything you pass. After this, every plan WRITE tool acts on this plan, and no plan id is accepted anywhere. THE REPLY ALSO CARRIES `listener: {command, persistent: true, instruction}` — arm it IMMEDIATELY with the Monitor tool (`command` as given, `persistent: true`): from then on every comment, answer, requires_human change and block/unblock on this plan's cards arrives as a notification line like `[DX-8 \"Title\" repo:board] newms87 answered: chose \"Pause E2E\" — note: \"…\"`. Never poll for these. The command carries a narrow stream ticket, not a credential; calling plan_connect again (same plan is fine) issues a new one and ends the old listener, which is how you re-arm after a session restart or after the Monitor reports it gave up. If the ticket cannot be issued the call fails with `listener_not_armed` even though the connect itself happened.", {
     plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
-}, async (args) => jsonResult(await planConnect(client, args)));
-server.tool("plan_add_record", "Add a GOAL, RULE or CAVEAT to the plan this session is connected to, via POST /api/plans/mine/records (DX-2683). A goal is what the plan is FOR (the outcome the work is measured against — not a task). A rule is what must HOLD while it is worked. A caveat is what is known to be AWKWARD — the fact that will surprise the next person. Each gets a permanent short reference within the plan (`G-1`, `R-4`, `CAV-12`) allocated by the server, which is how a person cites it in a card or a commit. TAKES NO PLAN ID: the plan is resolved from your connected session, so you cannot write a plan you are not connected to. Not connected → `{error: \"session_not_connected\"}`; call `plan_connect` first. Returns the new record plus that kind's full list.", {
-    kind: z
-        .enum(["goal", "rule", "caveat"])
-        .describe("Which standing record this is. Determines the reference prefix."),
-    body: z.string().min(1).describe("The record's text. Plain text, not markdown."),
+}, async (args) => jsonResult(await planConnect(client, args, { baseUrl: config.baseUrl, packageSpec: PACKAGE_SPEC })));
+server.tool("plan_add_record", "Add a goal, rule or caveat to your connected plan (POST /api/plans/mine/records). A GOAL is an outcome the work is measured against. A RULE is a constraint that must hold while it is worked. A CAVEAT is a lasting trade-off or limitation of the ARCHITECTURE — never progress, status or a session note (those are comments on the card). `body` is ONE plain statement of at most 250 characters; the evidence, history and detail go in `context` (markdown). An overlong body is refused with a 400 naming its length. The server allocates a permanent reference (`G-1`, `R-4`, `CAV-12`). Takes no plan id; `session_not_connected` → `plan_connect` first. Returns the record plus that kind's list.", {
+    kind: z.enum(["goal", "rule", "caveat"]).describe("goal = outcome, rule = constraint, caveat = architecture trade-off."),
+    body: z.string().min(1).describe("One plain statement, at most 250 characters. Details go in `context`."),
+    context: z.string().optional().describe("Markdown detail behind the statement: evidence, history, examples."),
 }, async (args) => jsonResult(await planAddRecord(client, args)));
-server.tool("plan_get_record", "Read ONE goal/rule/caveat of the plan this session is connected to, via GET /api/plans/mine/records/:rid (DX-2681 follow-up). Useful for an ordinary targeted read (skip pulling the whole plan via `plan_get` just to see one record) and for conflict recovery after a 409 `stale_plan_record` from `plan_update_record`/`plan_delete_record` — though that refusal already carries `currentBody`, so a second read is rarely needed for that specific case. TAKES NO PLAN ID: the plan is resolved from your connected session, same as `plan_add_record`. Not connected → `{error: \"session_not_connected\"}`. Unknown or another plan's record id → 404. Returns `{record: {id, planId, kind, refNum, ref, body, contentHash, createdAt, updatedAt}}`.", {
+server.tool("plan_get_record", "Read one goal/rule/caveat of your connected plan (GET /api/plans/mine/records/:rid) without pulling the whole plan. Takes no plan id; an unknown or another plan's record id → 404. Returns `{record: {id, planId, kind, refNum, ref, body, context, contentHash, createdAt, updatedAt}}` — `context` is the markdown detail, or null.", {
     record_id: z.number().int().positive().describe("A record id, from `plan_add_record`, `plan_get` or `plan_get_record` itself."),
 }, async (args) => jsonResult(await planGetRecord(client, args)));
-server.tool("plan_update_record", 'Edit a goal/rule/caveat of the plan this session is connected to, via PATCH /api/plans/mine/records/:rid (DX-2681 follow-up). The reference (`G-1`, `R-4`, `CAV-12`) NEVER moves — only the text changes. `content_hash` MUST be the record\'s `contentHash` from the immediately-prior `plan_get`/`plan_get_record`/`plan_add_record`; the server compares it against the row\'s current hash and, on a mismatch, refuses the write ENTIRELY (nothing is changed) and fails loud with `{ok: false, body: {error: "stale_plan_record", currentHash, currentBody}}` rather than overwriting whoever wrote in between. `currentBody` rides that SAME refusal — unlike the architecture document\'s `stale_plan_architecture`, which carries only `currentHash` — so you can merge and retry in ONE round trip, no second read needed. On a refusal: merge your edit into `currentBody`, and retry with `content_hash: currentHash` — never retry blindly against the old hash. TAKES NO PLAN ID: the plan is resolved from your connected session. Not connected → `{error: "session_not_connected"}`. Returns the updated record plus that kind\'s full list.', {
+server.tool("plan_update_record", 'Edit a goal/rule/caveat of your connected plan (PATCH /api/plans/mine/records/:rid). The reference never moves. `body` stays ONE plain statement of at most 250 characters (400 otherwise); detail belongs in markdown `context`. `content_hash` must be the record\'s `contentHash` from your last read, and covers body AND context. On a mismatch nothing is written and you get `{error: "stale_plan_record", currentHash, currentBody, currentContext}`: merge into those and retry with `content_hash: currentHash`, never blindly. Takes no plan id. Returns the record plus that kind\'s list.', {
     record_id: z.number().int().positive().describe("The record id to edit."),
-    content_hash: z
+    content_hash: z.string().describe("The record's `contentHash` from your last read. Required."),
+    body: z.string().min(1).describe("The new statement, at most 250 characters. Plain text."),
+    context: z
         .string()
-        .describe("The record's `contentHash` from the immediately-prior read. Required — an absent hash is not read as a wildcard."),
-    body: z.string().min(1).describe("The record's new text, replacing what is stored. Plain text, not markdown."),
+        .nullable()
+        .optional()
+        .describe("New markdown detail. Omit to keep the stored context; null clears it."),
 }, async (args) => jsonResult(await planUpdateRecord(client, args)));
-server.tool("plan_delete_record", 'Soft-delete a goal/rule/caveat of the plan this session is connected to, via DELETE /api/plans/mine/records/:rid (DX-2681 follow-up). Its reference (`G-1`, `R-4`, `CAV-12`) is retired PERMANENTLY and never reused by a later record of the same kind. `content_hash` MUST be the record\'s `contentHash` from the immediately-prior `plan_get`/`plan_get_record`/`plan_add_record`; a stale hash refuses the delete ENTIRELY (nothing is removed) with the same `{ok: false, body: {error: "stale_plan_record", currentHash, currentBody}}` shape `plan_update_record` uses — merge and retry with `content_hash: currentHash` rather than retrying blindly. TAKES NO PLAN ID: the plan is resolved from your connected session. Not connected → `{error: "session_not_connected"}`. Unknown, foreign, or already-deleted record id → 404. Returns that kind\'s remaining list.', {
+server.tool("plan_delete_record", 'Soft-delete a goal/rule/caveat of your connected plan (DELETE /api/plans/mine/records/:rid). Its reference is retired permanently, never reused. `content_hash` must be the record\'s `contentHash` from your last read; a stale hash deletes nothing and returns `{error: "stale_plan_record", currentHash, currentBody, currentContext}`. Takes no plan id. Unknown or already-deleted id → 404. Returns that kind\'s remaining list.', {
     record_id: z.number().int().positive().describe("The record id to delete."),
-    content_hash: z
-        .string()
-        .describe("The record's `contentHash` from the immediately-prior read. Required — an absent hash is not read as a wildcard."),
+    content_hash: z.string().describe("The record's `contentHash` from your last read. Required."),
 }, async (args) => jsonResult(await planDeleteRecord(client, args)));
 server.tool("plan_add_card", "Add an existing card to the plan this session is connected to, via POST /api/plans/mine/cards (DX-2683). The card may live on ANY board — that is what a plan is for. Idempotent: re-adding a card already on the plan is a no-op, not an error, and a card may sit in several plans at once. This adds MEMBERSHIP only; it never edits the card. TAKES NO PLAN ID: the plan is resolved from your connected session. Not connected → `{error: \"session_not_connected\"}`. Unknown card → 404. Returns the plan's full member list.", {
     card_id: z.string().min(1).describe("An existing card id, e.g. `DX-2683`."),
@@ -678,9 +690,28 @@ async function main() {
 // schemas can be introspected without spawning a dispatch. The check is
 // symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
 // spawns, not just a direct `node dist/index.js`.
+//
+// `listen` is the one subcommand: the session event listener `plan_connect`
+// tells the agent to arm as a Monitor. It never boots the MCP server and reads
+// none of the MCP env — its whole configuration is its two flags. Any OTHER
+// argument is refused rather than ignored, so a typo cannot silently start an
+// MCP server on stdio where a listener was meant to run.
 if (isEntrypointModule(import.meta.url, process.argv[1])) {
-    main().catch((err) => {
-        console.error(`[danx-dashboard-mcp] fatal: ${err.message}`);
-        process.exit(1);
-    });
+    const [subcommand, ...rest] = process.argv.slice(2);
+    if (subcommand === LISTEN_SUBCOMMAND) {
+        runListenCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] listen fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
+    else if (subcommand !== undefined) {
+        console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only one is "${LISTEN_SUBCOMMAND}")`);
+        process.exit(2);
+    }
+    else {
+        main().catch((err) => {
+            console.error(`[danx-dashboard-mcp] fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
 }

package/dist/listen.js

@@ -0,0 +1,278 @@
+/**
+ * `danx-dashboard-mcp listen --stream <url> --ticket <ticket> --lease-ms <ms>` —
+ * a working session's event listener.
+ *
+ * WHY IT EXISTS. A Claude Code session cannot be interrupted from outside, but
+ * its Monitor tool runs a background command and turns every line that command
+ * prints into a notification that wakes the session. This command is that
+ * background process: it holds the dashboard's session event stream open and
+ * prints ONE line per event on the plan the session is connected to — a comment,
+ * an answer, a `requires_human` change, a block — so the operator's answer
+ * reaches the agent within seconds, with no polling anywhere.
+ *
+ * THE OUTPUT CONTRACT, BECAUSE EVERY LINE WAKES THE AGENT:
+ *   - exactly one line per event, written the moment it arrives;
+ *   - nothing for keep-alives, the connect marker, or a successful reconnect;
+ *   - one line for an event it cannot read (never silence);
+ *   - one final line, and exit, only when it gives up or the dashboard ends it.
+ *
+ * RECONNECT. The stream drops whenever the dashboard restarts, and can also die
+ * silently (sleep, NAT, proxy). A read-idle timeout of three missed keep-alives
+ * turns silent death into a drop. Retries use capped exponential backoff and send
+ * `Last-Event-ID`; the dashboard replays what was missed (with a small overlap)
+ * and an id already printed is never printed twice. The backoff only resets once
+ * a connection proves healthy — it delivered an event, or stayed up past one
+ * keep-alive — so a dashboard that admits and immediately drops is not hammered.
+ * The listener gives up once it has gone `--lease-ms` without a healthy
+ * connection (past that the ticket cannot be admitted anyway), or at once when
+ * the ticket is refused.
+ *
+ * Everything server-specific — the stream URL and the lease — arrives as flags
+ * from `plan_connect`, which read them off the dashboard's own ticket response.
+ * Only the event shape is hand-copied from the dashboard's `IssueActivityEvent`
+ * (`src/issues/db/issue-activity.ts`); this published package cannot import
+ * danxbot source.
+ */
+export const LISTEN_SUBCOMMAND = "listen";
+export const INITIAL_BACKOFF_MS = 1_000;
+export const MAX_BACKOFF_MS = 30_000;
+/** Three of the dashboard's 15 s keep-alives without a byte means the connection is dead. */
+export const READ_IDLE_TIMEOUT_MS = 45_000;
+/** A connection that stays up this long has proven the dashboard healthy. */
+export const HEALTHY_CONNECTION_MS = 20_000;
+/** How many printed event ids the duplicate guard remembers — well past the replay overlap. */
+const PRINTED_ID_MEMORY = 1_000;
+const LINE_PREFIX = "[danx-dashboard listen]";
+const REARM = "Call plan_connect again and arm the Monitor it returns to keep receiving this plan's events.";
+const USAGE = `usage: danx-dashboard-mcp ${LISTEN_SUBCOMMAND} --stream <stream-url> --ticket <ticket> --lease-ms <ms>`;
+/** Parse the three required flags; anything else is refused. */
+export function parseListenArgs(argv) {
+    const values = new Map();
+    for (let i = 0; i < argv.length; i += 2) {
+        const flag = argv[i];
+        const value = argv[i + 1];
+        if (!["--stream", "--ticket", "--lease-ms"].includes(flag) || value === undefined || value === "") {
+            throw new Error(USAGE);
+        }
+        values.set(flag, value);
+    }
+    const streamUrl = values.get("--stream");
+    const ticket = values.get("--ticket");
+    const leaseMs = Number(values.get("--lease-ms"));
+    if (!streamUrl || !ticket || !Number.isSafeInteger(leaseMs) || leaseMs <= 0)
+        throw new Error(USAGE);
+    return { streamUrl, ticket, leaseMs };
+}
+function quoted(value) {
+    return `"${value.text}${value.truncated ? "…" : ""}"`;
+}
+function describe(event) {
+    const d = event.detail;
+    switch (event.kind) {
+        case "comment_added":
+            return `${event.actor} commented: ${quoted(d.excerpt)}`;
+        case "solution_answered": {
+            const solution = d.solution;
+            if (solution === null)
+                return `${event.actor} answered: ${quoted(d.freeform)}`;
+            const note = solution.note === null ? "" : ` — note: ${quoted(solution.note)}`;
+            return `${event.actor} answered: chose "${solution.title}"${note}`;
+        }
+        case "requires_human_set":
+            return `${event.actor} set requires_human: ${quoted(d.reason)}`;
+        case "requires_human_cleared":
+            return `${event.actor} cleared requires_human`;
+        case "blocked":
+            return `${event.actor} blocked the card: ${quoted(d.reason)}`;
+        case "unblocked":
+            return `${event.actor} unblocked the card`;
+        default:
+            // A kind newer than this listener still produces a line: an event the
+            // agent is never told about is exactly the failure this command prevents.
+            return `${event.actor}: ${event.kind}`;
+    }
+}
+/** The one notification line for an event. Always a single line; throws on a malformed event. */
+export function formatActivityLine(event) {
+    return `[${event.cardId} "${event.cardTitle}" ${event.boardId}] ${describe(event)}`.replace(/\s+/g, " ");
+}
+/**
+ * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
+ * field-less blocks produce no message, which is what keeps them off stdout.
+ */
+export class SseParser {
+    buffer = "";
+    push(chunk) {
+        this.buffer += chunk.replace(/\r\n?/g, "\n");
+        const messages = [];
+        let boundary = this.buffer.indexOf("\n\n");
+        while (boundary !== -1) {
+            const message = parseBlock(this.buffer.slice(0, boundary));
+            this.buffer = this.buffer.slice(boundary + 2);
+            if (message !== null)
+                messages.push(message);
+            boundary = this.buffer.indexOf("\n\n");
+        }
+        return messages;
+    }
+}
+function parseBlock(block) {
+    let id = null;
+    let event = "message";
+    const data = [];
+    let sawField = false;
+    for (const line of block.split("\n")) {
+        if (line === "" || line.startsWith(":"))
+            continue;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        const value = colon === -1 ? "" : line.slice(colon + 1).replace(/^ /, "");
+        sawField = true;
+        if (field === "id")
+            id = value;
+        else if (field === "event")
+            event = value;
+        else if (field === "data")
+            data.push(value);
+    }
+    return sawField ? { id, event, data: data.join("\n") } : null;
+}
+/** Statuses that describe the moment, not the ticket — retry them. */
+const RETRYABLE_CLIENT_STATUSES = new Set([408, 429]);
+/**
+ * Run until the dashboard ends the stream or the listener gives up. Returns the
+ * exit code: 0 when a newer listener took over, 1 when revoked, refused, or
+ * given up.
+ */
+export async function runListener(options, deps) {
+    const printed = new Set();
+    let lastEventId = null;
+    let unhealthySince = null;
+    let attempt = 0;
+    const remember = (id) => {
+        printed.add(id);
+        if (printed.size > PRINTED_ID_MEMORY)
+            printed.delete(printed.values().next().value);
+        lastEventId = lastEventId === null ? id : Math.max(lastEventId, id);
+    };
+    const handle = (message) => {
+        if (message.event === "end") {
+            const reason = JSON.parse(message.data).reason;
+            return { kind: "ended", reason: typeof reason === "string" ? reason : "unknown" };
+        }
+        if (message.event !== "activity")
+            return null;
+        const id = Number(message.id);
+        if (Number.isSafeInteger(id) && printed.has(id))
+            return null;
+        try {
+            deps.write(formatActivityLine(JSON.parse(message.data)));
+        }
+        catch (err) {
+            // Never silence, and never a reconnect loop on the same bad event: say so
+            // in one line and move past it.
+            deps.write(`${LINE_PREFIX} could not read event ${message.id ?? "(no id)"} (${err.message}): ` +
+                `${message.data.slice(0, 300)}`.replace(/\s+/g, " "));
+        }
+        if (Number.isSafeInteger(id))
+            remember(id);
+        return null;
+    };
+    const connectOnce = async () => {
+        const controller = new AbortController();
+        let idle;
+        const armIdle = () => {
+            clearTimeout(idle);
+            idle = setTimeout(() => controller.abort(), deps.readIdleTimeoutMs);
+        };
+        const headers = {
+            Authorization: `Bearer ${options.ticket}`,
+            Accept: "text/event-stream",
+        };
+        if (lastEventId !== null)
+            headers["Last-Event-ID"] = String(lastEventId);
+        const openedAt = deps.now();
+        let delivered = false;
+        const healthy = () => delivered || deps.now() - openedAt >= HEALTHY_CONNECTION_MS;
+        try {
+            armIdle();
+            const response = await deps.fetch(options.streamUrl, { headers, signal: controller.signal });
+            if (response.status >= 400 && response.status < 500 && !RETRYABLE_CLIENT_STATUSES.has(response.status)) {
+                return { kind: "refused", detail: `HTTP ${response.status} ${(await response.text()).slice(0, 300)}` };
+            }
+            if (!response.ok || response.body === null) {
+                await response.body?.cancel();
+                return { kind: "dropped", healthy: false };
+            }
+            const parser = new SseParser();
+            const decoder = new TextDecoder();
+            for await (const chunk of response.body) {
+                armIdle();
+                for (const message of parser.push(decoder.decode(chunk, { stream: true }))) {
+                    const outcome = handle(message);
+                    if (outcome !== null)
+                        return outcome;
+                    if (message.event === "activity")
+                        delivered = true;
+                }
+            }
+            return { kind: "dropped", healthy: healthy() };
+        }
+        catch {
+            return { kind: "dropped", healthy: healthy() };
+        }
+        finally {
+            clearTimeout(idle);
+            controller.abort();
+        }
+    };
+    for (;;) {
+        const outcome = await connectOnce();
+        if (outcome.kind === "ended") {
+            if (outcome.reason === "superseded" || outcome.reason === "replaced") {
+                deps.write(`${LINE_PREFIX} stopped: another listener for this session took over (${outcome.reason}). ` +
+                    `If you did not just call plan_connect, something else did — ${REARM}`);
+                return 0;
+            }
+            deps.write(`${LINE_PREFIX} stopped: the dashboard ended this listener (${outcome.reason}). ${REARM}`);
+            return 1;
+        }
+        if (outcome.kind === "refused") {
+            deps.write(`${LINE_PREFIX} gave up: the dashboard refused the listener ticket (${outcome.detail}). ${REARM}`);
+            return 1;
+        }
+        if (outcome.healthy) {
+            unhealthySince = null;
+            attempt = 0;
+        }
+        const now = deps.now();
+        unhealthySince ??= now;
+        if (now - unhealthySince >= options.leaseMs) {
+            deps.write(`${LINE_PREFIX} gave up: no healthy connection to ${options.streamUrl} for ` +
+                `${Math.round((now - unhealthySince) / 60_000)} minutes, past the ticket's lease. ${REARM}`);
+            return 1;
+        }
+        await deps.sleep(Math.min(MAX_BACKOFF_MS, INITIAL_BACKOFF_MS * 2 ** attempt));
+        attempt += 1;
+    }
+}
+/** The bin's `listen` subcommand, wired to the real process. */
+export async function runListenCommand(argv) {
+    let options;
+    try {
+        options = parseListenArgs(argv);
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n`);
+        return 2;
+    }
+    return runListener(options, {
+        fetch,
+        write: (line) => {
+            process.stdout.write(`${line}\n`);
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: Date.now,
+        readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "description": "Stdio MCP server wrapping danxbot's dashboard /api/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
   "license": "MIT",
   "type": "module",