@50arms/platform-mcp 0.0.0-stage → 0.1.436

package/dist/listen.js

@@ -0,0 +1,999 @@
+/**
+ * The session event STREAM READER — holds ONE listener ticket's connection to the
+ * dashboard's session event stream and emits one record per event.
+ *
+ * WHO USES IT. Only the in-process event relay (`plan-events-relay.ts`), which mints the
+ * ticket, runs this reader inside the MCP server, and re-mints when a ticket's lease runs out.
+ * The ticket therefore never leaves the server's memory: no command line, no
+ * environment variable.
+ *
+ * THE OUTPUT CONTRACT (`ListenOutput`), because every event record reaches an agent:
+ *   - `{type:"event", id, text}` — exactly one per event, the moment it arrives.
+ *     `text` is what the session reads; an event it cannot read still produces one
+ *     (`could not read event …`), never silence. `id` is `null` only for a frame
+ *     that carried no usable id. DX-2885's `nudge` frame (`formatNudgeLine`), DX-4340's `pacing` frame (`formatPacingLine`) and
+ *     DX-4342's `resume` frame (`formatResumeLine`) and DX-5690's `owed_comment` frame (`formatOwedCommentLine`) are advisory and ride this same shape rather than growing a THIRD output
+ *     variant. DX-5007: the dashboard stores each with an id and replays it until the id is reported, so they carry their id like
+ *     an activity line (an id-less one, from an older dashboard, carries `id: null`).
+ *   - `{type:"stopped", reason, detail}` — once, last. `reason`
+ *     is the dashboard's own end reason (`superseded`, `replaced`, `revoked`,
+ *     `not_connected`), `refused` (the ticket was not admitted), or
+ *     `lease_expired` (no healthy connection for the lease). A wire `reason` value this build does not recognize (a
+ *     newer dashboard's reason an older client hasn't shipped yet)
+ *     normalizes to `"unknown"` rather than passing the raw string through,
+ *     so the closed set stays closed — `fixForStop`'s generic
+ *     `DEFAULT_STOP_FIX` handles it exactly as it already handled a verbatim
+ *     unrecognized string.
+ *   - nothing for keep-alives, the connect marker, or a successful reconnect.
+ *
+ * RECONNECT AND RESUME. 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
+ * commit-order overlap that re-sends recently delivered ids, and an id already
+ * emitted is never emitted twice. `resumeIds` carries that memory across a ticket
+ * or process restart: the ids already delivered seed the duplicate guard, and the
+ * highest is the first `Last-Event-ID`. 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.
+ *
+ * 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.
+ */
+import { controlOfFrame, invalidCompactionReason } from "./compaction-control.js";
+import { clearControlOfFrame, invalidClearReason } from "./clear-control.js";
+import { LINE_PREFIX, oneLine } from "./one-line.js";
+import { MCP_STREAM_MIN_VERSION_HEADER, ownVersionBelow, readOwnVersion } from "./version-floor.js";
+import { pacingRelayLine } from "./pacing-relay.js";
+import { isUrgent } from "./urgent-records.js";
+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 delivered event ids the duplicate guard remembers — well past the replay overlap. */
+export const DELIVERED_ID_MEMORY = 1_000;
+/**
+ * DX-2829 — the ONE place that caps a resume-id list to the last
+ * `DELIVERED_ID_MEMORY` entries. Both `runListener` (seeding its own
+ * duplicate-detection `Set` below) and the relay (`plan-events-relay.ts`) (seeding its
+ * own delivered-id array) used to each carry their own `slice(-DELIVERED_ID_MEMORY)`
+ * — the same cap, on the same kind of input, computed twice.
+ */
+export function capResumeIds(ids) {
+    return ids.slice(-DELIVERED_ID_MEMORY);
+}
+const ACTIVITY_ORIGINS = new Set(["operator", "agent", "machine"]);
+function quoted(value) {
+    return `"${value.text}${value.truncated ? "…" : ""}"`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCappedText(value) {
+    return isRecord(value) && typeof value.text === "string" && typeof value.truncated === "boolean";
+}
+function isAckList(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((a) => isRecord(a) && Number.isSafeInteger(a.eventId) && a.eventId > 0 && Number.isSafeInteger(a.attempt) && a.attempt >= 1));
+}
+/** DX-4078 - hand-copied from `DESIGN_DECISION_OUTCOMES` (`src/issues/view-types.ts`): this published package cannot import danxbot source. */
+const DESIGN_OUTCOMES = ["approved", "rejected", "changes_requested"];
+function isDesignOutcome(value) {
+    return typeof value === "string" && DESIGN_OUTCOMES.includes(value);
+}
+/**
+ * DX-3880 — the part `solution_answered` and `problem_answer_changed` share: the
+ * decision's `outcome` and the either/or body it implies. A rejection (the
+ * operator DECLINED an action) always names the solution and carries its reason
+ * as `solution.note`; an answer is a solution (optional note) or free-form text.
+ */
+function invalidDecisionBody(d) {
+    if (d.outcome !== "answered" && d.outcome !== "rejected")
+        return 'detail.outcome is not "answered" or "rejected"';
+    if (d.solution === null) {
+        if (d.outcome === "rejected")
+            return "detail.solution is null on a rejection";
+        return isCappedText(d.freeform) ? null : "detail.freeform is not capped text";
+    }
+    if (!isRecord(d.solution) || typeof d.solution.title !== "string")
+        return "detail.solution is not {title, note}";
+    if (d.outcome === "rejected") {
+        return isCappedText(d.solution.note) ? null : "detail.solution.note (the rejection reason) is not capped text";
+    }
+    return d.solution.note === null || isCappedText(d.solution.note) ? null : "detail.solution.note is not capped text";
+}
+/**
+ * DX-2735 — why an event cannot be described, or `null` when it can.
+ *
+ * Checked BEFORE describing, so a malformed event is reported by what is
+ * actually wrong with it — never by whichever TypeError a missing field happens
+ * to raise (whose wording is the JS engine's, not ours). The envelope is checked
+ * for every kind; the detail only for the kinds `describe` reads, so a kind newer
+ * than this listener still produces its generic line.
+ */
+export function invalidEventReason(value) {
+    if (!isRecord(value))
+        return "the event is not an object";
+    if (typeof value.id !== "number" || !Number.isSafeInteger(value.id))
+        return "id is not an integer";
+    // DX-6211: the subject is a card (`cardId` a string) or the plan itself (`planId` a positive integer and `cardId` null), never both and never neither.
+    if (value.planId !== null && !(typeof value.planId === "number" && Number.isSafeInteger(value.planId) && value.planId > 0)) {
+        return "planId is not null or a positive integer";
+    }
+    if (typeof value.planId === "number") {
+        if (value.cardId !== null)
+            return "cardId is not null on a plan event";
+        if (typeof value.planRef !== "string" || value.planRef === "")
+            return "planRef is not a string on a plan event";
+    }
+    else if (typeof value.cardId !== "string") {
+        return "cardId is not a string";
+    }
+    for (const field of ["cardTitle", "actor", "kind"]) {
+        if (typeof value[field] !== "string")
+            return `${field} is not a string`;
+    }
+    // DX-5466: null is legal only on a pause release (a plan/session anchor has no board); no text marker ever travels here.
+    const isReleaseWithoutBoard = value.boardId === null && value.release === true;
+    const isBoardId = typeof value.boardId === "number" && Number.isSafeInteger(value.boardId);
+    if (!isReleaseWithoutBoard && !isBoardId)
+        return "boardId is not an integer";
+    // DX-2730 D4 — checked with the rest of the envelope, before any kind-specific
+    // detail check, exactly like every other envelope field above.
+    if (typeof value.origin !== "string" || !ACTIVITY_ORIGINS.has(value.origin)) {
+        return "origin is not one of operator, agent, machine";
+    }
+    // DX-4246 — the key snapshot is part of every event the dashboard sends, `null` when no key wrote it.
+    if (value.viaKey !== null && !(isRecord(value.viaKey) && typeof value.viaKey.id === "number" && typeof value.viaKey.name === "string")) {
+        return "viaKey is not null or {id, name}";
+    }
+    if (value.release !== undefined && value.release !== true)
+        return "release is not true";
+    // DX-5846: an event that asks for an acknowledgement and names no (or a wrong) event to acknowledge is a fault line, never a record the session cannot answer.
+    if (value.acks !== undefined && !isAckList(value.acks))
+        return "acks is not a list of {eventId, attempt}";
+    const d = value.detail;
+    if (!isRecord(d))
+        return "detail is not an object";
+    switch (value.kind) {
+        case "comment_added": {
+            if (!isCappedText(d.excerpt))
+                return "detail.excerpt is not capped text";
+            // DX-5435: the line tells the agent which comment to signal on, so a person's comment must name it.
+            if (isPersonsComment(value) && typeof d.comment_id !== "number")
+                return "detail.comment_id is not a number";
+            // DX-2906 — `problem` is OPTIONAL (only present when the comment named
+            // one); absent is valid, but a present-and-malformed one is not.
+            if (d.problem === undefined)
+                return null;
+            const problem = d.problem;
+            return isRecord(problem) && typeof problem.id === "number" && isCappedText(problem.statement)
+                ? null
+                : "detail.problem is not {id, statement}";
+        }
+        case "solution_answered": {
+            const problem = d.problem;
+            if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
+                return "detail.problem is not {id, statement}";
+            }
+            return invalidDecisionBody(d);
+        }
+        case "problem_added": {
+            const problem = d.problem;
+            if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
+                return "detail.problem is not {id, statement}";
+            }
+            return null;
+        }
+        // DX-2935 — the operator retracted a problem's answer with no new one yet.
+        case "problem_unanswered": {
+            const problem = d.problem;
+            if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
+                return "detail.problem is not {id, statement}";
+            }
+            return typeof d.decision_id === "number" ? null : "detail.decision_id is not a number";
+        }
+        // DX-2935 — the operator retracted a problem's answer AND recorded a new
+        // one, in one transaction — same either/or solution/freeform shape
+        // `solution_answered` carries, plus which decision was retracted.
+        case "problem_answer_changed": {
+            const problem = d.problem;
+            if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
+                return "detail.problem is not {id, statement}";
+            }
+            if (typeof d.retracted_decision_id !== "number")
+                return "detail.retracted_decision_id is not a number";
+            if (typeof d.decision_id !== "number")
+                return "detail.decision_id is not a number";
+            return invalidDecisionBody(d);
+        }
+        case "blocked":
+            return isCappedText(d.reason) ? null : "detail.reason is not capped text";
+        // DX-5323: an agent wrote a note in its working log on the card (never a comment).
+        case "agent_note_added":
+            if (typeof d.note_id !== "number")
+                return "detail.note_id is not a number";
+            return isCappedText(d.excerpt) ? null : "detail.excerpt is not capped text";
+        // DX-4622: a reviewer asked for changes on the card's pull request (GitHub review webhook).
+        case "pull_request_changes_requested":
+            if (typeof d.reviewer !== "string")
+                return "detail.reviewer is not a string";
+            if (typeof d.review_url !== "string")
+                return "detail.review_url is not a string";
+            return isCappedText(d.excerpt) ? null : "detail.excerpt is not capped text";
+        // DX-6478: a designer published a revision it could not check in a browser.
+        case "design_published_unchecked":
+            if (typeof d.design_no !== "number")
+                return "detail.design_no is not a number";
+            if (typeof d.design_title !== "string")
+                return "detail.design_title is not a string";
+            if (typeof d.revision_no !== "number")
+                return "detail.revision_no is not a number";
+            return isCappedText(d.reason) ? null : "detail.reason is not capped text";
+        // DX-4078: the operator's verdict on a design revision. An outcome this listener does not know is refused, never rendered as the bare
+        // kind line, which would name no outcome and no note and leave the agent to re-read the card. `rejected` and `changes_requested` always
+        // carry their note (the table CHECK); `approved` may carry none.
+        case "design_decided": {
+            if (typeof d.decision_id !== "number")
+                return "detail.decision_id is not a number";
+            if (typeof d.design_no !== "number")
+                return "detail.design_no is not a number";
+            if (typeof d.design_title !== "string")
+                return "detail.design_title is not a string";
+            if (typeof d.revision_no !== "number")
+                return "detail.revision_no is not a number";
+            if (!isDesignOutcome(d.outcome))
+                return 'detail.outcome is not "approved", "rejected" or "changes_requested"';
+            if (d.note === null)
+                return d.outcome === "approved" ? null : `detail.note (the ${d.outcome} reason) is null`;
+            return isCappedText(d.note) ? null : "detail.note is not null or capped text";
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * DX-2730 D4 — `actor` alone cannot distinguish an `agent` event from a
+ * `machine` one (both stamp `actor: "danxbot"` today), so every line names
+ * the origin next to the actor rather than leaving it to a separate field a
+ * reader would have to cross-reference.
+ */
+function actorLabel(event) {
+    // DX-4246 — a write made through an API key names the user AND the key ("dan via claude-laptop (agent)").
+    const via = event.viaKey === null ? "" : ` via ${event.viaKey.name}`;
+    return `${event.actor}${via} (${event.origin})`;
+}
+/** DX-5435: a comment a person wrote (not the session's own pause notice, not an agent's or the machine's): the one an agent answers through its reply message. */
+function isPersonsComment(event) {
+    return event.origin === "operator" && event.release !== true;
+}
+/**
+ * DX-5799: what the agent does with a person's comment. The person's comment shows the agent that received it, and the reply is ONE message the agent writes
+ * twice: first a short acknowledgement of its own (`phase: "ack"`, so the person sees the comment was received), then its full answer (`phase: "reply"`) written
+ * over the same message, so the answer never arrives as a separate comment. The text is written here, with the line the agent reads, so every session that
+ * updates this package follows it without a plugin change.
+ */
+export function replyInstruction(cardId, commentId) {
+    return replyInstructionAt(`/api/issues/${cardId}/comments/${commentId}/reply`);
+}
+/** DX-6211: {@link replyInstruction} for a person's comment written on the plan itself, answered by the plan's session through the plan's reply route. */
+export function planReplyInstruction(planId, commentId) {
+    return replyInstructionAt(`/api/plans/${planId}/comments/${commentId}/reply`);
+}
+/** DX-6211: the event's subject as the line names it: the card's id, or the plan's reference (`PLAN-72`, sent by the dashboard as `planRef`) for a plan event. Only called on an event `invalidEventReason` accepted. */
+function subjectRef(event) {
+    return typeof event.planId === "number" ? event.planRef : event.cardId;
+}
+function replyInstructionAt(path) {
+    return `Answer it through its reply message: first call 50arms_api POST ${path} with {"phase":"ack","body":"<one short sentence of your own acknowledging it>"} so the person sees it was received, then do the work and call POST ${path} again with {"phase":"reply","body":"<your full answer>"}, which overwrites the same message; never answer with a separate comment`;
+}
+/** DX-6064: what a session does with a person's answer (or changed answer), so a decision never lives only in its conversation. */
+export const UPDATE_RECORDS_NOW = "Update every plan record and card this answer changes, this turn";
+/** Only ever called on an event `invalidEventReason` accepted, so its casts are checked. */
+function describe(event) {
+    const d = event.detail;
+    const who = actorLabel(event);
+    switch (event.kind) {
+        case "comment_added": {
+            // DX-2906 — a comment naming a problem (a follow-up question, without
+            // answering it) relays distinctly from a plain comment, so an agent
+            // listening to the stream can tell which of its open problems just
+            // got a reply.
+            const problem = d.problem;
+            if (event.release === true)
+                return `${who} notice: ${quoted(d.excerpt)}`;
+            // DX-6211: a comment written on the plan itself is answered through the plan's reply route, and the line says it was written on the plan.
+            const onPlan = typeof event.planId === "number";
+            const reply = !isPersonsComment(event) ? "" : `. ${onPlan ? planReplyInstruction(event.planId, d.comment_id) : replyInstruction(event.cardId, d.comment_id)}`;
+            if (problem === undefined)
+                return `${who} commented${onPlan ? " on the plan" : ""}: ${quoted(d.excerpt)}${reply}`;
+            return `${who} commented on problem ${quoted(problem.statement)}: ${quoted(d.excerpt)}${reply}`;
+        }
+        case "solution_answered": {
+            // DX-2735: every answer answers ONE problem on a card that may carry several,
+            // so the line names the problem — otherwise the agent cannot tell which of its
+            // questions just closed.
+            const problem = d.problem;
+            const solution = d.solution;
+            // DX-3880 — a REJECTION is the opposite of work done: the operator declined
+            // the action, so the line says so and names the reason; the agent must not
+            // perform it and re-plans from the note.
+            if (d.outcome === "rejected")
+                return `${who} rejected the action "${solution.title}" for ${quoted(problem.statement)} — reason: ${quoted(solution.note)}. Do not perform it; re-plan from the reason`;
+            const answered = `${who} answered ${quoted(problem.statement)}:`;
+            if (solution === null)
+                return `${answered} ${quoted(d.freeform)}. ${UPDATE_RECORDS_NOW}`;
+            const note = solution.note === null ? "" : ` — note: ${quoted(solution.note)}`;
+            return `${answered} chose "${solution.title}"${note}. ${UPDATE_RECORDS_NOW}`;
+        }
+        case "problem_added": {
+            // DX-2830 — this IS the "needs a human" signal now: a card needs one
+            // exactly when it has an open problem, and this is one being opened.
+            const problem = d.problem;
+            return `${who} opened a problem: ${quoted(problem.statement)}`;
+        }
+        case "problem_unanswered": {
+            // DX-2935 — MUST read as "a previous answer was withdrawn", never as a
+            // brand-new problem: a connected session that already acted on the
+            // retracted answer has to stop, not treat this as fresh work to start.
+            const problem = d.problem;
+            return `${who} retracted the answer to ${quoted(problem.statement)}`;
+        }
+        case "problem_answer_changed": {
+            // DX-2935 — ONE line for the whole retract-and-reanswer (never two
+            // separate events), naming the statement so a listener with several
+            // open questions knows which one just moved.
+            const problem = d.problem;
+            const solution = d.solution;
+            if (d.outcome === "rejected")
+                return `${who} changed the answer to ${quoted(problem.statement)}: now REJECTED the action "${solution.title}" — reason: ${quoted(solution.note)}. Do not perform it; re-plan from the reason`;
+            const now = solution === null ? quoted(d.freeform) : `"${solution.title}"`;
+            return `${who} changed the answer to ${quoted(problem.statement)}: now ${now}. ${UPDATE_RECORDS_NOW}`;
+        }
+        case "blocked":
+            return `${who} blocked the card: ${quoted(d.reason)}`;
+        // DX-5323: a working-log entry for the next agent; the full note is the card's `agent_notes`.
+        case "agent_note_added":
+            return `${who} wrote an agent note: ${quoted(d.excerpt)}`;
+        case "unblocked":
+            return `${who} unblocked the card`;
+        // DX-4622: the agent must act on the review, so the line names who, where, and what to do next.
+        case "pull_request_changes_requested":
+            return `${who}: ${d.reviewer} requested changes on the pull request (${d.review_url})${d.excerpt.text === "" ? "" : `: ${quoted(d.excerpt)}`}. Address the review, push, and reply on the pull request`;
+        // DX-6478: names the design, the revision and the reason, so the operator can correct the behaviour.
+        case "design_published_unchecked":
+            return `${who} published revision ${d.revision_no} of design ${d.design_no} "${d.design_title}" WITHOUT checking it in a browser — reason: ${quoted(d.reason)}. It carries a red warning on the card; correct why the designer had no browser`;
+        // DX-4078: names the outcome, the revision and the note, and what the agent does next, so it never has to re-read the card to learn the verdict.
+        case "design_decided": {
+            const note = d.note;
+            // DX-5193: a card holds several designs, so the line names which one the verdict closes.
+            const revision = `revision ${d.revision_no} of design ${d.design_no} "${d.design_title}"`;
+            if (d.outcome === "approved")
+                return `${who} APPROVED ${revision}${note === null ? "" : ` — note: ${quoted(note)}`}. That design is the one to build from; the person can still withdraw the choice until the build is picked up, so build from the design the card holds now`;
+            if (d.outcome === "rejected")
+                return `${who} REJECTED ${revision} — reason: ${quoted(note)}. That design is closed; do not continue it`;
+            return `${who} requested changes on ${revision} — ${quoted(note)}. Publish a new revision that addresses it`;
+        }
+        default:
+            // A kind newer than this listener still produces a line: an event the
+            // agent is never told about is exactly the failure this reader prevents.
+            return `${who}: ${event.kind}`;
+    }
+}
+/**
+ * DX-5846: what the agent does with an event that must be acknowledged. The first send says to confirm receipt, then act; a re-send (the dashboard got no acknowledgement for an earlier copy) says it is a repeat, so an agent that
+ * already acted does only the acknowledgement. The text is written here, with the line the agent reads, so every session that updates this package follows it without a plugin change.
+ */
+export function ackInstruction(ack) {
+    const path = `/api/plan-sessions/me/events/${ack.eventId}/ack`;
+    if (ack.attempt <= 1)
+        return `[ack-required event ${ack.eventId}] First call 50arms_api POST ${path} (no body) to confirm you received it, then act on it.`;
+    return `[ack-required event ${ack.eventId}, sent again (attempt ${ack.attempt})] Not acknowledged yet. If you already acted on it, only acknowledge it: 50arms_api POST ${path} (no body).`;
+}
+/** The one readable line for an event. Always a single line; throws, naming the fault, on a malformed event. */
+export function formatActivityLine(event) {
+    const invalid = invalidEventReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed activity event: ${invalid}`);
+    // DX-5846: the acknowledgement comes first, so it is done before the event's own instructions (a comment's "responding" call).
+    const acks = (event.acks ?? []).map((a) => `${ackInstruction(a)} `).join("");
+    return oneLine(`${acks}[${subjectRef(event)} "${event.cardTitle}"${event.boardId === null ? "" : ` ${event.boardId}`}] ${describe(event)}`);
+}
+/** DX-6277 - the instruction a line carries when it names filed-not-readied cards; the dashboard's own wording (`FILED_NOT_READIED_INSTRUCTION`) for the same cards. */
+const FILED_NOT_READIED_INSTRUCTION = "Ready each now (order: depends_on), or open a problem if only a person can decide.";
+/** DX-6277 - the label the filed ids sit under; the same words as the dashboard's `FILED_NOT_READIED_LABEL` (src/issues/agent-pause.ts). */
+const FILED_NOT_READIED_LABEL = "Filed, not readied";
+function isNudgeCardRef(value) {
+    return isRecord(value) && typeof value.id === "string" && typeof value.title === "string";
+}
+function isNudgeCardRefArray(value) {
+    return Array.isArray(value) && value.every(isNudgeCardRef);
+}
+function isQueuedNudgeCardRefArray(value) {
+    return Array.isArray(value) && value.every((c) => isNudgeCardRef(c) && typeof c.queueState === "string");
+}
+/** Why a nudge cannot be read, or `null` when it can — same checked-before-describing shape as `invalidEventReason`. */
+export function invalidNudgeReason(value) {
+    if (!isRecord(value))
+        return "the nudge is not an object";
+    if (typeof value.idleMinutes !== "number" || !Number.isFinite(value.idleMinutes)) {
+        return "idleMinutes is not a number";
+    }
+    if (!isQueuedNudgeCardRefArray(value.startable))
+        return "startable is not a {id,title,queueState}[] array";
+    if (!isNudgeCardRefArray(value.held))
+        return "held is not a {id,title}[] array";
+    if (!isNudgeCardRefArray(value.unreadied))
+        return "unreadied is not a {id,title}[] array";
+    return null;
+}
+function cardList(cards) {
+    return cards.map((c) => `${c.id} "${c.title}"`).join(", ");
+}
+function queuedCardList(cards) {
+    return cards.map((c) => `${c.id} "${c.title}" [${c.queueState}]`).join(", ");
+}
+/**
+ * The one readable line for a nudge (DX-2885). Always names the actual
+ * waiting cards — never a generic "keep going" — because that is the whole
+ * point of the feature: a session that only sees "you're idle" learns
+ * nothing a bare timer couldn't have told it. Always a single line; throws,
+ * naming the fault, on a malformed nudge.
+ *
+ * DX-3274 — the line asserts only what `evaluateIdleNudge` actually measured
+ * (no real MCP call from THIS session in `idleMinutes`), never "work is
+ * waiting" or "work has stalled". `last_agent_call_at` cannot see a
+ * sub-agent/dispatch working the same card from underneath an orchestrating
+ * session — an orchestrator that delegates and then correctly waits without
+ * polling (the project's own mandated style, `base:monitor-polling`) looks
+ * identical, on this signal, to one that actually stalled. The card names
+ * are still worth reporting (a real signal: these are the cards this session
+ * itself has not touched), but the claim about THEM stops at "not checked
+ * in" — never a claim about whether the work itself is progressing, which
+ * this signal cannot support. See `evaluateIdleNudge`'s own doc comment
+ * (`src/issues/db/session-idle-nudge.ts`) for why a sub-agent-awareness
+ * special case was rejected instead of this wording fix.
+ *
+ * DX-3676 — every named card clears every dispatch gate, so if the session
+ * still cannot work one, the card's recorded state is wrong (DX-3400 sat in
+ * ToDo with its real blocker only in a comment). For the cards this session
+ * holds, the line therefore ends by naming each state-correcting move, which is
+ * also what stops the nudge. DX-5154 / DX-6071: a startable card is run by its queue item and is named only while that item is held, so for
+ * those the line says why the item is held (bracketed) and that clearing the reason or removing the item is the move, never working the card; a nudge naming only
+ * startable cards says nothing about working them.
+ */
+export function formatNudgeLine(event) {
+    const invalid = invalidNudgeReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed nudge event: ${invalid}`);
+    // DX-6277 - the filed label and instruction come before the ids, and the startable and held parts after them, so the instruction is never the part a cut takes.
+    const parts = [];
+    if (event.unreadied.length > 0)
+        parts.push(`${FILED_NOT_READIED_LABEL} (${FILED_NOT_READIED_INSTRUCTION}): ${cardList(event.unreadied)}`);
+    if (event.startable.length > 0)
+        parts.push(`startable: ${queuedCardList(event.startable)}`);
+    if (event.held.length > 0)
+        parts.push(`held: ${cardList(event.held)}`);
+    // DX-5154 / DX-6071: a startable card is run by its dispatch queue item, not by this session, and is named only while that item is held, so the line says what to do
+    // about THAT and keeps the work-or-correct-it instruction for the cards this session itself holds.
+    const advice = [];
+    if (event.startable.length > 0) {
+        advice.push("Startable cards are run by their queue item, not by this session: never work or rollback_pickup them. The bracketed text says where the item stands; a held item waits on you: clear the reason it names, or remove the item.");
+    }
+    if (event.held.length > 0) {
+        advice.push("Work the held cards; any you cannot work, update to its true state: open a problem, add depends_on or conflict_on, block it with the real reason, or rollback_pickup.");
+    }
+    const tail = advice.length > 0 ? `. ${advice.join(" ")}` : ".";
+    return oneLine(`${LINE_PREFIX} this session has not made an MCP call in ${event.idleMinutes}m — ${parts.join("; ")}${tail}`);
+}
+const PACING_LEVELS = ["on_pace", "over_pace", "critical"];
+/** Why a pacing message cannot be read, or `null` when it can. */
+export function invalidPacingReason(value) {
+    if (!isRecord(value))
+        return "the pacing message is not an object";
+    if (!PACING_LEVELS.includes(value.level))
+        return "level is not on_pace, over_pace or critical";
+    if (value.budget !== null && !(typeof value.budget === "number" && Number.isInteger(value.budget) && value.budget >= 0))
+        return "budget is not a count or null";
+    if (typeof value.resets_at !== "string" || Number.isNaN(Date.parse(value.resets_at)))
+        return "resets_at is not a timestamp";
+    if (typeof value.text !== "string" || value.text.trim() === "")
+        return "text is empty";
+    return null;
+}
+/** The one readable line for a pacing message: the dashboard's text, on one line. Throws, naming the fault, on a malformed message. */
+export function formatPacingLine(event) {
+    const invalid = invalidPacingReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed pacing message: ${invalid}`);
+    return pacingRelayLine(event.text);
+}
+/** Why a resume message cannot be read, or `null` when it can. */
+export function invalidResumeReason(value) {
+    if (!isRecord(value))
+        return "the resume message is not an object";
+    if (typeof value.text !== "string" || value.text.trim() === "")
+        return "text is empty";
+    return null;
+}
+/** The one readable line for a resume message: the dashboard's text, on one line, cut like a pacing line. Throws, naming the fault, on a malformed message. */
+export function formatResumeLine(event) {
+    const invalid = invalidResumeReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed resume message: ${invalid}`);
+    return pacingRelayLine(event.text);
+}
+/** Why an assignment message cannot be read, or `null` when it can. */
+export function invalidAssignmentReason(value) {
+    if (!isRecord(value))
+        return "the assignment message is not an object";
+    if (typeof value.text !== "string" || value.text.trim() === "")
+        return "text is empty";
+    return null;
+}
+/** The one readable line for an assignment message: the dashboard's text, on one line, cut like a pacing line. Throws, naming the fault, on a malformed message. */
+export function formatAssignmentLine(event) {
+    const invalid = invalidAssignmentReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed assignment message: ${invalid}`);
+    return pacingRelayLine(event.text);
+}
+/** Why an owed-comment message cannot be read, or `null` when it can. */
+export function invalidOwedCommentReason(value) {
+    if (!isRecord(value))
+        return "the owed-comment message is not an object";
+    if (typeof value.text !== "string" || value.text.trim() === "")
+        return "text is empty";
+    if (!Array.isArray(value.comment_ids) || !value.comment_ids.every((id) => Number.isSafeInteger(id)))
+        return "comment_ids is not a list of comment ids";
+    return null;
+}
+/** The one readable line for an owed-comment message: the dashboard's text, on one line, cut like a pacing line. Throws, naming the fault, on a malformed message. */
+export function formatOwedCommentLine(event) {
+    const invalid = invalidOwedCommentReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed owed-comment message: ${invalid}`);
+    return pacingRelayLine(event.text);
+}
+/** Why an agent-created frame cannot be read, or `null` when it can. */
+export function invalidAgentCreatedReason(value) {
+    if (!isRecord(value))
+        return "the agent-created frame is not an object";
+    if (!isRecord(value.agent))
+        return "agent is not an object";
+    if (!Number.isSafeInteger(value.agent.id) || value.agent.id <= 0)
+        return "agent.id is not a positive integer";
+    if (typeof value.agent.name !== "string" || value.agent.name.trim() === "")
+        return "agent.name is empty";
+    if (typeof value.agentInstruction !== "string" || value.agentInstruction.trim() === "")
+        return "agentInstruction is empty";
+    if (value.plan !== null && (!isRecord(value.plan) || typeof value.plan.ref !== "string" || typeof value.plan.name !== "string"))
+        return "plan is neither null nor a {ref, name} object";
+    if (value.card !== null && (!isRecord(value.card) || typeof value.card.id !== "string" || typeof value.card.title !== "string"))
+        return "card is neither null nor a {id, title} object";
+    if (value.naming !== null) {
+        if (!isRecord(value.naming) || (value.naming.status !== "ok" && value.naming.status !== "needed"))
+            return "naming is neither null nor a naming block";
+        if (value.naming.status === "needed" && (typeof value.naming.instruction !== "string" || value.naming.instruction.trim() === ""))
+            return "naming.instruction is empty";
+    }
+    if (value.titleInstruction !== null && typeof value.titleInstruction !== "string")
+        return "titleInstruction is neither null nor a string";
+    if (value.rolePointer !== null && typeof value.rolePointer !== "string")
+        return "rolePointer is neither null nor a string";
+    if (value.owedComments !== null && typeof value.owedComments !== "string")
+        return "owedComments is neither null nor a string";
+    if (value.missedEvents !== null) {
+        if (!isRecord(value.missedEvents) || !Array.isArray(value.missedEvents.events) || !Number.isSafeInteger(value.missedEvents.omitted))
+            return "missedEvents is neither null nor an {events, omitted} object";
+        for (const event of value.missedEvents.events) {
+            const bad = invalidEventReason(event);
+            if (bad !== null)
+                return `missedEvents holds an unreadable event: ${bad}`;
+        }
+    }
+    return null;
+}
+/**
+ * The one line that wakes a proposing session: its agent was created, it is signed in as that agent (and connected to its plan or card), and the instruction and thread name to carry on with. The caller has already
+ * validated the frame ({@link invalidAgentCreatedReason}).
+ */
+export function formatAgentCreatedLine(event) {
+    const where = event.plan !== null ? ` and connected to ${event.plan.ref} ${oneLine(event.plan.name, 80)}` : event.card !== null ? ` and connected to card ${event.card.id}` : "";
+    const thread = event.naming !== null ? (event.naming.status === "needed" ? event.naming.instruction : "") : (event.titleInstruction ?? "");
+    const missed = event.missedEvents;
+    const missedLines = missed === null || missed.events.length === 0
+        ? ""
+        : `Missed while you waited for your agent: ${missed.events.map((e) => formatActivityLine(e)).join(" ")}${missed.omitted > 0 ? ` (${missed.omitted} more not shown)` : ""}`;
+    // DX-6157: no connect is needed to take what Create gave the session; a naming or role step that follows still makes its own call.
+    const held = event.plan !== null ? "this agent and plan" : event.card !== null ? "this agent and card" : "this agent";
+    const ownCalls = thread !== "" || event.rolePointer !== null ? "; the steps below keep their own calls" : "";
+    const parts = [
+        `${LINE_PREFIX} The person created your team agent ${oneLine(event.agent.name, 60)}: this session is now signed in as it${where}. Taking ${held} needs no \`plan_connect\`${ownCalls}.`,
+        oneLine(event.agentInstruction, 800),
+        thread === "" ? "" : oneLine(thread, 800),
+        event.owedComments === null ? "" : oneLine(event.owedComments),
+        missedLines,
+        event.rolePointer === null ? "" : oneLine(event.rolePointer, 800),
+        "Then carry on with the work you were asked to do.",
+    ];
+    return parts.filter((part) => part !== "").join(" ");
+}
+/**
+ * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
+ * field-less blocks produce no message, which is what keeps them out of the output.
+ */
+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;
+}
+/**
+ * DX-2920 (round 4) — the dashboard's own `StreamEndReason` values this
+ * client recognizes on the wire. Hand-copied from `StreamEndReason` in
+ * `src/issues/plan-session-listeners.ts` — this published package cannot
+ * import danxbot source. A wire `reason` this set does not contain (a newer
+ * dashboard's reason this build predates) normalizes to `"unknown"` rather
+ * than passing the raw string through, which is what lets `Outcome`'s
+ * `reason` field below be a closed union instead of `string`.
+ */
+const KNOWN_WIRE_END_REASONS = new Set(["superseded", "replaced", "revoked", "not_connected", "plan_archived"]);
+function isKnownWireEndReason(reason) {
+    return KNOWN_WIRE_END_REASONS.has(reason);
+}
+/** A thrown value's message, for the one drop path that carries a real JS error — never re-derived elsewhere. */
+function describeDropError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** 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 reader gives up, always ending
+ * with exactly one `stopped` record. Returns the exit code: 0 when a newer
+ * listener took over, 1 otherwise.
+ */
+export async function runListener(options, deps) {
+    const delivered = new Set();
+    let lastEventId = null;
+    let unhealthySince = null;
+    let attempt = 0;
+    // DX-2829 — the most recent `dropped` outcome's cause, carried across
+    // reconnect attempts so the eventual `lease_expired` stop (the only outcome
+    // reached exclusively via repeated drops) can say what actually failed
+    // instead of only "no healthy connection ... past the ticket's lease".
+    let lastDropDetail = null;
+    const remember = (id) => {
+        delivered.add(id);
+        if (delivered.size > DELIVERED_ID_MEMORY)
+            delivered.delete(delivered.values().next().value);
+        lastEventId = lastEventId === null ? id : Math.max(lastEventId, id);
+    };
+    for (const id of capResumeIds(options.resumeIds))
+        remember(id);
+    function stop(reason, detail, code) {
+        deps.write({ type: "stopped", reason, detail });
+        return code;
+    }
+    // DX-5554: the one parse of a frame's JSON plus its shape check (advisory, compaction and agent-created frames all read this way); a parse failure is the reason, never a throw.
+    const readFrame = (message, invalidReason) => {
+        try {
+            const parsed = JSON.parse(message.data);
+            return { parsed, invalid: invalidReason(parsed) };
+        }
+        catch (err) {
+            return { parsed: undefined, invalid: `not JSON: ${err.message}` };
+        }
+    };
+    const faultText = (what, invalid, message) => `${LINE_PREFIX} could not read ${what} (${invalid}): ${oneLine(message.data, 300)}. This session's platform MCP (version ${readOwnVersion()}) cannot read what the dashboard sends: ` +
+        "restart this session, or reconnect its platform server in /mcp, to install the current version.";
+    // DX-6272: an unreadable frame wakes the session once per cause. A frame the dashboard repeats (the compaction control comes with every stats write) that fails for the same
+    // reason again is dropped; a readable frame of the kind clears the memory, so a later fault is reported again. Keyed by frame kind, valued by the reason last reported.
+    const reportedFaults = new Map();
+    /** True when this (kind, reason) fault is new and so is to be written; records it. */
+    const faultIsNew = (kind, reason) => {
+        if (reportedFaults.get(kind) === reason)
+            return false;
+        reportedFaults.set(kind, reason);
+        return true;
+    };
+    /**
+     * The shared path of an ADVISORY frame (DX-2885 `nudge`, DX-4340 `pacing`, DX-4342 `resume`): the dashboard stores each with an id (DX-5007,
+     * `plan-session-stream.ts`'s module doc), so it is deduplicated and remembered by that id exactly like an activity event: the id is reported as
+     * `Last-Event-ID` on reconnect, which is what stops the dashboard replaying a frame this reader already read. It rides the SAME
+     * `{type:"event", id, text}` shape an ordinary activity line uses. That is what lets the relay (`plan-events-relay.ts`) forward it with no change: it forwards any
+     * `{type:"event", id, text}` record, keyed only on `type`.
+     *
+     * `origin: null` is DX-2730 D4's exemption: the frame is delivered at once, never held for a digest flush (a nudge exists to interrupt a quiet
+     * session; a pacing change is an instruction to act now). A frame that is not JSON or not the right shape is reported from an explicit check
+     * naming the fault, and the next frame still emits.
+     */
+    const emitAdvisory = (message, what, invalidReason, format, sourceOf, scope) => {
+        const { parsed, invalid } = readFrame(message, invalidReason);
+        // `Number(null)` is 0: a frame with no id must never be read as id 0 (see the activity path below).
+        const id = message.id === null ? Number.NaN : Number(message.id);
+        const knownId = Number.isSafeInteger(id) && id > 0;
+        if (knownId && delivered.has(id))
+            return null;
+        // DX-6272: a fault on a frame with no id is a repeat-prone one (an id'd frame is remembered by its id); report it once per cause.
+        if (invalid === null)
+            reportedFaults.delete(what);
+        else if (!knownId && !faultIsNew(what, invalid))
+            return null;
+        const text = invalid === null ? format(parsed) : faultText(what, invalid, message);
+        // DX-4721: an unreadable frame is a fault line, never the frame it failed to be (a malformed `critical` pacing frame is not a stop).
+        const urgent = isUrgent(invalid === null ? sourceOf(parsed) : { source: "fault" });
+        deps.write({ type: "event", id: knownId ? id : null, text, origin: null, urgent, acks: [], ...(scope === undefined ? {} : { scope }) });
+        if (knownId)
+            remember(id);
+        return null;
+    };
+    /** DX-4993 / DX-6692: a level-triggered control frame (`compaction`, `clear`): its output when it reads, else a fault line once per cause (never silence); the next frame still lands. */
+    const emitControl = (message, what, invalidReason, outputOf) => {
+        const { parsed, invalid } = readFrame(message, invalidReason);
+        if (invalid === null) {
+            reportedFaults.delete(what);
+            deps.write(outputOf(parsed));
+        }
+        else if (faultIsNew(what, invalid))
+            deps.write({ type: "event", id: null, text: faultText(what, invalid, message), origin: null, urgent: isUrgent({ source: "fault" }), acks: [], scope: "session" });
+        return null;
+    };
+    // DX-5554 (AC6): the agent ids already announced to the session. The frame is level-triggered (written again on every reconnect while the agent is untaken), so one agent wakes the session once.
+    const announcedAgentIds = new Set();
+    const emitAgentCreated = (message) => {
+        const { parsed, invalid } = readFrame(message, invalidAgentCreatedReason);
+        if (invalid !== null) {
+            if (faultIsNew("agent-created frame", invalid))
+                deps.write({ type: "event", id: null, text: faultText("agent-created frame", invalid, message), origin: null, urgent: isUrgent({ source: "fault" }), acks: [], scope: "session" });
+            return null;
+        }
+        reportedFaults.delete("agent-created frame");
+        const created = parsed;
+        const agent = created.agent;
+        if (announcedAgentIds.has(agent.id))
+            return null;
+        announcedAgentIds.add(agent.id);
+        deps.onAgentCreated?.(created);
+        deps.write({ type: "event", id: null, text: formatAgentCreatedLine(created), origin: null, urgent: isUrgent({ source: "agent_created" }), acks: [], scope: "session" });
+        return null;
+    };
+    const handle = (message) => {
+        if (message.event === "end") {
+            // DX-2920 (round 3) — a JSON.parse failure here falls through to the
+            // pre-existing "unknown" reason below via `isRecord(null)`.
+            let parsed;
+            try {
+                parsed = JSON.parse(message.data);
+            }
+            catch {
+                parsed = null;
+            }
+            const reasonRaw = isRecord(parsed) ? parsed.reason : undefined;
+            const reason = typeof reasonRaw === "string" ? reasonRaw : "unknown";
+            // DX-2920 (round 4) — a wire reason this build does not recognize (a
+            // newer dashboard's reason an older client hasn't shipped yet)
+            // normalizes to "unknown" rather than passing the raw string through:
+            // `Outcome`'s "ended" reason is a closed set (`EndedReason`).
+            return { kind: "ended", reason: isKnownWireEndReason(reason) ? reason : "unknown" };
+        }
+        if (message.event === "nudge")
+            return emitAdvisory(message, "nudge", invalidNudgeReason, (p) => formatNudgeLine(p), () => ({ source: "nudge" }));
+        // DX-4340 - the pacing tick's one message for this session's Claude account (level or budget changed): advisory like a nudge.
+        if (message.event === "pacing")
+            return emitAdvisory(message, "pacing message", invalidPacingReason, (p) => formatPacingLine(p), (p) => ({ source: "pacing", level: p.level }), "session");
+        // DX-4342 - the auto-resume's message once the limit that paused or stopped this session has reset: advisory like a pacing message.
+        if (message.event === "resume")
+            return emitAdvisory(message, "resume message", invalidResumeReason, (p) => formatResumeLine(p), () => ({ source: "resume" }), "session");
+        // DX-5690 - a person's comment this session is to answer is still unanswered: advisory like a resume message, session-scoped (it is about the session's comments, not a plan move).
+        if (message.event === "owed_comment")
+            return emitAdvisory(message, "owed-comment message", invalidOwedCommentReason, (p) => formatOwedCommentLine(p), () => ({ source: "owed_comment" }), "session");
+        // DX-6611 - a person assigned this ready session to a plan or card: advisory like a resume message, session-scoped (the session is on no plan, and connecting is what it is told to do).
+        // DX-4529 - a docs land's conflict job: its line tells the session where to read the job.
+        if (message.event === "docs_land")
+            return emitAdvisory(message, "docs land message", invalidAssignmentReason, (p) => formatAssignmentLine(p), () => ({ source: "docs_land" }));
+        // DX-6866 - a docs draft owed on this session's plan: the same one-line frame.
+        if (message.event === "docs_draft")
+            return emitAdvisory(message, "docs draft message", invalidAssignmentReason, (p) => formatAssignmentLine(p), () => ({ source: "docs_draft" }));
+        if (message.event === "assignment")
+            return emitAdvisory(message, "assignment message", invalidAssignmentReason, (p) => formatAssignmentLine(p), () => ({ source: "assignment" }), "session");
+        // DX-4993 - the compaction control: level-triggered, no id, no replay. A frame that cannot be read is a fault line (never silence), and the next frame still lands.
+        if (message.event === "compaction")
+            return emitControl(message, "compaction control", invalidCompactionReason, (p) => ({ type: "compaction", control: controlOfFrame(p) }));
+        // DX-6692 - the clear control of a ready-list session whose job has ended: level-triggered like `compaction`.
+        if (message.event === "clear")
+            return emitControl(message, "clear control", invalidClearReason, (p) => ({ type: "clear", control: clearControlOfFrame(p) }));
+        if (message.event === "team_agent_created")
+            return emitAgentCreated(message);
+        if (message.event !== "activity")
+            return null;
+        // `Number(null)` is 0, so a frame with no id must never be read as event 0: that id
+        // would become a `Last-Event-ID` the dashboard refuses, ending the listener.
+        const id = message.id === null ? Number.NaN : Number(message.id);
+        const knownId = Number.isSafeInteger(id) && id > 0;
+        if (knownId && delivered.has(id))
+            return null;
+        // DX-2735: an event that is not JSON, or JSON of the wrong shape, is reported
+        // from an explicit check naming the fault — never from a TypeError thrown
+        // partway through describing it. Never silence, and never a reconnect loop on
+        // the same bad event: say so in one line and move past it.
+        let parsed;
+        let invalid;
+        try {
+            parsed = JSON.parse(message.data);
+            invalid = invalidEventReason(parsed);
+        }
+        catch (err) {
+            invalid = `not JSON: ${err.message}`;
+        }
+        const text = invalid === null
+            ? formatActivityLine(parsed)
+            : `${LINE_PREFIX} could not read event ${message.id ?? "(no id)"} (${invalid}): ` +
+                // DX-2735: oneLine caps by code point, so a bad event carrying an emoji
+                // at the cut can never leave a lone surrogate in the line.
+                oneLine(message.data, 300);
+        // DX-2730 D4 — an event this listener could not parse carries `origin: null`
+        // (emit immediately) rather than the unreadable payload's own claimed
+        // origin: a fault worth surfacing at all must never be hidden behind a
+        // 10-minute digest wait just because it happened to come from an agent or
+        // a machine writer.
+        const release = invalid === null && parsed.release === true;
+        const acks = invalid === null ? (parsed.acks ?? []) : [];
+        // DX-5846: a repeat of an event nobody acknowledged is the dashboard asking again: emitted at once like a pause release (never held for a digest, which would wait out the next attempt too).
+        const resent = acks.some((a) => a.attempt > 1);
+        // DX-4951: a pause release is the session's own notice: emitted at once (`origin: null`), and kept across a plan move (`scope: "session"`).
+        const origin = invalid === null && !release && !resent ? parsed.origin : null;
+        // DX-4721: an unreadable event is a fault line; a readable one is urgent by its kind (none is today).
+        const urgent = isUrgent(invalid === null ? { source: "activity", kind: parsed.kind } : { source: "fault" });
+        deps.write({ type: "event", id: knownId ? id : null, text, origin, urgent, acks, ...(release ? { scope: "session" } : {}) });
+        if (knownId)
+            remember(id);
+        return null;
+    };
+    const connectOnce = async () => {
+        const controller = new AbortController();
+        // DX-3099 — hand THIS attempt's own abort to the caller before doing
+        // anything else, so a force-reconnect requested at any point during the
+        // attempt (including before the fetch even starts) targets exactly this
+        // controller, never a stale one from a previous attempt.
+        deps.onConnectionAttempt?.(() => controller.abort());
+        deps.signal?.addEventListener("abort", () => controller.abort(), { once: true });
+        let idle;
+        const armIdle = () => {
+            clearTimeout(idle);
+            idle = setTimeout(() => controller.abort(), deps.readIdleTimeoutMs);
+        };
+        const headers = {
+            Authorization: `Bearer ${options.ticket}`,
+            Accept: "text/event-stream",
+            // DX-5846: says this reader understands `acks` and shows the instruction to acknowledge; the dashboard stamps and re-sends only to a connection that sends it (an older reader would drop a repeat it cannot act on).
+            "X-Danx-Ack": "1",
+        };
+        if (lastEventId !== null)
+            headers["Last-Event-ID"] = String(lastEventId);
+        const openedAt = deps.now();
+        let gotEvent = false;
+        const healthy = () => gotEvent || 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)) {
+                const text = await response.text();
+                return { kind: "refused", detail: `HTTP ${response.status} ${oneLine(text, 300)}` };
+            }
+            if (!response.ok || response.body === null) {
+                await response.body?.cancel();
+                return { kind: "dropped", healthy: false, detail: `HTTP ${response.status} with no readable body` };
+            }
+            // DX-6272: the stream says which relay version it needs; a relay below it reads no frame, so it cannot misread one into a line that wakes the session. A malformed floor throws (a named drop), never reads as no floor.
+            const floor = response.headers.get(MCP_STREAM_MIN_VERSION_HEADER);
+            if (floor !== null && ownVersionBelow(floor)) {
+                await response.body?.cancel();
+                return { kind: "outdated", detail: floor };
+            }
+            // DX-3028 — the connection is genuinely open and readable now; see
+            // `ListenDeps.onState`'s docblock for exactly what this reports.
+            deps.onState?.("streaming");
+            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")
+                        gotEvent = true;
+                }
+            }
+            return { kind: "dropped", healthy: healthy() };
+        }
+        catch (err) {
+            // DX-2829 — was a bare `catch { ... }` that discarded the causing error
+            // entirely: a connection that failed the same way on every retry (DNS
+            // failure, TLS reset, the idle-timeout abort) surfaced nothing beyond
+            // "no healthy connection" once the lease finally expired. Preserving the
+            // message here is what lets `runListener` name the actual last failure
+            // in its final `lease_expired` stop record below.
+            return { kind: "dropped", healthy: healthy(), detail: describeDropError(err) };
+        }
+        finally {
+            clearTimeout(idle);
+            controller.abort();
+        }
+    };
+    for (;;) {
+        if (deps.signal?.aborted)
+            return 0;
+        const outcome = await connectOnce();
+        // DX-4233 - cancelled while connected: the outcome of an attempt the owner abandoned is not the owner's to hear.
+        if (deps.signal?.aborted)
+            return 0;
+        if (outcome.kind === "ended") {
+            if (outcome.reason === "superseded" || outcome.reason === "replaced") {
+                return stop(outcome.reason, "another listener for this session took over", 0);
+            }
+            return stop(outcome.reason, "the dashboard ended this listener", 1);
+        }
+        if (outcome.kind === "outdated") {
+            return stop("mcp_outdated", `this session's platform MCP is version ${readOwnVersion()}, and the dashboard's event stream needs ${outcome.detail} or newer, so this session's events stop here`, 1);
+        }
+        if (outcome.kind === "refused") {
+            return stop("refused", `the dashboard refused the listener ticket: ${outcome.detail}`, 1);
+        }
+        // DX-5088: the stream is down from here until the next attempt opens; reporting `streaming` through the backoff made the heartbeat watchdog
+        // call a dashboard outage "a stream that looks open" and abort the reconnect it was waiting on.
+        deps.onState?.("reconnecting");
+        if (outcome.detail !== undefined)
+            lastDropDetail = outcome.detail;
+        if (outcome.healthy) {
+            unhealthySince = null;
+            attempt = 0;
+        }
+        const now = deps.now();
+        unhealthySince ??= now;
+        if (now - unhealthySince >= options.leaseMs) {
+            // DX-2829 — names the last connection failure when one was ever recorded,
+            // instead of only reporting the timeout itself.
+            const cause = lastDropDetail === null ? "" : ` — last connection attempt failed: ${lastDropDetail}`;
+            return stop("lease_expired", `no healthy connection to ${options.streamUrl} for ${Math.round((now - unhealthySince) / 60_000)} minutes, past the ticket's lease${cause}`, 1);
+        }
+        await deps.sleep(Math.min(MAX_BACKOFF_MS, INITIAL_BACKOFF_MS * 2 ** attempt));
+        attempt += 1;
+    }
+}