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

package/dist/session-stream.js

@@ -0,0 +1,345 @@
+/**
+ * DX-4233 - the dashboard HTTP contract of a session's event stream, spoken by the in-process relay behind
+ * `plan_events_wait` (`plan-events-relay.ts`).
+ *
+ * One authenticated request with a timeout, the listener-ticket mint, the best-effort plan inventory read and the 15 s
+ * heartbeat. Everything here is about talking to the dashboard; WHEN to talk (the mint/stream loop, the heartbeat schedule,
+ * what a stop means for the session) belongs to the relay.
+ */
+import { errorCodeOf } from "./json-body.js";
+import { boundRequest } from "./request-bound.js";
+import { keyRevocationOf, keyRevokedHalt } from "./key-revoked-halt.js";
+import { oneLine } from "./one-line.js";
+import { PLUGIN_BACKGROUND_HEADER, SESSION_ID_HEADER } from "./session-options.js";
+import { isClaimState } from "@50arms/session-telemetry";
+/**
+ * DX-3912 — the longest heartbeat `reason` the relay sends: one under the dashboard's own
+ * limit (`HEARTBEAT_REASON_MAX_CHARS` = 200, `src/issues/db/plan-session-heartbeat.ts`),
+ * because `oneLine` appends a "…" to a truncated string and a longer reason refuses the whole
+ * heartbeat. `plan-events-wait.test.ts` asserts the cap.
+ */
+const HEARTBEAT_REASON_MAX_CODE_POINTS = 199;
+export const STREAM_TICKET_PATH = "/api/plan-sessions/me/stream-ticket";
+// DX-2970 — the bare (no `fields=`) cheap-scalars read, used ONLY to report the
+// connected plan's real `boards`/`cardCount` on the `ready` record (see
+// `fetchPlanInventory`). This is NOT a revival of DX-2920's deleted
+// `verifyPlanBoardsReadable` gate — it never refuses a mint, never blocks
+// streaming, and is best-effort (one attempt, no retry/backoff).
+export const PLAN_MINE_PATH = "/api/plans/mine";
+// DX-3028 (AC1) — `POST /api/plan-sessions/me/heartbeat` (DX-2952's server
+// route, `plan-sessions-routes.ts#handleHeartbeat`). Every 15s this process
+// reports its truthful streaming state; see `sendHeartbeat` below.
+export const HEARTBEAT_PATH = "/api/plan-sessions/me/heartbeat";
+/** How long one dashboard request may take before it counts as a transient failure. */
+export const REQUEST_TIMEOUT_MS = 10_000;
+/** A freshly minted ticket refused this many times in a row is a terminal outcome, not a loop. */
+export const MAX_REFUSED_TICKETS_IN_A_ROW = 2;
+/** DX-3028 (AC1) — the dashboard's own heartbeat cadence; see the card's AC1. */
+export const HEARTBEAT_INTERVAL_MS = 15_000;
+/**
+ * DX-3099 — how many consecutive 15s heartbeat POSTs may fail to LAND
+ * (network error, timeout, 5xx, 408/429 — never an ordinary 401/403 answer,
+ * which proves the pipe itself still works) while this process still
+ * believes it is `"streaming"`, before that counts as evidence the current
+ * stream connection is dead without having errored — the exact "alive but
+ * not reporting" signature the investigation found: the SSE connection can
+ * read as established at the OS level and never trip `listen.ts`'s own
+ * read-idle timeout, while every outbound heartbeat silently never lands
+ * (the send call's own result used to be discarded entirely — see the
+ * card). `3 * HEARTBEAT_INTERVAL_MS` = 45s, deliberately UNDER
+ * `SESSION_LIVENESS_WINDOW_MS` (60s, `plan-session-heartbeat.ts`) so this
+ * process self-heals before, or right around, the moment the dashboard
+ * would itself start reporting the session `unattached` — never a shorter
+ * freshness window (that constant is untouched) and never a blind
+ * "restart more eagerly" (no external watchdog, no timer-driven kill): this
+ * fires only on repeated, OBSERVED delivery failure, self-diagnosed by the
+ * SAME process that is already streaming. Card: DX-3099 (AC3 forbids both
+ * of the obvious wrong fixes this constant is not).
+ */
+export const HEARTBEAT_SILENT_FAILURE_THRESHOLD = 3;
+/**
+ * DX-5088 - how long the heartbeat must keep failing to land (counted from the first failure, across every reconnect, until one
+ * lands) before the MODEL is told. 5 minutes: a production deploy replaces the single dashboard container, an outage the
+ * investigation measured at about 35 s (DX-5085 comment 14821), and the lock-convoy stalls around it ran 8-27 s more; 5 minutes is
+ * roughly 8x the restart, so a deploy never wakes a session, while an outage that outlasts it is one the session's person should hear
+ * about (the dashboard has long read the session `unattached`). Below it the self-heal is silent and logged to stderr.
+ */
+export const HEARTBEAT_SUSTAINED_OUTAGE_MS = 5 * 60_000;
+const TRANSIENT_CLIENT_STATUSES = new Set([408, 429]);
+/**
+ * One authenticated request, with a timeout, classifying the failures that are
+ * about THIS MOMENT (network, timeout, 408/429, 5xx) as transient. Shared by
+ * every request this module makes so they can never disagree about which
+ * failures are worth retrying.
+ */
+async function request(options, deps, what, url, init = { method: "GET" }) {
+    const bound = boundRequest(deps.requestTimeoutMs, deps.signal);
+    try {
+        let status;
+        let text;
+        try {
+            const headers = {
+                Authorization: `Bearer ${options.token}`,
+                Accept: "application/json",
+                [SESSION_ID_HEADER]: options.sessionId,
+                // DX-5076: every request this module makes is the relay's own work (ticket mint, inventory read, heartbeat), never the agent acting, so it must not end an agent pause. One marking point, so a new request here cannot forget it.
+                [PLUGIN_BACKGROUND_HEADER]: "1",
+            };
+            if (init.body !== undefined)
+                headers["Content-Type"] = "application/json";
+            const response = await deps.fetch(url, {
+                method: init.method,
+                headers,
+                body: init.body,
+                signal: bound.signal,
+            });
+            status = response.status;
+            text = await response.text();
+        }
+        catch (err) {
+            return {
+                kind: "transient",
+                detail: bound.aborted()
+                    ? `${what} timed out after ${deps.requestTimeoutMs} ms`
+                    : `${what} failed: ${err.message}`,
+            };
+        }
+        if (status >= 500 || TRANSIENT_CLIENT_STATUSES.has(status)) {
+            return { kind: "transient", detail: `${what} HTTP ${status}` };
+        }
+        let body = null;
+        try {
+            body = text === "" ? null : JSON.parse(text);
+        }
+        catch {
+            body = null;
+        }
+        return { kind: "answer", status, text, body };
+    }
+    finally {
+        bound.release();
+    }
+}
+/** What is wrong with a 2xx mint body, or `null` when it is a ticket. Never echoes the body. */
+function badTicketReason(body) {
+    if (typeof body !== "object" || body === null)
+        return "the body is not a JSON object";
+    const b = body;
+    if (typeof b.ticket !== "string" || b.ticket === "")
+        return "ticket is not a non-empty string";
+    if (typeof b.streamPath !== "string" || !b.streamPath.startsWith("/"))
+        return "streamPath is not a path";
+    if (typeof b.leaseMs !== "number" || !Number.isSafeInteger(b.leaseMs) || b.leaseMs <= 0) {
+        return "leaseMs is not a positive integer";
+    }
+    return null;
+}
+/** Mint this session's listener ticket, classifying every way that can end. */
+export async function mintTicket(options, deps) {
+    const outcome = await request(options, deps, "ticket mint", `${options.dashboardUrl}${STREAM_TICKET_PATH}`, {
+        method: "POST",
+        body: "{}",
+    });
+    if (outcome.kind === "transient")
+        return outcome;
+    const { status, text, body } = outcome;
+    // DX-4882: a session on no plan is minted a ticket like any other (its stream carries its account's pacing and resume messages), so
+    // `409 session_not_connected` is no longer an answer the mint gives.
+    // DX-3028 (AC2) — matched BEFORE the generic mint_refused fallback below,
+    // which every other 409 falls into: this session id belongs to a worker
+    // dispatch (`SessionIsWorkerError`, the same shape the heartbeat route
+    // already gives it, DX-2952).
+    if (status === 409 && errorCodeOf(body) === "session_is_worker") {
+        return { kind: "terminal", reason: "session_is_worker", detail: "this session id belongs to a worker dispatch, not an operator plan session" };
+    }
+    // DX-4418 - a key a person revoked is not a lapsed one: the detail IS the stop halt (who revoked it, what to do), so the record
+    // the plugin relays to the session says it in full.
+    const revocation = keyRevocationOf({ ok: false, status, body });
+    if (revocation !== null) {
+        return { kind: "terminal", reason: "key_revoked", detail: keyRevokedHalt(revocation, false) };
+    }
+    if (status === 401 || status === 403) {
+        return { kind: "terminal", reason: "unauthorized", detail: `ticket mint HTTP ${status} ${oneLine(text, 300)}` };
+    }
+    if (status < 200 || status >= 300) {
+        return { kind: "terminal", reason: "mint_refused", detail: `ticket mint HTTP ${status} ${oneLine(text, 300)}` };
+    }
+    const bad = badTicketReason(body);
+    if (bad !== null) {
+        return { kind: "terminal", reason: "mint_bad_response", detail: `ticket mint HTTP ${status}: ${bad}` };
+    }
+    const ticket = body;
+    return {
+        kind: "ticket",
+        ticket: ticket.ticket,
+        streamUrl: `${options.dashboardUrl}${ticket.streamPath}`,
+        leaseMs: ticket.leaseMs,
+    };
+}
+/**
+ * What is wrong with a 2xx bare `/api/plans/mine` body, or `null` when it carries a usable inventory.
+ *
+ * DX-3912 — the field names here are the plan resource's WIRE names (`boards`, `card_count`,
+ * snake_case since DX-3428), the same ones `src/resources/plan/plan-resource.ts` emits; the
+ * contract test `src/issues/__tests__/plan-inventory-relay-contract.test.ts` runs this parser
+ * on the server's own response, so a rename there fails that test instead of silently
+ * degrading every listener. A missing field lists the keys the body DID carry, so a rename is
+ * named in the first message anyone reads.
+ */
+function badInventoryReason(body) {
+    if (!isRecord(body))
+        return "the body is not a JSON object";
+    if (!("boards" in body))
+        return `boards is missing (response keys: ${Object.keys(body).join(", ")})`;
+    if (!Array.isArray(body.boards) || body.boards.some((x) => typeof x !== "number" || !Number.isSafeInteger(x) || x <= 0)) {
+        return "boards is not an array of board ids (positive integers)";
+    }
+    if (!("card_count" in body))
+        return `card_count is missing (response keys: ${Object.keys(body).join(", ")})`;
+    const count = body.card_count;
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) {
+        return `card_count is not a non-negative integer (got ${typeof count === "number" ? count : typeof count})`;
+    }
+    return null;
+}
+/**
+ * DX-2970 — a single BEST-EFFORT read of the connected plan's real
+ * `boards`/`cardCount`, purely for accurate `ready`-record reporting. NEVER a
+ * gate: unlike DX-2920's deleted `verifyPlanBoardsReadable`, a failure here
+ * (network, timeout, non-2xx, unusable body) is NOT retried and NEVER blocks
+ * or delays streaming — the relay reports `degraded: true` with `boards`/
+ * `cardCount` both `null` and proceeds exactly as it would have before this
+ * read existed. The bare (no `fields=`) call is deliberately the cheapest
+ * read the route offers — the plan's own "cheap scalars," always present on
+ * every `GET /api/plans/mine` response regardless of `fields`.
+ */
+export async function fetchPlanInventory(options, deps) {
+    const outcome = await request(options, deps, "plan inventory read", `${options.dashboardUrl}${PLAN_MINE_PATH}`);
+    if (outcome.kind === "transient")
+        return { kind: "unavailable", detail: outcome.detail };
+    const { status, text, body } = outcome;
+    if (status < 200 || status >= 300) {
+        return { kind: "unavailable", detail: `plan inventory read HTTP ${status} ${oneLine(text, 300)}` };
+    }
+    const bad = badInventoryReason(body);
+    if (bad !== null) {
+        return { kind: "unavailable", detail: `plan inventory read HTTP ${status}: ${bad}` };
+    }
+    const b = body;
+    return { kind: "ok", boards: b.boards, cardCount: b.card_count };
+}
+/**
+ * The one real `scheduleInterval`: a `setInterval` and its canceler, for the relay's heartbeat. Unref'd: a heartbeat never keeps
+ * the MCP server alive after its session ended.
+ */
+export function realScheduleInterval(tick, ms) {
+    const timer = setInterval(tick, ms);
+    timer.unref();
+    return { stop: () => clearInterval(timer) };
+}
+/**
+ * The one real sleep of the relay's mint / stream loop: unref'd, so a backoff never keeps the MCP server alive after its session
+ * ended, and cut short by `signal` (the run was ended), so a suspended relay does not leave a timer behind.
+ */
+export function realSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        timer.unref();
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/**
+ * The truthful `connection` for a heartbeat: `streaming` only while the SSE connection is open (with whether the plan
+ * inventory read worked), `stopped` with the reason the stream ended, otherwise `reconnecting`.
+ */
+export function heartbeatConnection(state, stoppedReason, inventoryError) {
+    if (state === "streaming") {
+        return inventoryError === null
+            ? { state, inventory: "ok" }
+            : { state, inventory: "unavailable", reason: oneLine(inventoryError, HEARTBEAT_REASON_MAX_CODE_POINTS) };
+    }
+    return state === "stopped" ? { state, reason: stoppedReason ?? undefined } : { state };
+}
+/**
+ * One heartbeat POST. Never throws on a failure of the request itself and NEVER stops the relay on one
+ * (the one throw is a contract breach: a `key_revoked` answer that does not say who revoked the key, DX-4418; `heartbeatTick`'s
+ * `.catch` keeps it from taking the relay down) (card AC1 — "a failed heartbeat never stops the relay"): `request()`
+ * itself already classifies every network/timeout/5xx failure as
+ * `{kind:"transient"}` rather than throwing, and a 401/403 (a revoked
+ * credential) simply comes back as an ordinary non-2xx answer this function
+ * discards — there is nothing meaningful to retry a heartbeat POST for, and
+ * the NEXT tick will just try again. A heartbeat refused with 401/403 cannot
+ * report itself, so `computeListenerHealth`'s staleness fallback
+ * (`heartbeatIsFresh`) is what eventually reflects it: the row's
+ * `last_heartbeat_at` stops advancing, and once it falls outside
+ * `SESSION_LIVENESS_WINDOW_MS` the badge reads `unattached`, NOT
+ * `credential_mismatch` — `credential_mismatch` is computed only from a
+ * heartbeat that DID land with `state:"streaming"` and a live ticket whose
+ * issuer hash differs from the caller's; it has no way to represent "the
+ * heartbeat call itself was rejected". This gap is real and is recorded on
+ * the card rather than silently papered over.
+ */
+export async function sendHeartbeat(options, deps, connection, stats, 
+// DX-4461 - the session's current Claude title, read from its transcript (`session-title.ts`).
+title, 
+// DX-6367 - this relay already holds the stored stats; the dashboard then answers a stats-free heartbeat without them. Sent only to a dashboard that said it accepts it.
+statsHeld) {
+    const body = { state: connection.state };
+    if (connection.reason !== undefined)
+        body.reason = connection.reason;
+    if (connection.inventory !== undefined)
+        body.inventory = connection.inventory;
+    const outcome = await request(options, deps, "heartbeat", `${options.dashboardUrl}${HEARTBEAT_PATH}`, {
+        method: "POST",
+        body: JSON.stringify({ connection: body, ...(stats !== undefined ? { stats } : {}), ...(title !== undefined ? { title } : {}), ...(statsHeld === true ? { statsHeld } : {}) }),
+    });
+    // DX-3099 — this is now the ONE place a heartbeat's own outcome is
+    // inspected. `request()` still never throws, and a 401/403 is still an
+    // ordinary answer this function does not retry for (the credential is
+    // whatever it is; there is nothing to redo about THIS request) — only a
+    // "transient" outcome (network error, timeout, 5xx, 408/429) means the
+    // request never landed at all, which is exactly the signal the silent-
+    // failure counter in the relay below needs. Still never throws.
+    if (outcome.kind !== "answer")
+        return { landed: false, status: null, stats: null, statsNotStored: null, acceptsStatsHeld: false, revocation: null, title: null };
+    // DX-2954 — the answer's `stats` (the operator dispatch's stored or
+    // just-written totals and cursors) feed the session's stats collector.
+    const ok = outcome.status >= 200 && outcome.status < 300;
+    // A heartbeat whose carried stats were NOT applied (`statsError`) still
+    // landed; its `stats` are the stored values, so the collector must re-queue
+    // rather than treat them as the answer to its write.
+    const applied = ok && isRecord(outcome.body) && outcome.body.statsError === undefined;
+    const statsBody = applied && isRecord(outcome.body) && isRecord(outcome.body.stats) ? outcome.body.stats : null;
+    // DX-3962: an answer from a server that predates attribution stores cursors with no `claims`. Treated exactly like
+    // an answer with no stats (the older-server path): the collector never starts, the heartbeat still lands, and
+    // nothing is recorded until the server is deployed. Handing it on would crash the collector at attach.
+    const answered = statsBody !== null &&
+        isRecord(statsBody.sourceCursors) &&
+        isRecord(statsBody.totals) &&
+        Object.values(statsBody.sourceCursors).every((cursor) => isRecord(cursor) && isClaimState(cursor.claims))
+        ? statsBody
+        : null;
+    // DX-4418 - the dashboard refuses the beat of a session whose key a person revoked, and says so.
+    // DX-4461 - the dashboard's stored title for this session; an answer without one is an older dashboard's.
+    const storedTitle = ok && isRecord(outcome.body) && typeof outcome.body.title === "string" ? outcome.body.title : null;
+    return {
+        landed: true,
+        status: outcome.status,
+        stats: answered,
+        acceptsStatsHeld: ok && isRecord(outcome.body) && outcome.body.acceptsStatsHeld === true,
+        // DX-4892: the dashboard says why carried stats were not stored (a session on no plan), instead of the relay inferring it from a missing `stats`.
+        statsNotStored: ok && isRecord(outcome.body) && isRecord(outcome.body.statsError) && outcome.body.statsError.kind === "no_plan" ? "no_plan" : null,
+        revocation: keyRevocationOf({ ok: false, status: outcome.status, body: outcome.body }),
+        title: storedTitle,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/session-title.js

@@ -0,0 +1,129 @@
+/**
+ * DX-4461 - a session's live Claude title, read from its own transcript with no help from the agent.
+ *
+ * WHY THE TRANSCRIPT. The dashboard stores a plan session's title, and until now it arrived only as the `title`
+ * argument of `plan_connect`, so a session renamed afterwards showed a stale name until the agent happened to connect
+ * again. DX-2816 found no env var, hook input or MCP-reachable signal carrying the title, but Claude Code writes every
+ * title change into the session's transcript as a `{"type":"custom-title","customTitle":"..."}` line the moment the
+ * rename happens, even while the session is idle (observed on session 952f0739: 76 records of the old title, then the
+ * renamed one, no turn in between). the relay already holds the transcript path (the plugin passes the hook input's
+ * `transcript_path` as the `transcript_path` argument, `session-stats.ts`), so it reads the last such record on each
+ * heartbeat and reports it when it differs from the title the dashboard answered with (the relay); the dashboard
+ * stores it (`plan-sessions-routes.ts`).
+ *
+ * INCREMENTAL, NEVER A RE-READ. The reader remembers how far it has scanned (always a line boundary) and the title it
+ * found, so a heartbeat reads only the bytes appended since the last one. The first read of a long transcript is
+ * bounded to its last {@link TRANSCRIPT_TITLE_MAX_SCAN_BYTES}: Claude Code repeats the record on every turn, so the
+ * latest one is always near the end, and a transcript with none in that window has nothing to report.
+ *
+ * It reads synchronously on purpose: the relay's heartbeat tick is synchronous up to its first request, and a read
+ * of a few appended kilobytes every 15 seconds costs less than the plumbing an async read would need.
+ */
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { stripSessionTitleMarks } from "@50arms/session-telemetry";
+/**
+ * The longest title the dashboard accepts (`SESSION_TITLE_MAX_CHARS`, `src/issues/db/plan-sessions.ts`, counted in
+ * UTF-16 units). A longer one would 400 the whole heartbeat, which is liveness, so the reader cuts it first.
+ */
+export const SESSION_TITLE_MAX_CHARS = 200;
+/** How much of a transcript's end the first read looks at. */
+export const TRANSCRIPT_TITLE_MAX_SCAN_BYTES = 2 * 1024 * 1024;
+/** The marker of a title record. A message quoting it carries escaped quotes, so it never matches. */
+const TITLE_RECORD_MARKER = '"type":"custom-title"';
+export class TranscriptTitleReader {
+    path;
+    /** Offset just past the last complete line already scanned; always 0 or a line boundary. */
+    scannedTo = 0;
+    title = null;
+    constructor(path) {
+        this.path = path;
+    }
+    /**
+     * The session's current title, or `null` when its transcript has none (yet). Throws on a transcript this cannot
+     * read, or a complete title record that is not JSON: the caller decides what a failed read costs.
+     */
+    read() {
+        const fd = this.open();
+        if (fd === null)
+            return this.title;
+        try {
+            const size = fstatSync(fd).size;
+            if (size < this.scannedTo) {
+                // The file was rewritten shorter than what was already scanned; nothing remembered about it holds.
+                this.scannedTo = 0;
+                this.title = null;
+            }
+            if (size === this.scannedTo)
+                return this.title;
+            const start = Math.max(this.scannedTo, size - TRANSCRIPT_TITLE_MAX_SCAN_BYTES);
+            const buf = Buffer.alloc(size - start);
+            let filled = 0;
+            while (filled < buf.length) {
+                const n = readSync(fd, buf, filled, buf.length - filled, start + filled);
+                if (n === 0)
+                    break;
+                filled += n;
+            }
+            const lastNewline = buf.subarray(0, filled).lastIndexOf(0x0a);
+            if (lastNewline === -1)
+                return this.title;
+            const lines = buf.subarray(0, lastNewline).toString("utf8").split("\n");
+            // A region that starts mid-file (the first read of a long transcript) begins inside a line.
+            if (start !== this.scannedTo)
+                lines.shift();
+            this.scannedTo = start + lastNewline + 1;
+            for (let i = lines.length - 1; i >= 0; i--) {
+                if (!lines[i].includes(TITLE_RECORD_MARKER))
+                    continue;
+                this.title = parseTitleRecord(lines[i], this.path);
+                break;
+            }
+            return this.title;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    /** The transcript's descriptor, or `null` when it does not exist yet (Claude Code creates it on the first turn). */
+    open() {
+        try {
+            return openSync(this.path, "r");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+}
+function parseTitleRecord(line, path) {
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch (err) {
+        throw new Error(`a custom-title line in ${path} is not JSON: ${err.message}`);
+    }
+    const customTitle = record?.customTitle;
+    if (typeof customTitle !== "string")
+        return null;
+    // DX-6078: the plugin's display marks are dropped by the one list the dashboard also strips on every title write.
+    const trimmed = stripSessionTitleMarks(customTitle.trim());
+    return trimmed === "" ? null : boundTitle(trimmed);
+}
+/**
+ * At most {@link SESSION_TITLE_MAX_CHARS} UTF-16 units, cut on a code-point boundary. A cut that lands after a space is
+ * trimmed again: the dashboard stores the trimmed title, so an untrimmed one would never equal it and the relay would
+ * resend it on every heartbeat.
+ */
+function boundTitle(title) {
+    if (title.length <= SESSION_TITLE_MAX_CHARS)
+        return title;
+    let out = "";
+    for (const point of title) {
+        if (out.length + point.length > SESSION_TITLE_MAX_CHARS)
+            break;
+        out += point;
+    }
+    return out.trimEnd();
+}

package/dist/shutdown.js

@@ -0,0 +1,38 @@
+/**
+ * DX-4523 / DX-4233 - what the server lets go of when its session ends: the permission watch's open stream and the plan event
+ * relay (its pending call, stream, heartbeat and tailer), so nothing keeps the process alive after the client is gone.
+ *
+ * Three triggers, all needed: the transport's `onclose` (an orderly close of the connection), the end of stdin (the SDK's stdio
+ * transport does not watch stdin for its end, so a client that simply exits would leave the process running without it), and a
+ * SIGTERM / SIGINT.
+ *
+ * DX-5415: `stop` returns the relay's bounded final settle (a sub-agent's held final report is stored before the collector stops).
+ * The first two triggers leave the process to end on its own once nothing keeps it alive, so the settle completes. A signal would
+ * kill it mid-settle, so its handler awaits `stop` and only then exits. The handler is `once` per signal: a second signal of the
+ * SAME kind takes the default action, but a DIFFERENT one (SIGTERM then SIGINT) runs the handler again, which is safe because
+ * `stop` is idempotent. The settle is bounded (10 s), yet a parent that signals with an SDK client allows only about 4 s before
+ * it sends SIGKILL, so the held finals are stored best-effort within that window, not guaranteed.
+ */
+export function stopWhenSessionEnds(wiring) {
+    wiring.server.onclose = wiring.stop;
+    wiring.stdin.once("end", wiring.stop);
+    const exitAfterStop = () => {
+        // A synchronous throw from `stop` takes the same "shutdown failed" path as a rejection.
+        void Promise.resolve().then(wiring.stop).then(() => wiring.exit(0), (err) => {
+            process.stderr.write(`platform-mcp: shutdown failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            wiring.exit(1);
+        });
+    };
+    wiring.signals.once("SIGTERM", exitAfterStop);
+    wiring.signals.once("SIGINT", exitAfterStop);
+}
+/**
+ * DX-5415: the server's stop callback, the one link from every shutdown trigger to the relay's settle: it returns the relay's
+ * pending `close()` so a signal handler can wait for it before exiting.
+ */
+export function makeSessionStop(permissionWatch, planEventRelay) {
+    return () => {
+        permissionWatch.stop();
+        return planEventRelay.close();
+    };
+}

package/dist/stop-fixes.js

@@ -0,0 +1,50 @@
+/**
+ * DX-4233 - the remedy a session is shown for each way its dashboard event stream can stop, in ONE place.
+ *
+ * The client that ends in these texts is the in-process relay behind `plan_events_wait` (`plan-events-relay.ts`); `session-options.ts` uses
+ * `fixForStop` for a start it cannot make. Pure data and one function with no imports.
+ */
+/**
+ * The remedy per terminal reason. ONE map, so the message a session is shown and the message a log carries can never drift.
+ * `KnownStopReason` is only a SUBSET of `ListenStopReason` (which also has `unknown`, for a newer dashboard's wire reason this
+ * build predates), so `fixForStop` accepts a plain string and falls back to `DEFAULT_STOP_FIX`.
+ *
+ * DX-4233 - the texts name the session's listener, never a process: with the relay inside the session's own MCP server there
+ * is no separate process to restart.
+ */
+const RESTART_NOTICE_STOP_LEAD = "continue without it";
+const RESTART_NOTICE_STOP_TAIL = "call plan_connect to connect this session to a plan";
+export const STOP_FIXES = {
+    no_connection_record: "call plan_connect again in this session — its platform MCP server records the connection that restart_notice and the listener reminder read " +
+        "(a server older than the one that introduced the record writes none)",
+    credential_unavailable: "call plan_connect again to request access: this session's key file is missing or unreadable",
+    credential_mismatch: "restart this Claude Code session so its MCP server resolves its credential afresh, then call plan_connect again",
+    not_connected: "call plan_connect to connect this session to a plan",
+    plan_archived: "the plan was archived or deleted, so this session was disconnected; ask the operator to restore it, then call plan_connect again",
+    unauthorized: "the dashboard no longer accepts this session's key (it lapsed after a day unused): call plan_connect again to request access",
+    key_revoked: "stop all work now, commit your work in progress and end this session: the person who owns this session's access revoked it; " +
+        "do not call plan_connect or request access again",
+    mint_refused: "check that this session is signed in to the dashboard its MCP server points at, then call plan_connect again",
+    mint_bad_response: "check that DANXBOT_DASHBOARD_URL for this session's MCP server points at a 50 Arms dashboard",
+    // A newer ticket exists (superseded) or another connection is already using this one (replaced): THIS listener is ending
+    // because the session is already served elsewhere, not because anything is broken.
+    superseded: "no action needed — a newer ticket was minted for this session, and a fresh listener is already using it",
+    replaced: "no action needed — another connection is already using this session's ticket; call plan_connect again only if that was unexpected",
+    revoked: "call plan_connect again to mint a new listener ticket for this session",
+    refused: "call plan_connect again to mint a new listener ticket for this session",
+    // DX-6272: calling plan_connect again would reconnect with the same old relay and be refused again.
+    mcp_outdated: "restart this Claude Code session, or reconnect its platform server in /mcp, to install the current version of the MCP server; the dashboard's event stream needs a newer one than this session runs",
+    // DX-3028 - this session id belongs to a worker dispatch; there is no listener ticket a worker session can ever use.
+    session_is_worker: "this session id belongs to a worker dispatch; start a new session",
+    // DX-4632: `restart_notice` only tells a restarted session which plan its predecessor was on; none of its stops blocks anything.
+    no_session_id: `${RESTART_NOTICE_STOP_LEAD}: this server was started without a session id, so it cannot tell which session it replaced; ${RESTART_NOTICE_STOP_TAIL}`,
+    lookup_timeout: `${RESTART_NOTICE_STOP_LEAD}: the dashboard did not answer in time; ${RESTART_NOTICE_STOP_TAIL}`,
+    no_predecessor_record: `${RESTART_NOTICE_STOP_LEAD}: this machine holds no usable record of the named earlier session, so there is nothing to carry over; ${RESTART_NOTICE_STOP_TAIL}`,
+    transcript_unreadable: `${RESTART_NOTICE_STOP_LEAD}: this session's transcript could not be read to find the session it replaced (the detail says why); ${RESTART_NOTICE_STOP_TAIL}`,
+    lookup_failed: `${RESTART_NOTICE_STOP_LEAD}: no earlier session's record could be checked (the detail says why); ${RESTART_NOTICE_STOP_TAIL}`,
+    relay_failed: "the event relay inside this session's platform MCP server failed (the detail says why); the next call tries again, and if it keeps failing restart this Claude Code session",
+};
+export const DEFAULT_STOP_FIX = "call plan_connect again in this session to restart the listener";
+export function fixForStop(reason) {
+    return STOP_FIXES[reason] ?? DEFAULT_STOP_FIX;
+}