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

package/dist/handlers.js

@@ -0,0 +1,385 @@
+/**
+ * Per-tool handlers for the dashboard MCP server.
+ *
+ * Each handler is a pure async function: validate args (Zod at the MCP
+ * boundary), build the HTTP request the corresponding `/api/issues/*`
+ * route expects, and pass the envelope back to the caller verbatim.
+ *
+ * BOARD-ONLY (DX-1171): board is the first-level concept; repo is
+ * DERIVED from board server-side, never passed. Every handler accepts an
+ * optional `board` arg — a board ref (the number that numbers the board within its team, DX-6486 DEC-186). When
+ * set, it overrides the dispatch's configured board for that single call
+ * (forwarded as `?board=<board>` — and into `body.board` for create — so
+ * an agent can target any board). Omitted → falls back to the dispatch's
+ * env-derived board, if any (a board-less server stamps none). The dashboard route validates the board (owning
+ * board→repo) and 404s on unknown; the MCP forwards the refusal envelope
+ * verbatim, never duplicates validation.
+ *
+ * Zero transformation of the server response. Refusal payloads carry
+ * structured detail (`failed_gate`, `non_terminal_phases`,
+ * `offending_keys`, `received_reason`, etc.) that the agent uses to
+ * decide its next move; swallowing any of it would force the agent to
+ * guess.
+ */
+import { posix, win32 } from "node:path";
+import { readFile, stat } from "node:fs/promises";
+// ---------------- plan_connect (DX-2683) ----------------
+// DX-3465 (PLN-11 R-25) — every other per-operation handler that used to
+// live in this file (issue_*, plan_* except plan_connect, brief_*,
+// repo_knowledge_*, failure_category_*, dispatch_transcript_search,
+// quality_gate_instruction) is deleted: `danxbotApi`/`danxbotApiSpec` below
+// are the generic replacement. `plan_connect` stays a dedicated tool because
+// it is session-bound (see `index.ts`'s own comment on this).
+const PLAN_SESSIONS_BASE_PATH = "/api/plan-sessions";
+/**
+ * Connect THIS session to a plan — the same write the operator's Connect
+ * action performs, reaching the same server-side code path. `me` in the URL
+ * is resolved from the forwarded session id, so this can only ever bind the
+ * caller's own session.
+ *
+ * A session already on another plan is MOVED, and the response says which
+ * plan it left (`movedFrom`).
+ *
+ * IT DOES NOTHING ABOUT HEARING THE PLAN'S EVENTS, deliberately. Delivery belongs
+ * to the plan event relay inside this MCP server (`plan_events_wait`, `plan-events-relay.ts`),
+ * which holds the session's ONE listener ticket and is started by the 50arms plugin's loop once this tool
+ * succeeds. The dashboard keeps one ticket per session, so a ticket minted here
+ * would end the relay's stream.
+ *
+ * `title` (DX-2816) rides here, not on a header, because the AGENT — not this
+ * server — can read Claude's own session title at connect time (via a
+ * Desktop-side `get_session` tool no MCP server subprocess can call). Sent
+ * only when the caller supplied one; the server leaves an unset title alone.
+ * The event relay keeps it current afterwards, from the transcript (DX-4461,
+ * `session-title.ts`).
+ */
+export async function planConnect(client, args) {
+    if (args.disconnect === true) {
+        if (args.title !== undefined) {
+            return { ok: false, status: 400, body: { error: "plan_connect: `disconnect: true` takes no `title` — a leave changes no title" } };
+        }
+        // DX-2985 — `DELETE /api/plan-sessions/me/plan?plan_id=`: `me` is the forwarded session id, so only the caller's own session leaves.
+        return client.request({
+            method: "DELETE",
+            path: "/me/plan",
+            basePath: PLAN_SESSIONS_BASE_PATH,
+            query: { plan_id: args.plan_id },
+        });
+    }
+    return client.request({
+        method: "POST",
+        path: "/me/plan",
+        basePath: PLAN_SESSIONS_BASE_PATH,
+        body: {
+            plan_id: args.plan_id,
+            ...(args.title === undefined ? {} : { title: args.title }),
+            ...(args.assignment_id === undefined ? {} : { assignment_id: args.assignment_id }),
+        },
+    });
+}
+/**
+ * DX-5549 - sign THIS session in as a team agent without joining a plan: `POST /api/plan-sessions/me/agent`. `me` is the forwarded session
+ * id, so it can only ever claim for the caller's own session. Answers `state: agent_held` with the agent and the instruction to use its name
+ * and personality, or `agent_needed` / `agent_limit_reached` when the session has none (see `agent-gate.ts`).
+ */
+export async function claimSessionAgent(client) {
+    return client.request({ method: "POST", path: "/me/agent", basePath: PLAN_SESSIONS_BASE_PATH });
+}
+/**
+ * DX-5553 - hold ONE stand-alone card (a card on no plan) instead of a plan, or let it go: `POST|DELETE /api/plan-sessions/me/card`. `me` is the forwarded session id, so only
+ * the caller's own session is ever bound. Like `plan_connect`, the answer carries what the session missed (`missedEvents`) and the exact thread title to take (`naming`); the
+ * session then hears that card's and its descendants' events through the same relay as a plan's.
+ */
+export async function cardConnect(client, args) {
+    if (args.disconnect === true) {
+        if (args.title !== undefined) {
+            return { ok: false, status: 400, body: { error: "card_connect: `disconnect: true` takes no `title` — a leave changes no title" } };
+        }
+        return client.request({ method: "DELETE", path: "/me/card", basePath: PLAN_SESSIONS_BASE_PATH, query: { card_id: args.card_id } });
+    }
+    return client.request({
+        method: "POST",
+        path: "/me/card",
+        basePath: PLAN_SESSIONS_BASE_PATH,
+        body: { card_id: args.card_id, ...(args.title === undefined ? {} : { title: args.title }), ...(args.assignment_id === undefined ? {} : { assignment_id: args.assignment_id }) },
+    });
+}
+// DX-3465 (code-architecture gate finding, at 275f82c0d) — the dedicated
+// `resource_fields` handler (DX-3426) was deleted from here: it was a thin
+// wrapper around `GET /api/resources/:resource/fields`, which `50arms_api`
+// already reaches with nothing agent-specific in it. See `index.ts`'s own
+// note at the former tool-registration site.
+// ---------------- 50arms_api (DX-3465, PLN-11 R-25) ----------------
+export const DANXBOT_API_METHODS = ["GET", "POST", "PATCH", "PUT", "DELETE"];
+export function isDanxbotApiMethod(value) {
+    return typeof value === "string" && DANXBOT_API_METHODS.includes(value);
+}
+/** The file types a `body_file` may carry, by extension; the content type sent is the one the extension names. The one route that takes a file today re-draws each as a PNG (the proposal avatar). */
+export const BODY_FILE_MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+};
+/** The largest `body_file` this server sends: the dashboard's own avatar limit (`AVATAR_MAX_BYTES`, `src/dashboard/avatar-upload.ts`), which this package cannot import. */
+export const MAX_BODY_FILE_BYTES = 1_000_000;
+/** DX-5633: the platform's own path rules (a Windows drive path is absolute only under win32). */
+function pathRulesFor(platform) {
+    return (platform ?? process.platform) === "win32" ? win32 : posix;
+}
+/** A `body_file` checked and read as a raw request body. Every refusal throws before any request is made. */
+async function readRawBodyFile(path, deps) {
+    const { isAbsolute, basename, extname } = pathRulesFor(deps.platform);
+    if (!isAbsolute(path))
+        throw new Error(`50arms_api: body_file must be an absolute path (got "${path}")`);
+    const contentType = BODY_FILE_MIME_BY_EXT[extname(path).toLowerCase()];
+    if (!contentType) {
+        throw new Error(`50arms_api: body_file accepts only ${Object.keys(BODY_FILE_MIME_BY_EXT).join(", ")} files (got "${extname(path) || basename(path)}")`);
+    }
+    // Stat first so an oversized file is refused without being read into memory.
+    const size = await (deps.fileSize ?? (async (p) => (await stat(p)).size))(path);
+    if (size === 0)
+        throw new Error(`50arms_api: body_file "${path}" is empty`);
+    if (size > MAX_BODY_FILE_BYTES)
+        throw new Error(`50arms_api: body_file "${path}" is ${size} bytes; the limit is ${MAX_BODY_FILE_BYTES} (1 MB)`);
+    return { bytes: await (deps.readFile ?? readFile)(path), contentType };
+}
+/**
+ * `50arms_api({method, path, query, body})` — the ONE generic tool that
+ * reaches every dashboard API route this credential is allowed to call
+ * (R-25, DX-3465). Replaces the ~45 per-operation tools this package used to
+ * ship one-for-one against each route: a new route needs a permission and a
+ * spec entry (`50arms_api_spec`), never a new tool.
+ *
+ * The credential lives inside `client` (resolved once at boot — the
+ * operator's declared token file for a session, the per-dispatch
+ * `DANX_DASHBOARD_CREDENTIAL` for a worker) and never appears in this
+ * function's arguments or return value — nothing in `DanxbotApiArgs` can
+ * carry one. The session id (`x-danx-session-id`) rides every call the SAME
+ * way it already does for every other tool on this server
+ * (`http-client.ts#request` stamps it from `config.session`); this tool adds
+ * no special-casing for that.
+ *
+ * `path` MUST start with `/api/` — this is a guardrail against a caller
+ * accidentally reaching for something outside the dashboard's own API
+ * surface (there is nothing else this credential could reach through
+ * `client`'s configured `baseUrl` that would make sense to call this way),
+ * not a route allowlist: the dashboard's own route policy (`authorize()`,
+ * `src/dashboard/route-policy.ts`) is the actual authorization boundary —
+ * an unknown or unauthorized route 404s/401s/403s exactly as it would to any
+ * other caller, and that refusal body (which names the fix — CP1) is
+ * returned verbatim, unmodified, like every other route's response.
+ *
+ * The response is the target route's JSON body, VERBATIM — including its
+ * own `reminders[]` field when the route embeds one (every reminder-
+ * registry row is keyed on `{method, route}` now, DX-3465 item 5, so a
+ * route that used to attach a reminder to a deleted per-operation tool's
+ * response still attaches it here, with zero special MCP-side plumbing).
+ */
+export async function danxbotApi(client, args, deps = {}) {
+    // The file is checked and read BEFORE the request, so a bad path leaves nothing behind on the dashboard.
+    const rawBody = args.body_file === undefined ? undefined : await readRawBodyFile(args.body_file, deps);
+    return client.request({
+        method: args.method,
+        // `basePath: ""` — `path` here is the FULL absolute path already (see
+        // the tool's own docs), unlike every other handler in this file, which
+        // passes a path RELATIVE to a fixed `basePath` (`/api/issues`,
+        // `/api/plans`, ...). This tool has no fixed base; the caller names the
+        // whole route.
+        basePath: "",
+        path: args.path,
+        query: args.query,
+        body: args.body,
+        rawBody,
+        board: args.board,
+        background: args.background,
+    });
+}
+// ---------------- 50arms_api_list (DX-3465 A5, PLN-11 R-25) ----------------
+const ROUTES_BASE_PATH = "/api/routes";
+/**
+ * `50arms_api_list()` — the routes YOUR credential may currently call,
+ * `{routes: ["METHOD /path"]}`, one string each (DX-4401). Backed by DX-3528's
+ * `GET /api/routes`, which filters the served route table through the SAME
+ * `isRouteAuthorizedForPrincipal` check `authorize()` enforces on every
+ * request — a route listed here is always callable, and a route this
+ * credential cannot call never appears. This is how you find the route for
+ * something you need to do: call this first when you don't already know the
+ * path, then `50arms_api_spec({endpoints})` for the exact contract of the
+ * one(s) you picked, then `50arms_api` to call it. No arguments — the
+ * server-side route table has no filter to pass.
+ */
+export async function danxbotApiList(client) {
+    return client.request({
+        method: "GET",
+        path: "",
+        basePath: ROUTES_BASE_PATH,
+    });
+}
+// ---------------- 50arms_api_spec (DX-3465, PLN-11 R-25) ----------------
+const OPENAPI_BASE_PATH = "/api/openapi";
+/**
+ * `50arms_api_spec({endpoints})` — the exact OpenAPI 3.1 contract (DX-3527)
+ * for the named routes: request/response shapes, required permission/
+ * consumer action, and every documented error envelope. Call this before a
+ * `50arms_api` call whose shape you are not already sure of — "a 4xx body
+ * names the fix; check the spec" (the MCP server's own shared instructions).
+ *
+ * Backed by DX-3528's permission-aware `GET /api/openapi` — the SAME
+ * `isRouteAuthorizedForPrincipal` check `50arms_api_list` uses, so an
+ * endpoint this credential may not call refuses loud (400
+ * `invalid_endpoints`, naming it under `unknown` or `disallowed`) rather
+ * than silently documenting a route you cannot actually reach.
+ */
+export async function danxbotApiSpec(client, args) {
+    return client.request({
+        method: "GET",
+        path: "",
+        basePath: OPENAPI_BASE_PATH,
+        query: { endpoints: args.endpoints.join(",") },
+    });
+}
+/**
+ * Extension → MIME map for the agent-attached file types that matter for
+ * downstream rendering (image previews in the dashboard drawer, Trello
+ * card, and Slack thread all key on the persisted `mime`). This package is
+ * a standalone published artifact and cannot import the dashboard
+ * backend's own MIME table, so the small map lives here. An unknown
+ * extension resolves to the generic octet-stream — a sensible default for
+ * "we don't know the type", NOT a silenced error (the bytes still upload +
+ * the row is still written).
+ */
+const MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".csv": "text/csv",
+    ".txt": "text/plain",
+    ".log": "text/plain",
+    ".md": "text/markdown",
+    ".json": "application/json",
+    ".html": "text/html",
+    ".zip": "application/zip",
+    ".gz": "application/gzip",
+    ".tgz": "application/gzip",
+};
+/**
+ * DX-5241: the types and ceiling of `POST /api/uploads/images` (`src/dashboard/uploads-images-route.ts`, no SVG). This package is a separate
+ * published artifact and cannot import them, so they are restated here - keep them in sync with that route. The route enforces both too;
+ * checking here first gives the agent a plain refusal without reading or sending a file the route would refuse.
+ */
+export const INLINE_IMAGE_MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+};
+export const MAX_INLINE_IMAGE_BYTES = 25 * 1024 * 1024;
+export function inferAttachmentMime(filename) {
+    return MIME_BY_EXT[posix.extname(filename).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+ * Attach a local file to a card (`target` "card", the default; replies with the attachment row) or, with `target: "inline_image"`, upload
+ * a local image to `POST /api/uploads/images` and reply `{url, markdown}` (see `uploadInlineImage`). Reads the bytes from the dispatch's
+ * shared filesystem (this MCP server runs co-located with the agent that
+ * calls it), then forwards to the dashboard's `POST /api/issues/:id/attachments`
+ * route (or, with `replaces`, `PUT /api/issues/:id/attachments/:aid`, which swaps that row's bytes in place) — the
+ * SAME ingest the dashboard UI's own upload uses: stores the
+ * bytes in S3, inserts or updates one attachment row, and (via the dashboard's
+ * existing outbound projection) auto-mirrors the file to the card's
+ * linked Trello card and Slack thread. Board-scoped; see `board`.
+ *
+ * Fail-loud (`base:fail-loudly`): `path` is validated (non-empty +
+ * absolute) and the file is read BEFORE any HTTP call, so a bad/missing/
+ * unreadable path throws here and NEVER reaches S3, the DB row, or the
+ * projection. THE FILE'S BYTES NEVER APPEAR IN THIS FUNCTION'S ARGUMENTS
+ * OR IN THE AGENT'S OWN TRANSCRIPT — they are read directly off disk into
+ * this process's memory and sent straight to the dashboard, the same
+ * privacy property `50arms_api`'s credential handling has for tokens. An
+ * S3 / server fault on the route surfaces as a 5xx, which the HTTP client
+ * throws.
+ */
+export async function attachFile(client, args, deps = {}) {
+    if (typeof args.path !== "string" || args.path.trim() === "") {
+        throw new Error("attach_file: path must be a non-empty string");
+    }
+    const { isAbsolute, basename, extname } = pathRulesFor(deps.platform);
+    if (!isAbsolute(args.path)) {
+        throw new Error(`attach_file: path must be an absolute path (got "${args.path}")`);
+    }
+    const read = deps.readFile ?? readFile;
+    if (args.target === "inline_image") {
+        return uploadInlineImage(client, args, read, deps.fileSize ?? (async (p) => (await stat(p)).size), { basename, extname });
+    }
+    // DX-4386: the replaced row keeps its stored name, so a filename override has nothing to apply to - refuse it loudly, before any read.
+    if (args.replaces !== undefined && args.filename !== undefined) {
+        throw new Error("attach_file: filename cannot be set with replaces (the replaced attachment keeps its name)");
+    }
+    if (typeof args.card_id !== "string" || args.card_id.trim() === "") {
+        throw new Error("attach_file: card_id is required unless target is inline_image");
+    }
+    // A missing / unreadable file rejects here — no HTTP call is made, so no
+    // S3 upload, no row insert, and no projection are ever triggered.
+    const bytes = await read(args.path);
+    const contentTypeOf = (name) => (args.content_type?.trim() ? args.content_type.trim() : inferAttachmentMime(name));
+    const issuePath = `/${encodeURIComponent(args.card_id)}/attachments`;
+    // DX-4386: `primary` is the dashboard's own atomic option (one live cover, set in the write's own transaction); an absent flag sends no key.
+    const primary = args.primary === undefined ? {} : { primary: args.primary };
+    if (args.replaces !== undefined) {
+        return client.request({
+            method: "PUT",
+            basePath: "/api/issues",
+            path: `${issuePath}/${args.replaces}`,
+            body: { contentType: contentTypeOf(basename(args.path)), base64: bytes.toString("base64"), ...primary },
+            board: args.board,
+        });
+    }
+    const filename = args.filename?.trim() ? args.filename.trim() : basename(args.path);
+    return client.request({
+        method: "POST",
+        basePath: "/api/issues",
+        path: issuePath,
+        body: { filename, contentType: contentTypeOf(filename), base64: bytes.toString("base64"), ...primary },
+        board: args.board,
+    });
+}
+/**
+ * DX-5241 / PLAN-47 CAV-1: upload a local image to `POST /api/uploads/images` and answer its permanent URL plus the markdown to embed it
+ * (feedback bodies, any markdown field). `50arms_api`'s `body_file` sends one raw file of at most 1 MB to a route that takes a file; this adds the upload routes, more image types and the 25 MB limit. The bytes are read here, never through the agent's context.
+ * Everything that makes no sense for an inline image (a card, a replace, a cover flag, a name or type override) is refused before any read.
+ */
+async function uploadInlineImage(client, args, read, fileSize, { basename, extname }) {
+    for (const key of ["card_id", "filename", "content_type", "replaces", "primary", "board"]) {
+        if (args[key] !== undefined)
+            throw new Error(`attach_file: ${key} cannot be set with target inline_image`);
+    }
+    const ext = extname(args.path).toLowerCase();
+    const contentType = INLINE_IMAGE_MIME_BY_EXT[ext];
+    if (!contentType) {
+        throw new Error(`attach_file: inline_image accepts only ${Object.keys(INLINE_IMAGE_MIME_BY_EXT).join(", ")} files (got "${ext || basename(args.path)}"); no SVG`);
+    }
+    // Stat first so an oversized file is refused without being read into memory.
+    const size = await fileSize(args.path);
+    if (size === 0)
+        throw new Error(`attach_file: "${args.path}" is empty`);
+    if (size > MAX_INLINE_IMAGE_BYTES) {
+        throw new Error(`attach_file: "${args.path}" is ${size} bytes; the limit is ${MAX_INLINE_IMAGE_BYTES} (25 MB)`);
+    }
+    const bytes = await read(args.path);
+    const result = await client.request({ method: "POST", basePath: "/api/uploads", path: "/images", rawBody: { bytes, contentType } });
+    if (!result.ok)
+        return result;
+    const url = result.body?.url;
+    if (typeof url !== "string" || url === "") {
+        throw new Error("attach_file: the image upload answered no url");
+    }
+    const alt = basename(args.path, extname(args.path)).replace(/[[\]]/g, "");
+    return { ...result, body: { url, markdown: `![${alt}](${url})` } };
+}

package/dist/heartbeat-reporter.js

@@ -0,0 +1,156 @@
+/**
+ * DX-3028 / DX-4233 - ONE heartbeat tick of a session's event stream, of the in-process relay behind
+ * `plan_events_wait`: what to send (connection state, session stats, the transcript's title), what
+ * to do with the answer, and the self-heal for a stream that reads as open while no heartbeat lands. WHEN a tick fires, and
+ * what an announced notice does, belongs to the owner.
+ *
+ * A tick never throws and never stops the stream: the stats and title are cosmetic and the heartbeat is liveness, so a
+ * failure of either costs that part (said once on stderr), never the beat.
+ */
+import { keyRevokedHalt } from "./key-revoked-halt.js";
+import { oneLine } from "./one-line.js";
+import { DIGEST_PREFIX } from "./digest-hold.js";
+import { HEARTBEAT_SILENT_FAILURE_THRESHOLD, HEARTBEAT_SUSTAINED_OUTAGE_MS, sendHeartbeat, } from "./session-stream.js";
+import { OperatorSessionStats } from "./session-stats.js";
+import { TranscriptTitleReader } from "./session-title.js";
+/** DX-5415: how long a stop waits for the final settle (drain + one stats flush) before giving up; shutdown must stay bounded. */
+export const FINAL_SETTLE_BOUND_MS = 10_000;
+function settleBound() {
+    return AbortSignal.timeout(FINAL_SETTLE_BOUND_MS);
+}
+export class HeartbeatReporter {
+    deps;
+    sessionStats;
+    titleReader;
+    transcriptPath;
+    // DX-4461 - the title the dashboard last answered with. Only the LATEST landed answer counts: one without a title (an older
+    // dashboard, including one rolled back to mid-session, or a refusal) stops the title until an answer carries one again,
+    // since an older dashboard refuses the `title` key and a refused heartbeat is a dead listener.
+    dashboardTitle;
+    lastTitleError = null;
+    // DX-3099 - consecutive heartbeats that failed to LAND on one open stream (DX-5088: per stream, reset whenever the state leaves `streaming`).
+    failureStreak = 0;
+    // DX-5088 - when the heartbeat first failed to land in the current outage (across every reconnect); null while the last one landed.
+    outageSince = null;
+    outageAnnounced = false;
+    // DX-4418 - the stop notice for a revoked key goes out once; every later beat is refused the same way.
+    revocationAnnounced = false;
+    constructor(deps, transcriptPath) {
+        this.deps = deps;
+        this.transcriptPath = transcriptPath;
+        this.sessionStats = new OperatorSessionStats(transcriptPath, deps.makeStatsWatcher);
+        this.titleReader = transcriptPath === null ? null : new TranscriptTitleReader(transcriptPath);
+    }
+    /**
+     * The relay learns the session's transcript from each `plan_events_wait` call, after the reporter exists: a different path
+     * (a resumed session) starts a fresh collector and title reader; the same one, or none, changes nothing.
+     */
+    useTranscript(path) {
+        if (path === undefined || path === this.transcriptPath)
+            return null;
+        const previous = this.sessionStats;
+        this.transcriptPath = path;
+        this.sessionStats = new OperatorSessionStats(path, this.deps.makeStatsWatcher);
+        this.titleReader = new TranscriptTitleReader(path);
+        this.dashboardTitle = undefined;
+        this.lastTitleError = null;
+        // DX-5415: the old transcript's held finals are stored before this returns; the swap above is synchronous so a second call sees the new path.
+        return previous.stop(this.send(undefined), settleBound());
+    }
+    /** A fresh connect cycle earns a clean slate for the silent-failure count. */
+    resetFailureStreak() {
+        this.failureStreak = 0;
+    }
+    /** DX-5415: settle the collector's held sub-agent finals (bounded), then stop tailing the transcript. Idempotent. */
+    async stop() {
+        await this.sessionStats.stop(this.send(undefined), settleBound());
+    }
+    /** One heartbeat as the reporter sends it: the carried answer's title and revocation are applied here. */
+    send(title) {
+        return async (stats, statsHeld) => {
+            const answer = await sendHeartbeat(this.deps.auth(), this.deps.http, this.deps.connection(), stats, title, statsHeld);
+            if (answer.landed)
+                this.dashboardTitle = answer.title ?? undefined;
+            // DX-4418 - a person revoked this session's key: tell the session to stop, at once and only once. Its next
+            // dashboard call says the same.
+            if (answer.revocation !== null && !this.revocationAnnounced) {
+                this.revocationAnnounced = true;
+                this.deps.announce(keyRevokedHalt(answer.revocation, false), "key_revoked");
+            }
+            return answer;
+        };
+    }
+    titleToReport() {
+        if (this.titleReader === null || this.dashboardTitle === undefined)
+            return undefined;
+        // The title is cosmetic and the heartbeat is liveness: a transcript the title cannot be read from costs the title (said
+        // once per distinct failure), never the beat.
+        try {
+            const title = this.titleReader.read();
+            this.lastTitleError = null;
+            return title !== null && title !== this.dashboardTitle ? title : undefined;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message !== this.lastTitleError)
+                process.stderr.write(`session title: ${message}\n`);
+            this.lastTitleError = message;
+            return undefined;
+        }
+    }
+    /** One heartbeat. Fired without being awaited: its own failures are reported here, never thrown. */
+    tick() {
+        const title = this.titleToReport();
+        void this.sessionStats
+            .tick(this.send(title))
+            .then((landed) => {
+            const now = this.deps.now();
+            if (landed) {
+                this.failureStreak = 0;
+                this.outageSince = null;
+                this.outageAnnounced = false;
+                return;
+            }
+            this.outageSince ??= now;
+            // DX-5088 - the model hears of an outage only once it is sustained, in any connection state (a dashboard that stays down keeps
+            // the stream reconnecting, and that is exactly the outage worth saying); a blip such as a ~35 s deploy restart is stderr only.
+            const downMs = now - this.outageSince;
+            if (downMs >= HEARTBEAT_SUSTAINED_OUTAGE_MS && !this.outageAnnounced) {
+                this.outageAnnounced = true;
+                const minutes = Math.round(downMs / 60_000);
+                const connection = this.deps.connection();
+                // DX-5088: the wording follows the state. A stopped relay (a terminal outcome) does not reconnect by itself, so "keeps reconnecting" would be false.
+                const wording = connection.state === "stopped"
+                    ? `this session's listener has stopped${connection.reason === undefined ? "" : ` (${connection.reason})`} and does not reconnect by itself, ` +
+                        `so the dashboard has heard nothing from it for ${minutes} minutes. The next plan_events_wait call says why it stopped and what to do; ` +
+                        `a person can also restart the session.`
+                    : `this session's listener has not reached the dashboard for ${minutes} minutes (its heartbeats keep failing). ` +
+                        `It keeps reconnecting on its own, and nothing is needed from you.`;
+                this.deps.announce(oneLine(`${DIGEST_PREFIX} ${wording}`), "relay_notice");
+            }
+            // DX-3099 - the self-heal counts only while a stream is open: that is the desync the card found (the client's stream reads
+            // open; the dashboard has nothing recent for it). DX-5088: while it is reconnecting the reconnect already owns recovery, and
+            // aborting it would restart the backoff, so a failure then neither counts nor forces anything.
+            if (!this.deps.streaming()) {
+                this.failureStreak = 0;
+                return;
+            }
+            this.failureStreak += 1;
+            if (this.failureStreak < HEARTBEAT_SILENT_FAILURE_THRESHOLD)
+                return;
+            this.failureStreak = 0;
+            process.stderr.write(`plan_events_wait: ${HEARTBEAT_SILENT_FAILURE_THRESHOLD} heartbeats in a row did not land on a stream that reads open; forcing a fresh connection\n`);
+            // End the CURRENT connection now, rather than wait on the stream reader's own read-idle timeout (which this exact
+            // failure mode can outlive indefinitely: the connection reads as established and keeps producing keep-alive bytes,
+            // only the outbound heartbeat silently never lands). The new attempt reconnects with the SAME ticket; the
+            // dashboard's one-open-stream-per-ticket rule then ends the old, superseded entry, releasing the exclusive claim
+            // as a side effect of THIS reconnect, never an external watchdog. The new stream's `streaming` sends a heartbeat at once.
+            this.deps.forceReconnect();
+        })
+            .catch((err) => {
+            // DX-3962: a stats failure must never take the stream down. `tick` is fired without being awaited, so a throw here
+            // would be an unhandled rejection that kills the process and with it the session's plan events.
+            process.stderr.write(`operator session stats: heartbeat tick failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+    }
+}