approval-md 0.0.1 → 0.2.0

package/dist/src/channels/telegram.js

@@ -0,0 +1,3190 @@
+/**
+ * The Telegram push channel (SPEC.md §10.3, APRV-26).
+ *
+ * A Telegram bot is the reference *push* channel: the runtime sends the pending
+ * request into a chat the approver already reads, and the approver answers with
+ * one tap. Everything the contract says about a channel still holds here and is
+ * worth restating, because a network channel is where the temptations live:
+ *
+ * - **It decides nothing.** A `callback_query` becomes a {@link ChannelDecision}
+ *   and is handed to the handler the runtime registered. That handler calls
+ *   `recordChannelDecision`, which calls the human-only `decide()`. There is no
+ *   second path, so TTL lapse, budget re-check, attestation, idempotency and
+ *   compare-and-append all still apply to a button press.
+ * - **It never sees a token.** A grant mints a single-use execution token, and
+ *   `recordChannelDecision` hands it to *its* caller, not to the channel. See
+ *   "The token never goes back into the chat" below.
+ * - **It holds no decision state.** The only thing kept in memory is the map
+ *   from a callback nonce to the action key it was issued for, which is
+ *   delivery bookkeeping, not authorization. It is lost on restart, and a
+ *   restarted listener re-notifies the pending queue. Since APRV-196 a button
+ *   also carries a digest of its action key, so a tap on a pre-restart copy
+ *   resolves to the request the new process is holding open and decides it;
+ *   what a lost map costs is a duplicate message, not a dead button. The trade
+ *   is unchanged and is the reason that works at all: an approval that survives
+ *   a restart lives in the log, never in a channel's memory, so the thing a
+ *   stale button resolves against is a request the LOG still calls pending.
+ *
+ * ## Zero dependencies
+ *
+ * The Bot API is plain HTTPS with JSON bodies, so this module uses `fetch`
+ * (global since Node 18) and nothing else. No SDK, no polling library, no
+ * webhook framework. `fetch` is injectable ({@link TelegramConfig.fetch}) and
+ * `apiBase` is injectable, which is how the test suite runs the whole channel —
+ * notify, long-poll, callbacks, failure modes — against a local mock Bot API
+ * server and never touches the real network.
+ *
+ * ## Config-declared identity — SPEC.md §11
+ *
+ * > Human identity in v0.1 is config-declared (an environment variable or
+ * > flag); the trust boundary is the local machine, and anyone who can set that
+ * > configuration and write to the log is inside it.
+ *
+ * This channel does **not** authenticate the person who tapped the button. It
+ * checks that the callback arrived from the configured chat id, and the
+ * decision is then recorded against the human actor the *runtime* was
+ * configured with (`APPROVAL_HUMAN` / `--as`), not against anything the
+ * callback carried. So the guarantee is "someone with access to the configured
+ * chat, on a runtime configured by someone with local control, tapped Approve"
+ * — not "alice tapped Approve". Anyone in that chat can approve as the
+ * configured actor. Use a private chat with the bot, and treat the chat's
+ * membership as part of the trust boundary. Cryptographic identity is future
+ * work and is not a v0.1 claim.
+ *
+ * ## Formatting: HTML, not MarkdownV2 — a deliberate choice
+ *
+ * Messages use `parse_mode: "HTML"`. MarkdownV2 requires escaping eighteen
+ * characters (`_*[]()~\`>#+-=|{}.!`) in every text position, with different
+ * rules inside code spans, and a single missed one is not a cosmetic bug: it is
+ * agent-authored text (a summary, a payload body) changing the *structure* of
+ * the message a human is about to approve. HTML mode needs exactly three
+ * escapes — `&`, `<`, `>` — applied uniformly to every interpolated value by
+ * {@link escapeHtml}, and `<pre>` carries the payload bytes without any
+ * character being special inside it beyond those three. A narrower escape rule
+ * is a narrower injection surface, and the untrusted input here is precisely
+ * the claimed fields and the payload.
+ *
+ * ## The token never goes back into the chat — flagged for human review
+ *
+ * `recordChannelDecision` returns the raw execution token to the runtime on a
+ * grant. The runtime (`cli/channel.ts`) prints it on the **listener's stdout**
+ * and nowhere else. It is never sent as a Telegram message, never put in an
+ * `answerCallbackQuery` text, and never logged by this module. A chat
+ * transcript is stored on someone else's servers, is backed up to phones, and
+ * is readable by anyone who is later added to the chat; a single-use execution
+ * token in it would be a credential in a place with none of the properties a
+ * credential store has. The consequence is real and is the reason this is
+ * flagged: the human who approves on their phone does not get the token on
+ * their phone — the agent or operator at the terminal running `approval channel
+ * telegram listen` does. For v0.1's local-first, single-operator model that is
+ * the right side of the trade; a deployment where the approver and the runtime
+ * are different people needs a token-delivery design, not a chat message.
+ *
+ * ## Reject collects no free-text reason — flagged for human review
+ *
+ * Telegram inline keyboards have no text input: a button press returns only its
+ * `callback_data`. Collecting the approver's reason would require a
+ * `ForceReply` round trip (send a prompt, wait for the *next* message in the
+ * chat, correlate it), which means holding a second piece of per-request state
+ * and deciding what to do when the reply never comes. This task records the
+ * rejection immediately with the note `rejected via telegram (callback <id>)`,
+ * so the audit trail says how the refusal was collected and which callback it
+ * came from, and says nothing about why. A follow-up may add the ForceReply
+ * flow; until then, a reason belongs in `approval reject --note`.
+ *
+ * ## Batching (B7): the digest (APRV-115)
+ *
+ * SPEC.md §10.3 lets a channel collect one gesture over a set, and until
+ * APRV-115 this channel took that option **degenerately**: one message per
+ * member, each with its own keyboard, all sharing one batch delivery id. The
+ * semantics were right and the ergonomics were the incident. A research session
+ * once produced forty near-identical `network.call` prompts in twenty minutes,
+ * one message each, and a channel that behaves like a notification hose is a
+ * channel a human learns to swipe away.
+ *
+ * A group of similar pending requests (the grouping key is
+ * {@link digestKeyOf}, applied by the listener) is now delivered as a
+ * **digest**: every member's full prompt and full payload first, in its own
+ * messages and with no buttons, then ONE trailing message carrying the
+ * headline, one summary line per member, and the keyboard — a per-member
+ * Approve/Reject row for each, plus an "all" row.
+ *
+ * Four properties hold it together:
+ *
+ * - **The payloads come first.** The buttons are on the LAST message, and
+ *   every member's `<pre>` payload region has already been sent above it. An
+ *   approver cannot reach an "Approve all" without the bytes it covers having
+ *   been put in front of them (SPEC.md §10.4).
+ * - **It fails toward more messages.** A group whose digest text would not fit
+ *   inside {@link TELEGRAM_MAX_MESSAGE_CHARS}, or that has fewer than two
+ *   members, falls back to the old one-message-per-member delivery, and so
+ *   does a group `assembleBatch` refuses. The listener caps a digest at
+ *   {@link TELEGRAM_DIGEST_MAX_MEMBERS} and splits a larger burst into
+ *   several. Never a grant covering an unseen payload.
+ * - **"All" is N decisions, not one.** An all-button hands the runtime's
+ *   handler one {@link ChannelDecision} per still-armed member, in order, and
+ *   the handler records each through the gate's compare-and-append on its own.
+ *   The log never learns the word "batch": it gets N `approval.granted` or
+ *   `approval.rejected` events, each bound to its own action and payload hash,
+ *   each carrying the shared batch delivery id (SPEC.md §10.3).
+ * - **Annotation is per member.** A decided, expired or withdrawn member marks
+ *   its own line on the digest and loses its own buttons; the others stay
+ *   armed. A partially decided digest therefore shows mixed state, which is
+ *   what {@link TelegramChannel.annotate} redraws it to.
+ *
+ * The digest bookkeeping is delivery state of exactly the kind the nonce map
+ * already was: what was sent where, never what was decided. Every outcome word
+ * on it comes from the verified log or from the record the gate appended, and
+ * losing the map to a restart degrades to a stale message whose buttons the
+ * gate refuses, never to a wrong one.
+ *
+ * ## Every terminal state edits its message (APRV-113)
+ *
+ * A decided prompt used to look exactly like a pending one: the tap toasted,
+ * and the message kept its text and its live buttons. So did a request answered
+ * at the CLI or the web queue while the chat prompt was up, and so did one the
+ * daemon expired. The chat transcript — the thing the approver actually scrolls
+ * — said "APPROVAL REQUIRED" about a question that had been settled hours ago.
+ *
+ * Every terminal state this process observes for a message it delivered now
+ * edits that message: {@link TelegramChannel.annotate} replaces the text with
+ * the outcome and clears the keyboard in ONE `editMessageText`, and forgets the
+ * delivery so a tap on a button the edit did not remove refuses rather than
+ * decides. {@link TelegramChannel.retract} is the withdrawal case of it.
+ *
+ * Two properties this keeps, deliberately:
+ *
+ * - **It is not state.** The map this consults is delivery bookkeeping, and
+ *   annotating removes from it rather than adding. Losing it (a restart)
+ *   degrades to a message that is never annotated — stale text in front of a
+ *   human whose gate still refuses every tap on it — and never to a message
+ *   annotated with the wrong outcome, because every outcome word comes from the
+ *   verified log at the moment it is written.
+ * - **The token is never in an edit.** An annotation carries the outcome word,
+ *   the action key, who decided, when, and the record's seq. It never carries
+ *   the execution token, for the reason spelled out above.
+ *
+ * ## The bookkeeping is swept (APRV-135)
+ *
+ * Both maps used to be released only by process exit. Annotating a delivery
+ * removes its nonces, but nothing removes a delivery that is never annotated
+ * (a request that simply lapsed) or a digest whose members were each settled
+ * individually, so a listener left running for weeks held memory proportional
+ * to every prompt it had ever sent — and APRV-110's ambient runtime makes
+ * week-long listeners the normal case rather than the exception.
+ *
+ * {@link TelegramChannel.sweep} drops an entry when every member of it is
+ * terminal AND the entry is older than the policy's approval TTL. Both halves
+ * matter and the pair is what makes the drop safe: past the TTL the gate
+ * refuses every decision on the request, so a button referencing a dropped
+ * entry could not have been honoured anyway, and it is answered by the
+ * stale-callback path that a restarted listener's buttons already take. It is
+ * process memory and nothing else: no event is appended, no message is edited,
+ * and the log is not opened.
+ */
+import { createHash } from "node:crypto";
+import { GLOSS_UNVERIFIED_SUFFIX, refusedDecisionLine } from "./contract.js";
+// APRV-299. The reaction vocabulary and the verdict type, imported for the
+// reason `core/audit.ts` states where it exports them: they are shown here and
+// decided nowhere. Nothing in this file branches on a reaction, and SPEC.md
+// §11.1 invariant 10's guard scans the modules that decide, which this is not.
+import { REACTIONS } from "../core/audit.js";
+import { TELEGRAM_PROMPT_LAYOUT, } from "../core/prompt-layout.js";
+import { commandPayloadView, payloadRegionText } from "./payload-view.js";
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+// The variable NAMES and their resolvers live in `core/telegram-config.ts`
+// (APRV-72, moved in APRV-73 so `approval env` can read them without a
+// core -> channels import). Re-exported here so channel callers keep one
+// import path. Still true: nothing under `src/channels/` reads `process.env`.
+import { TELEGRAM_CHAT_ENV, TELEGRAM_TOKEN_ENV } from "../core/telegram-config.js";
+export { TELEGRAM_CHAT_ENV, TELEGRAM_TOKEN_ENV, telegramChatEnvFor, telegramTokenEnvFor, } from "../core/telegram-config.js";
+/** The real Bot API. Overridden only by tests, against a local mock. */
+export const TELEGRAM_DEFAULT_API_BASE = "https://api.telegram.org";
+/** Telegram's hard limit on a message's text. */
+export const TELEGRAM_MAX_MESSAGE_CHARS = 4096;
+/** Telegram's hard limit on `callback_data`, in bytes. */
+export const TELEGRAM_MAX_CALLBACK_BYTES = 64;
+/** The note recorded on a rejection collected from a button. */
+export const TELEGRAM_REJECT_NOTE = "rejected via telegram";
+/**
+ * The toast a tap gets when no branch produced one of its own (APRV-196).
+ *
+ * It is deliberately about the tap and not about the request: this text is only
+ * ever reached when the handler threw or forgot, which are exactly the states
+ * in which this process does not know what became of the request. Saying so is
+ * the honest answer, and it is still infinitely better than a button that spins.
+ */
+export const TELEGRAM_ACK_FALLBACK = "Received — this listener could not finish reading your tap. Nothing was recorded by it; check the message above for the outcome.";
+/**
+ * The toast a tap gets the instant it is recognized, BEFORE the gate runs
+ * (APRV-206).
+ *
+ * Telegram gives a callback query exactly one answer, and until it arrives the
+ * button spins on the approver's phone. Sending it after the decision made the
+ * spinner as long as the decision — which grew with the log — and the human,
+ * with no way to tell a slow tap from a swallowed one, tapped again.
+ *
+ * So this is what the single answer says, and its wording is load-bearing: it
+ * claims only that the tap ARRIVED. It must never say granted, rejected,
+ * approved, recorded, or anything else a reader could take as "the log now says
+ * so", because at the moment it is sent nothing has been appended and the gate
+ * may still refuse. What became of the request is said by the message edit that
+ * follows, which is written from the record the gate actually appended (or from
+ * its refusal). The toast vanishes; the message stays.
+ */
+export const TELEGRAM_ACK_HEARD = "Heard — deciding. The message will say what the log recorded.";
+/**
+ * The headline on a message whose tap the gate refused (APRV-206).
+ *
+ * Before the early ack, a refusal was a toast and the message was left alone.
+ * Now that the single answer is spent on "heard", the refusal has to reach the
+ * approver here or nowhere. The buttons go with it ({@link annotate} disarms),
+ * which is the right outcome in both directions: a request the gate calls
+ * terminal has no live decision left to collect, and a request that is still
+ * pending is re-delivered by the next dispatch cycle as a fresh prompt.
+ */
+export const TELEGRAM_NOT_RECORDED = "✗ NOT RECORDED";
+/**
+ * The detail line under {@link TELEGRAM_NOT_RECORDED} when the runtime's
+ * decision handler threw (APRV-206).
+ *
+ * The wording is careful about what it does not know: a handler that threw may
+ * have thrown before or after its append, so this says where to look rather
+ * than what happened. The log is the thing that knows.
+ */
+export const TELEGRAM_HANDLER_FAILED = "This listener failed while recording your tap. Check `approval queue` — the log is what says whether anything was recorded.";
+/** Prefixed to the toast when the tap arrived on a pre-restart copy (APRV-196). */
+export const TELEGRAM_STALE_COPY_PREFIX = "Earlier copy of this request — ";
+/**
+ * The toast for a tap on a copy of an action this process is not holding open,
+ * when no verified-log probe is configured to say more (APRV-196).
+ */
+export const TELEGRAM_STALE_UNKNOWN = "This request is not open here — it was already decided, it lapsed, or another listener holds it. Nothing was recorded.";
+/**
+ * The headline of an ordinary single-request prompt.
+ *
+ * Exported because the mock Bot API and several tests key on it, and because a
+ * digest member's header deliberately does NOT use it: a member prompt carries
+ * no buttons, so calling it "APPROVAL REQUIRED" would point a reader at a
+ * message that cannot take their answer.
+ */
+export const TELEGRAM_PROMPT_HEADING = "APPROVAL REQUIRED";
+/**
+ * What the label over the payload chunks names (APRV-162).
+ *
+ * The chunks carry the canonical rendering, which is a deterministic function
+ * of the bytes and not the bytes themselves; calling it "the exact bytes" told
+ * the reader that a diff view and a JSON file were the same object. The
+ * rendering names its own `display_hash`, and the store path inside it is the
+ * route back to the bytes.
+ */
+export const PAYLOAD_CHUNK_LABEL_TAIL = "the canonical rendering this approval's display_hash names; raw bytes at the store path inside";
+export const PAYLOAD_CHUNK_LABEL = `PAYLOAD — ${PAYLOAD_CHUNK_LABEL_TAIL}`;
+/**
+ * What the claimed block is headed, and what a second claimed message is headed
+ * when a rationale overflows one (APRV-165).
+ *
+ * Both say CLAIMED and both say NOT verified, because a continuation is a
+ * message a reader may see first, and a claimed line that arrives under no
+ * heading at all reads as the runtime's own.
+ */
+export const TELEGRAM_CLAIMED_HEADING_PREFIX = "WHAT THIS DOES — CLAIMED by";
+export const TELEGRAM_CLAIMED_HEADING_SUFFIX = "NOT verified by the runtime";
+export const TELEGRAM_CLAIMED_CONTINUED_HEADING = `WHAT THIS DOES (continued) — CLAIMED, ${TELEGRAM_CLAIMED_HEADING_SUFFIX}`;
+/**
+ * The most members one digest may carry (APRV-115).
+ *
+ * Not a rendering limit — {@link renderDigest} checks the real one against
+ * {@link TELEGRAM_MAX_MESSAGE_CHARS} — but a *reading* one: a keyboard of
+ * twenty rows is a wall, and the failure this feature exists to fix is a human
+ * who stops reading. A burst larger than this becomes several digests, which is
+ * the direction this whole design fails in.
+ */
+export const TELEGRAM_DIGEST_MAX_MEMBERS = 8;
+/**
+ * The headline each terminal state puts on the message it settles (APRV-113).
+ *
+ * Keyed by `core/state.ts`'s `RequestState` names for the terminal states, so
+ * the caller that derived the state from the verified log picks a word by
+ * indexing rather than by re-deciding what happened.
+ *
+ * Glyphs, not emoji: `✓`/`✗` are the vocabulary `cli/style.ts` uses for the
+ * same ok/fail distinction, and every line of *message text* this channel
+ * writes ("APPROVAL REQUIRED", "PAYLOAD", "WITHDRAWN") is emoji-free. The
+ * emoji live on the button labels, which are a different surface and stay as
+ * they are. `withdrawn` keeps the exact wording APRV-106 shipped.
+ */
+export const TELEGRAM_TERMINAL_HEADLINES = {
+    granted: "✓ APPROVED",
+    rejected: "✗ REJECTED",
+    revoked: "✗ REVOKED — the grant was taken back",
+    expired: "✗ EXPIRED — the approval window closed",
+    withdrawn: "WITHDRAWN — no decision is needed",
+};
+/** Whether a derived request state is one an annotation can settle a message on. */
+export function isTelegramTerminalState(state) {
+    return Object.prototype.hasOwnProperty.call(TELEGRAM_TERMINAL_HEADLINES, state);
+}
+/**
+ * `HH:MM UTC`, or the raw instant when it does not parse.
+ *
+ * UTC and not a local zone: the listener, the approver's phone and the log can
+ * all be in different places, and the log's own timestamps are UTC. A clock a
+ * reader can line up against `approval log` beats one that matches their wrist.
+ */
+export function utcClock(ts) {
+    const ms = Date.parse(ts);
+    if (Number.isNaN(ms))
+        return ts;
+    const at = new Date(ms);
+    return `${String(at.getUTCHours()).padStart(2, "0")}:${String(at.getUTCMinutes()).padStart(2, "0")} UTC`;
+}
+/** The "who decided, when, and which record says so" line of an annotation. */
+export function decidedLine(actor, ts, seq) {
+    return `by ${actor} at ${utcClock(ts)} (seq ${seq})`;
+}
+/** Room left under {@link TELEGRAM_MAX_MESSAGE_CHARS} for our own markup. */
+const SEGMENT_BUDGET = 3600;
+/** The `getUpdates` long-poll timeout, in seconds, when none is configured. */
+const DEFAULT_POLL_TIMEOUT_SECONDS = 25;
+/** First backoff step after a failed poll. Doubles, capped. */
+const DEFAULT_BACKOFF_MS = 1_000;
+const DEFAULT_MAX_BACKOFF_MS = 30_000;
+/**
+ * How long a settled delivery is remembered when the policy declares no
+ * `defaults.approval_ttl` (APRV-135).
+ *
+ * A policy with no TTL bounds nothing, so "past the approval TTL" can never
+ * become true and a sweep keyed on it alone would never fire — which is the
+ * unbounded map this task exists to remove. The retention floor takes over
+ * there, and it applies only to entries whose every member this process has
+ * seen settled: with no TTL an undecided request stays answerable forever, and
+ * forgetting its button would take a live decision away from an approver.
+ *
+ * A day, because the point of remembering a settled delivery at all is that an
+ * approver may still tap a button on a message already scrolled past, and the
+ * answer they should get is the stale-callback reply either way.
+ */
+export const TELEGRAM_DEFAULT_RETENTION_MS = 24 * 60 * 60 * 1000;
+/** Least time between two sweeps. A sweep is O(map); once a minute is plenty. */
+export const TELEGRAM_SWEEP_INTERVAL_MS = 60_000;
+// ---------------------------------------------------------------------------
+// Anomalies
+// ---------------------------------------------------------------------------
+/**
+ * Why a callback was ignored.
+ *
+ * Every one of these is counted and complained about on stderr, and **none of
+ * them reaches the decision path or the log**. An ignored callback is not an
+ * event: writing "someone we do not answer to pressed a button" into an
+ * append-only approval log would let any stranger who guessed the bot's handle
+ * grow the record a human is asked to trust.
+ */
+export const TELEGRAM_ANOMALY_KINDS = [
+    /** The callback came from a chat that is not the configured one. */
+    "foreign-chat",
+    /** `callback_data` did not parse as one of ours. */
+    "malformed-callback",
+    /** A well-formed nonce this listener never issued (or issued before a restart). */
+    "unknown-callback",
+    /** The action key carried in `callback_data` disagrees with the issued nonce. */
+    "key-mismatch",
+    /**
+     * A tap on a copy of a request this process is no longer holding open
+     * (APRV-196): the nonce is not one of ours, and the action it names is not
+     * pending here either — it was decided, it lapsed, or another process owns
+     * it. Distinct from `unknown-callback` because the operator's question is
+     * different: nothing is wrong with the button, the question behind it is
+     * over. Always answered with a toast that names the state.
+     */
+    "stale-copy",
+    /**
+     * A message in the approver chat that began with `/` and named no command
+     * this channel answers (APRV-216). Counted rather than replied to: the chat
+     * belongs to a human, other bots and other slash commands live in it, and a
+     * channel that answered every unrecognised one would be noise in the one
+     * place an approver's attention is supposed to be scarce.
+     */
+    "unknown-command",
+];
+export const TELEGRAM_COMMANDS = ["queue", "skip", "next"];
+/**
+ * The command a message's text names, or `null` (APRV-216).
+ *
+ * Pure, and exported so the listener's tests can exercise the grammar without
+ * a transport. Telegram delivers a command in a group chat as `/skip@thebot`,
+ * so the `@suffix` is stripped; the bot's own username is not checked, because
+ * this channel only ever reads ONE chat and a message in it that says `/skip`
+ * to some other bot is a message the approver still meant as a skip more often
+ * than not. Anything after the command word is ignored: none of these three
+ * takes an argument, and silently discarding one is better than refusing a
+ * command a human typed with a stray word on the end.
+ */
+export function parseBotCommand(text) {
+    if (typeof text !== "string")
+        return null;
+    const first = text.trim().split(/\s+/u)[0];
+    if (first === undefined || !first.startsWith("/"))
+        return null;
+    const word = first.slice(1).split("@")[0]?.toLowerCase();
+    return TELEGRAM_COMMANDS.find((command) => command === word) ?? null;
+}
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+/** The three characters Telegram's HTML mode treats as markup. */
+export function escapeHtml(text) {
+    return text.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** A field's `source` / `author` label, for the "(log)" / "(agent:x)" suffix. */
+function originOf(field) {
+    return field.kind === "computed" ? field.source : field.author;
+}
+/**
+ * The suffix the model-authored line carries, on the line itself (APRV-144).
+ *
+ * One constant, shared with the terminal channel since APRV-197: this name is
+ * kept because the tests and the help text pin it, and it now resolves to
+ * {@link GLOSS_UNVERIFIED_SUFFIX} so the two surfaces cannot drift apart.
+ */
+export const TELEGRAM_GLOSS_SUFFIX = GLOSS_UNVERIFIED_SUFFIX;
+/**
+ * The prefix a health row carries when it is the reason to look (APRV-163).
+ *
+ * Only the abnormal state of `autonomy`, `budgets` and the attestation renders
+ * at all, so the mark is never routine: a row bearing it is a row the reader
+ * has not seen on the last twenty prompts.
+ */
+export const TELEGRAM_ANOMALY_MARK = "⚠ ";
+function line(field, tagged, label, text) {
+    return { field, kind: tagged.kind, label, text, origin: originOf(tagged) };
+}
+function budgetSummary(request) {
+    const verdicts = request.budgets.value;
+    if (verdicts.length === 0)
+        return "no limits apply";
+    return verdicts
+        .map((verdict) => {
+        const state = verdict.pass ? "ok" : "EXCEEDED";
+        return `${state} ${verdict.scope}.${verdict.limit} (${verdict.window}) consumed ${verdict.consumed} + this ${verdict.requested}, ${verdict.remaining} left`;
+    })
+        .join("; ");
+}
+/**
+ * The attestation line.
+ *
+ * Anything but `attested` is shouted, because an unattested or drifted policy
+ * means the rule that produced `autonomy: manual` above is not the rule a human
+ * signed off on — which is exactly the thing an approver must not have to infer.
+ */
+function attestationSummary(request) {
+    const status = request.attestation.value;
+    switch (status.status) {
+        case "attested":
+            return `attested (seq ${status.seq})`;
+        case "not-attested":
+            return "NOT ATTESTED — no human has signed off on this policy file";
+        case "hash-mismatch":
+            return `HASH MISMATCH — the policy file changed since attestation seq ${status.seq}`;
+        default:
+            return `UNREADABLE — ${status.message}`;
+    }
+}
+function formatTelegramTtl(ms) {
+    if (ms === null)
+        return "no expiry declared";
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0)
+        return `${String(hours)}h ${String(minutes % 60)}m left`;
+    if (minutes > 0)
+        return `${String(minutes)}m ${String(seconds % 60)}s left`;
+    return `${String(seconds)}s left`;
+}
+/** The rows a review card renders, in the order it renders them (APRV-299). */
+export const REVIEW_CARD_ROWS = [
+    "class",
+    "command_breakdown",
+    "task",
+    "summary",
+    "gloss",
+];
+/**
+ * The five rows a prompt and a review card render identically (APRV-299).
+ *
+ * Extracted from {@link telegramRow} rather than copied, so that a card and a
+ * prompt cannot come to describe the same class, the same command or the same
+ * claimed summary in two different ways. The gloss keeps every property
+ * APRV-144 gave it here too: it renders under the CLAIMED heading because its
+ * field says `claimed`, it carries {@link TELEGRAM_GLOSS_SUFFIX} on the line
+ * itself, and nothing branches on what it says.
+ */
+function reviewRow(fields, row) {
+    const normal = (line_) => ({ line: line_, abnormal: false });
+    switch (row) {
+        case "task":
+            return normal(line("task", fields.task, "task", fields.task.value ?? "(none)"));
+        case "class":
+            return normal(line("class", fields.class, "class", fields.class.value));
+        case "command_breakdown":
+            return fields.command_breakdown === undefined
+                ? null
+                : normal(line("command_breakdown", fields.command_breakdown, "commands", fields.command_breakdown.value));
+        case "gloss":
+            return fields.gloss === undefined
+                ? null
+                : normal(line("gloss", fields.gloss, "gloss", `${fields.gloss.value} ${TELEGRAM_GLOSS_SUFFIX}`));
+        case "summary":
+            return normal(line("summary", fields.summary, "summary", fields.summary.value ?? "(none given)"));
+        default:
+            return null;
+    }
+}
+/**
+ * One row's line, or `null` when this request does not carry it and when the
+ * channel renders it structurally rather than as a bullet.
+ *
+ * Every row in {@link PROMPT_ROWS} has a case, including the eight APRV-143 and
+ * APRV-163 dropped from the default layout. Those fields never left the
+ * `ChannelRequest` — the tasks slimmed the phone rendering and nothing else —
+ * so an operator turning one back on with `always` is asking for a line this
+ * channel can already build, not for a new fact about the log.
+ *
+ * The five rows a review card shares live in {@link reviewRow} since APRV-299
+ * and are delegated to here.
+ */
+function telegramRow(request, row) {
+    const normal = (line_) => ({ line: line_, abnormal: false });
+    switch (row) {
+        // Structural, not a bullet: the action key is the message's second line, in
+        // its own `<code>` span. It is a required row, so no policy can hide it,
+        // and it is not a bullet, so forcing it on adds nothing.
+        case "action_key":
+            return null;
+        case "task":
+        case "class":
+        case "command_breakdown":
+        case "gloss":
+        case "summary":
+            return reviewRow(request, row);
+        case "protected_path":
+            return request.protected_path === undefined
+                ? null
+                : normal(line("protected_path", request.protected_path, "protected path", request.protected_path.value));
+        case "policy_diff":
+            return request.policy_diff === undefined
+                ? null
+                : normal(line("policy_diff", request.policy_diff, "policy diff", request.policy_diff.value));
+        case "policy_load":
+            return request.policy_load === undefined
+                ? null
+                : normal(line("policy_load", request.policy_load, "policy loads", request.policy_load.value));
+        case "autonomy":
+            return {
+                line: line("autonomy", request.autonomy, "autonomy", request.autonomy.value),
+                abnormal: request.autonomy.value !== "manual",
+            };
+        case "budgets":
+            return {
+                line: line("budgets", request.budgets, "budgets", budgetSummary(request)),
+                abnormal: !request.budgets.value.every((verdict) => verdict.pass),
+            };
+        case "attestation":
+            return {
+                line: line("attestation", request.attestation, "policy", attestationSummary(request)),
+                abnormal: request.attestation.value.status !== "attested",
+            };
+        case "provenance":
+            return normal(line("provenance", request.provenance, "resolved by", request.provenance.value));
+        case "state":
+            return normal(line("state", request.state, "state", request.state.value));
+        case "requested_ts":
+            return normal(line("requested_ts", request.requested_ts, "requested", request.requested_ts.value));
+        case "waiting":
+            return normal(line("waiting", request.waiting, "waiting", request.waiting.value));
+        case "ttl_remaining_ms":
+            return normal(line("ttl_remaining_ms", request.ttl_remaining_ms, "ttl", formatTelegramTtl(request.ttl_remaining_ms.value)));
+        case "payload_hash":
+            return normal(line("payload_hash", request.payload_hash, "payload sha256", request.payload_hash.value));
+        case "chain": {
+            const chain = request.chain.value;
+            return normal(line("chain", request.chain, "chain", `seq ${String(chain.seq)} hash ${chain.hash} (log head seq ${String(chain.head_seq)})`));
+        }
+        case "token_delivery":
+            return request.token_delivery === undefined
+                ? null
+                : normal(line("token_delivery", request.token_delivery, "token delivery", request.token_delivery.value));
+        case "est_cost_usd":
+            return normal(line("est_cost_usd", request.est_cost_usd, "est. cost", `$${request.est_cost_usd.value.toFixed(2)}`));
+        // APRV-144's `gloss` and the `summary` row are two of the five {@link
+        // reviewRow} answers above. Under the CLAIMED heading, because a model's
+        // sentence is not something the runtime derived, and labelled on the line
+        // as well: the `(author)` parenthetical every claimed line already carries
+        // is small, uniform and easy to stop seeing, and the gloss is the one line
+        // in the message that NO party — not the runtime, not even the requesting
+        // agent — stands behind. Nothing here or anywhere else branches on what it
+        // says, and a layout cannot move it out from under that heading: the region
+        // a line lands in comes from the field's `kind`, applied after the ordering.
+        case "rationale":
+            return request.rationale === undefined
+                ? null
+                : normal(line("rationale", request.rationale, "rationale", request.rationale.value));
+        case "confidence":
+            return request.confidence === undefined
+                ? null
+                : normal(line("confidence", request.confidence, "confidence", `${String(request.confidence.value)} (never a gate)`));
+        default:
+            return null;
+    }
+}
+/**
+ * Build the two regions and the line list. Pure: no I/O, no clock.
+ *
+ * `heading` is the message's first line. It is a parameter for exactly one
+ * reason (APRV-115): a digest member's prompt carries no buttons, and telling
+ * a reader "APPROVAL REQUIRED" above a message they cannot answer on is the
+ * kind of small lie that costs a channel its legibility. Everything below the
+ * first line is identical either way, computed/claimed split included.
+ *
+ * `layout` is the policy's answer to which rows this channel shows (APRV-218).
+ * It defaults to {@link TELEGRAM_PROMPT_LAYOUT}, which is the slimmed prompt
+ * APRV-143 and APRV-163 left behind, so a policy that declares no
+ * `channels.telegram.prompt` renders byte for byte what it rendered before the
+ * key existed. Rendering stays a pure function of (request, layout): the layout
+ * chooses among facts the request already carries and teaches this channel
+ * nothing about the log.
+ *
+ * The computed/claimed split survives ANY ordering, and that is a property
+ * rather than a convention. `layout.order` decides the sequence rows are
+ * considered in; the partition below is by `Line.kind`, which comes from the
+ * `TaggedField` the row was built from. A `rows` list that puts `summary`
+ * first therefore puts it first among the CLAIMED lines, and never above the
+ * computed heading.
+ */
+export function renderTelegram(request, heading = TELEGRAM_PROMPT_HEADING, layout = TELEGRAM_PROMPT_LAYOUT) {
+    const payload = request.fullPayload.value;
+    const computedLines = [];
+    const claimedLines = [];
+    for (const row of layout.order) {
+        const visibility = layout.visibility[row];
+        if (visibility === "off")
+            continue;
+        const candidate = telegramRow(request, row);
+        if (candidate === null)
+            continue;
+        if (visibility === "abnormal" && !candidate.abnormal)
+            continue;
+        const entry = candidate.abnormal
+            ? { ...candidate.line, label: `${TELEGRAM_ANOMALY_MARK}${candidate.line.label}` }
+            : candidate.line;
+        if (entry.kind === "computed")
+            computedLines.push(entry);
+        else
+            claimedLines.push(entry);
+    }
+    const author = request.summary.kind === "claimed" ? request.summary.author : "the requesting party";
+    const render = (entry) => `• <b>${escapeHtml(entry.label)}:</b> ${escapeHtml(entry.text)} <i>(${escapeHtml(entry.origin)})</i>`;
+    const header = [
+        `<b>${escapeHtml(heading)}</b>`,
+        `<code>${escapeHtml(request.action_key.value)}</code>`,
+        "",
+        "<b>COMPUTED — derived by the runtime from the log, the policy and the payload bytes</b>",
+        ...computedLines.map(render),
+    ].join("\n");
+    const claimedText = [
+        `<b>${TELEGRAM_CLAIMED_HEADING_PREFIX} ${escapeHtml(author)}, ${TELEGRAM_CLAIMED_HEADING_SUFFIX}</b>`,
+        ...claimedLines.map(render),
+    ].join("\n");
+    return {
+        // Computed first, then claimed, whatever order the messages go out in:
+        // `lines` is the conformance suite's view of what was rendered, and the
+        // two-kind split it checks is a property of the fields, not of the layout.
+        lines: [...computedLines, ...claimedLines],
+        header,
+        claimedText,
+        // A whole payload needs no prefix: the canonical block states its own
+        // renderer, class, kind and `payload sha256` in its first lines, and a
+        // second sha256 above it is one more line between the reader and the
+        // action. A TRUNCATED rendering has no canonical block to say any of that,
+        // so it gets a prefix worded as what it is: a refusal. Neither is reachable
+        // from a layout: the block is not a row (APRV-218).
+        payloadText: payload === null
+            ? null
+            : `${payload.truncated ? `--- payload TRUNCATED at render (sha256 ${payload.hash}) — no canonical rendering exists; do not grant on this ---\n` : ""}${payloadRegionText(payload, request.class.value)}`,
+    };
+}
+/**
+ * Split `text` so every chunk survives HTML escaping inside the message limit.
+ *
+ * Splitting is by *escaped* length, because `&` becomes five characters and a
+ * payload full of them would otherwise produce a message Telegram rejects. The
+ * payload is never truncated to fit: the bytes a human is asked to approve are
+ * the bytes the token will execute, so an oversized payload becomes several
+ * messages, never a shortened one.
+ */
+export function chunkForTelegram(text, budget = SEGMENT_BUDGET) {
+    const chunks = [];
+    let current = "";
+    let cost = 0;
+    for (const character of text) {
+        const size = escapeHtml(character).length;
+        if (cost + size > budget && current.length > 0) {
+            chunks.push(current);
+            current = "";
+            cost = 0;
+        }
+        current += character;
+        cost += size;
+    }
+    if (current.length > 0 || chunks.length === 0)
+        chunks.push(current);
+    return chunks;
+}
+/**
+ * Split an already-marked-up segment so every chunk is valid HTML on its own.
+ *
+ * {@link chunkForTelegram} may cut anywhere because its caller escapes each
+ * chunk and wraps it in `<pre>`; the claimed segment carries markup, so a cut
+ * inside `<b>` or inside `&amp;` would reach Telegram as a parse error, and a
+ * cut between an opening tag and its close would reach it as unbalanced HTML.
+ * Tags and entities are therefore atomic here, and the break is taken at the
+ * last line boundary in the chunk when there is one, which keeps each bullet
+ * whole and balanced. A bullet longer than the budget on its own (a rationale
+ * is unbounded agent text) splits inside its text, between tags, never within
+ * one — and it splits rather than being shortened, for the same reason a
+ * payload does.
+ */
+export function chunkClaimedForTelegram(text, budget = SEGMENT_BUDGET) {
+    /** One line, as pieces no longer than the budget, cut between atoms only. */
+    const pieces = (input) => {
+        if (input.length <= budget)
+            return [input];
+        const out = [];
+        let piece = "";
+        for (const atom of input.match(/<[^>]*>|&[^;\s]*;|[\s\S]/gu) ?? []) {
+            if (piece.length + atom.length > budget && piece.length > 0) {
+                out.push(piece);
+                piece = "";
+            }
+            piece += atom;
+        }
+        if (piece.length > 0)
+            out.push(piece);
+        return out;
+    };
+    const chunks = [];
+    let current = "";
+    for (const linePieces of text.split("\n").map(pieces)) {
+        for (const piece of linePieces) {
+            const candidate = current.length === 0 ? piece : `${current}\n${piece}`;
+            if (candidate.length > budget) {
+                if (current.length > 0)
+                    chunks.push(current);
+                current = piece;
+            }
+            else {
+                current = candidate;
+            }
+        }
+    }
+    if (current.length > 0 || chunks.length === 0)
+        chunks.push(current);
+    return chunks;
+}
+// ---------------------------------------------------------------------------
+// Digests (APRV-115)
+// ---------------------------------------------------------------------------
+/**
+ * The shape token of a payload, for grouping.
+ *
+ * A shell command groups by its `argv[0]`, because that is what makes forty
+ * `network.call` prompts "the same question forty times" to the human reading
+ * them: forty `curl`s are one decision with forty URLs in it, and a `curl` next
+ * to an `rm` is not. Everything else groups by its top-level key set, which is
+ * the structural sense in which two payloads are the same shape.
+ *
+ * Structural, never self-declared: nothing here reads a `kind` or `type` field,
+ * for the reason `payload-view.ts` spells out — a field authored by the party
+ * under oversight must not choose how the party's requests are presented.
+ */
+export function payloadShapeKey(value) {
+    const command = commandPayloadView(value);
+    if (command !== null) {
+        const argv0 = command.command.trim().split(/\s+/u)[0] ?? "";
+        return `argv0:${argv0}`;
+    }
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value !== "object")
+        return `scalar:${typeof value}`;
+    return `keys:${Object.keys(value).sort().join(",")}`;
+}
+/**
+ * The grouping key: requests that share it are the same question asked twice.
+ *
+ * Signed off 2026-08-25 as (class, origin session/task, argv[0] or payload
+ * shape). The requesting actor rides along too, which can only ever SPLIT a
+ * group — two agents working the same task get two digests — and splitting is
+ * the safe direction: it costs a message and never merges two things a human
+ * would have wanted to weigh separately.
+ *
+ * `"\0"` as the separator because every component is agent-influenced text
+ * and a separator that can appear inside one would let a crafted task name
+ * collide two classes into one group. Written as the escape, never the raw
+ * byte: a literal NUL in the source turns this file into "binary" for grep,
+ * diff tooling, and editors, and the escape compiles to the same string.
+ */
+export function digestKeyOf(request) {
+    return [
+        request.class.value,
+        request.task.value ?? "",
+        request.autonomy.value,
+        originOf(request.summary),
+        payloadShapeKey(request.fullPayload.value?.value),
+    ].join("\0");
+}
+/**
+ * Split `requests` into digest groups, preserving queue order.
+ *
+ * One poll window is the whole window: this is called on the requests one
+ * dispatch cycle found undelivered, and nothing here waits for more. A group of
+ * one is returned as a group of one, and the caller sends it as an ordinary
+ * prompt.
+ */
+/**
+ * The key that makes ONE tool call one question (APRV-287), or `null` for a
+ * request that names no task or no payload.
+ *
+ * A shell command that touches several classes raises one request per class
+ * (`cli/hook.ts` mints `<task>:<class>` keys), and every one of them carries the
+ * same task and the same payload hash: they are one command, asked about once,
+ * with the log keeping a record per class because that is what audit granularity
+ * requires. Grouping them by class the way {@link digestKeyOf} does put five
+ * separate cards on a phone for one `git commit && git push` on 2026-09-06, and
+ * the approver had to tap through three rounds of them.
+ *
+ * The pair is enough on its own. A task id is one tool call, and a payload hash
+ * is the bytes it is about, so two requests sharing both are two classes of one
+ * command and can never be two commands. Both are computed: the task id is
+ * minted by the runtime and the hash is recomputed from the payload bytes
+ * (`channels/contract.ts`), so nothing an agent authors chooses this grouping.
+ */
+function toolCallKeyOf(request) {
+    const task = request.task.value;
+    const hash = request.payload_hash.value;
+    if (task === null || task.length === 0)
+        return null;
+    if (typeof hash !== "string" || hash.length === 0)
+        return null;
+    return [task, hash].join("\0");
+}
+export function groupForDigest(requests, max = TELEGRAM_DIGEST_MAX_MEMBERS) {
+    const groups = [];
+    const byKey = new Map();
+    // APRV-287, before the class grouping and never instead of it. The classes of
+    // one tool call are one question however many they are; everything else is
+    // grouped as it always was, so a burst of forty separate `network.call`s from
+    // forty tool calls still digests by class.
+    // Only where the classes DIFFER: members of one tool call that share a class
+    // are grouped by the class key already, and the two groupings then agree.
+    // Narrowing it this way keeps every existing grouping exactly as it was and
+    // changes only the case this task is about, the one command a human was asked
+    // about once per class.
+    const oneCall = new Set();
+    const seen = new Map();
+    for (const request of requests) {
+        const key = toolCallKeyOf(request);
+        if (key === null)
+            continue;
+        const classes = seen.get(key) ?? new Set();
+        classes.add(request.class.value);
+        seen.set(key, classes);
+        if (classes.size > 1)
+            oneCall.add(key);
+    }
+    for (const request of requests) {
+        const call = toolCallKeyOf(request);
+        const key = call !== null && oneCall.has(call) ? `tool-call\0${call}` : digestKeyOf(request);
+        let group = byKey.get(key);
+        // A group that has reached the cap is closed and a fresh one opened under
+        // the same key: a burst of twenty becomes three digests, never one wall.
+        if (group === undefined || group.length >= max) {
+            group = [];
+            byKey.set(key, group);
+            groups.push(group);
+        }
+        group.push(request);
+    }
+    return groups;
+}
+/**
+ * The computed facts a digest's members share, as the digest states them.
+ *
+ * Every one is read off the first member, which is sound precisely because the
+ * grouping key made them equal across the set: a digest whose members disagreed
+ * about their class or their task is a digest the listener would not have
+ * built. The last line is the one an approver needs most — it says how many
+ * payloads are above and that each request has its own.
+ */
+export function digestFacts(members) {
+    const first = members[0];
+    if (first === undefined)
+        return [];
+    // APRV-287. A digest may now carry the several classes of ONE tool call, so
+    // the class line states the set rather than the first member's, and the
+    // grouping line says which of the two groupings put this set together. A
+    // digest whose members share one class reads exactly as it did.
+    const classes = [...new Set(members.map((member) => member.class.value))];
+    const shared = sharedPayload(members);
+    const autonomies = [...new Set(members.map((member) => member.autonomy.value))];
+    return [
+        { label: "class", text: classes.join(", "), origin: originOf(first.class) },
+        { label: "autonomy", text: autonomies.join(", "), origin: originOf(first.autonomy) },
+        { label: "task", text: first.task.value ?? "(none)", origin: originOf(first.task) },
+        {
+            label: "grouped by",
+            text: shared === null
+                ? `one class, one task, one payload shape (${payloadShapeKey(first.fullPayload.value?.value)})`
+                : `one tool call: one task, one payload, ${String(classes.length)} class(es) of the same command`,
+            origin: "grouping",
+        },
+        {
+            label: "payloads",
+            text: shared === null
+                ? `${members.length} full payloads, one per request, in the ${members.length} prompts above this message`
+                : `one payload, shared by all ${members.length} requests, in the prompt above this message`,
+            origin: originOf(first.fullPayload),
+        },
+    ];
+}
+/**
+ * The one payload every member is about, or `null` when they differ
+ * (APRV-287).
+ *
+ * The computed hash decides it, never the rendering: two members share a
+ * payload when the bytes the grants bind to are the same bytes. A member whose
+ * full payload the channel was not given in full is not a shared payload
+ * either, because "they are all this one, which you have read" is a claim about
+ * something the approver was shown.
+ */
+function sharedPayload(members) {
+    const first = members[0];
+    if (first === undefined || members.length < 2)
+        return null;
+    const hash = first.payload_hash.value;
+    if (typeof hash !== "string" || hash.length === 0)
+        return null;
+    if (!members.every((member) => member.payload_hash.value === hash))
+        return null;
+    const rendering = first.fullPayload.value;
+    if (rendering === null || rendering.truncated)
+        return null;
+    return first;
+}
+/**
+ * The collapsed re-delivery's own message: what is waiting, and one way to
+ * clear it (APRV-287).
+ *
+ * Everything above the buttons is computed by the runtime from the verified log
+ * — the count, the ages, the classes — and the per-member lines carry the
+ * agent's own summaries under a heading that says so, exactly as an ordinary
+ * digest does. What it does NOT carry is any payload, and the message says so
+ * in the same breath as it explains why the only button rejects: a decision is
+ * bound to the bytes the approver was shown, and nothing here shows them.
+ */
+function renderStaleSummary(digest, stale, open, total) {
+    const lines = [
+        `<b>${escapeHtml(open === 0
+            ? `ALL ${total} STALE REQUESTS DECIDED`
+            : `${open} STALE REQUEST${open === 1 ? "" : "S"} — NOBODY IS WAITING ON ${open === 1 ? "IT" : "THEM"}`)}</b>`,
+        "",
+        "<b>COMPUTED — derived by the runtime from the log and the policy</b>",
+        ...stale.lines.map((line) => `• ${escapeHtml(line)}`),
+        ...digest.facts.map((fact) => `• <b>${escapeHtml(fact.label)}:</b> ${escapeHtml(fact.text)} <i>(${escapeHtml(fact.origin)})</i>`),
+        "",
+        `<b>CLAIMED — authored by ${escapeHtml(digest.author)}, NOT verified by the runtime</b>`,
+    ];
+    for (const [index, member] of digest.members.entries()) {
+        lines.push(`${index + 1}. <code>${escapeHtml(member.actionKey)}</code> — ${escapeHtml(member.summary)}`);
+        if (member.settled !== null) {
+            lines.push(`   <b>${escapeHtml(member.settled.headline)}</b>`);
+            for (const detail of member.settled.detail)
+                lines.push(`   ${escapeHtml(detail)}`);
+        }
+    }
+    lines.push("", escapeHtml("These asked while a hook waited, and the wait is long over: no tool call is holding the answer. This message carries NO payload, so it offers no approve button — a decision is bound to the bytes you were shown, and nothing here shows them. Rejecting is one log event per request and authorizes nothing. To approve one instead, decide it on its own card or run `approval grant <action key>`; the requests stay listed by /queue either way."));
+    const rows = open === 0
+        ? []
+        : [
+            [
+                {
+                    text: `🛑 Reject all (${open})`,
+                    callback_data: digestCallbackData("R", digest.allNonce),
+                },
+            ],
+        ];
+    return {
+        text: lines.join("\n"),
+        keyboard: rows.length === 0 ? null : { inline_keyboard: rows },
+    };
+}
+/** The digest's headline, given how much of it is still open. */
+function digestHeadline(open, total) {
+    if (open === 0)
+        return `ALL ${total} REQUESTS DECIDED`;
+    if (open === total)
+        return `${total} REQUESTS AWAITING APPROVAL`;
+    return `${open} OF ${total} REQUESTS STILL AWAITING APPROVAL`;
+}
+/**
+ * The digest message: text plus the keyboard for whatever is still open.
+ *
+ * Pure. The computed/claimed split of an ordinary prompt is kept — the shared
+ * facts are computed and sit under a heading that says so, the per-member lines
+ * are the agent's own words and sit under one that says they are not verified —
+ * because a digest is a prompt, and SPEC.md §9 does not stop applying because
+ * there are five of them.
+ *
+ * A settled member keeps its line, gains its outcome underneath, and loses its
+ * buttons. The "all" row appears only while two or more members are open: with
+ * one left, "all" is the same tap as its own Approve and a second way to do one
+ * thing is a way to do the wrong one.
+ */
+export function renderDigest(digest) {
+    const open = digest.members.filter((member) => member.settled === null);
+    const total = digest.members.length;
+    const stale = digest.stale ?? null;
+    if (stale !== null)
+        return renderStaleSummary(digest, stale, open.length, total);
+    const lines = [
+        `<b>${escapeHtml(digestHeadline(open.length, total))}</b>`,
+        "",
+        "<b>COMPUTED — derived by the runtime from the log and the policy</b>",
+        ...digest.facts.map((fact) => `• <b>${escapeHtml(fact.label)}:</b> ${escapeHtml(fact.text)} <i>(${escapeHtml(fact.origin)})</i>`),
+        "",
+        `<b>CLAIMED — authored by ${escapeHtml(digest.author)}, NOT verified by the runtime</b>`,
+    ];
+    for (const [index, member] of digest.members.entries()) {
+        lines.push(`${index + 1}. <code>${escapeHtml(member.actionKey)}</code> — ${escapeHtml(member.summary)} · ${escapeHtml(member.cost)}`);
+        if (member.settled !== null) {
+            lines.push(`   <b>${escapeHtml(member.settled.headline)}</b>`);
+            for (const detail of member.settled.detail)
+                lines.push(`   ${escapeHtml(detail)}`);
+        }
+    }
+    lines.push("", escapeHtml(`Each button decides ONE request, numbered as above. "all" is ${open.length} separate decisions, one log event each; the full payload of every request is in the messages above this one.`));
+    const rows = [];
+    for (const [index, member] of digest.members.entries()) {
+        if (member.settled !== null)
+            continue;
+        rows.push([
+            {
+                text: `✅ Approve ${index + 1}`,
+                callback_data: callbackData("g", member.nonce, member.actionKey),
+            },
+            {
+                text: `🛑 Reject ${index + 1}`,
+                callback_data: callbackData("r", member.nonce, member.actionKey),
+            },
+        ]);
+    }
+    if (open.length > 1) {
+        rows.push([
+            {
+                text: `✅ Approve all (${open.length})`,
+                callback_data: digestCallbackData("G", digest.allNonce),
+            },
+            {
+                text: `🛑 Reject all (${open.length})`,
+                callback_data: digestCallbackData("R", digest.allNonce),
+            },
+        ]);
+    }
+    return {
+        text: lines.join("\n"),
+        keyboard: rows.length === 0 ? null : { inline_keyboard: rows },
+    };
+}
+// ---------------------------------------------------------------------------
+// Callback data
+// ---------------------------------------------------------------------------
+/**
+ * The stable short reference to an action key that a button carries (APRV-196).
+ *
+ * The first {@link ACTION_REF_HEX} hex characters of the key's sha256. Two
+ * properties earn it its place, and they are the two the old scheme lacked:
+ *
+ * 1. **It always fits.** `<verb>:<nonce>:<ref>` is well inside Telegram's
+ *    64-byte cap for any nonce this class issues, so the cross-check that used
+ *    to be dropped for a long action key is now always present.
+ * 2. **It survives a restart.** The nonce is per-process and per-copy; the ref
+ *    is a function of the action key alone, so two copies of the same request
+ *    delivered by two different listener processes carry the same ref. That is
+ *    what lets a tap on a pre-restart copy resolve to the request the current
+ *    process is holding, instead of dying as an unknown nonce.
+ *
+ * It is a REFERENCE and never an authorization. The bytes come back from the
+ * network, so a ref is only ever matched against deliveries THIS process made
+ * (and only from the configured chat); it can select among what the listener
+ * has itself put in front of the approver, and it can name nothing else.
+ */
+export const ACTION_REF_HEX = 16;
+export function actionRefOf(actionKey) {
+    return createHash("sha256").update(actionKey, "utf8").digest("hex").slice(0, ACTION_REF_HEX);
+}
+/**
+ * `callback_data` for one button: `<g|r>:<nonce>:<action ref>`.
+ *
+ * The **nonce is authoritative** where it resolves: it is issued by this process
+ * at `notify` and maps to the request that was actually delivered, so an
+ * ordinary tap never consults the ref for anything but a cross-check (a
+ * mismatch is an anomaly and the callback is dropped). The ref is the fallback
+ * for the copy whose nonce this process never issued, and {@link actionRefOf}
+ * states the bound on what that fallback may reach.
+ */
+export function callbackData(verb, nonce, actionKey) {
+    const withRef = `${verb}:${nonce}:${actionRefOf(actionKey)}`;
+    // Unreachable with the nonces this class issues, and kept because the failure
+    // it guards is the worst one available here: `callback_data` over the cap is
+    // refused by `sendMessage`, so an over-long nonce would stop DELIVERY rather
+    // than degrade a lookup. Dropping the reference costs a stale copy's tap its
+    // rescue and leaves every other property intact.
+    return Buffer.byteLength(withRef, "utf8") <= TELEGRAM_MAX_CALLBACK_BYTES
+        ? withRef
+        : `${verb}:${nonce}`;
+}
+/**
+ * `callback_data` for a digest's "all" button: `<G|R>:<nonce>` (APRV-115).
+ *
+ * Upper case, and no action key: an "all" button names a *delivery*, and the
+ * set it decides is whichever members of that delivery are still open at the
+ * moment of the tap — which the delivering process knows and the network does
+ * not. Naming keys in the bytes would let something that can reach the bot
+ * choose the set, and there is no length at which that becomes acceptable.
+ */
+export function digestCallbackData(verb, nonce) {
+    return `${verb}:${nonce}`;
+}
+/**
+ * `callback_data` for the checkpoint prompt's two buttons (APRV-257).
+ *
+ * `k:<nonce>` signs, `x:<nonce>` declines. Verbs of their own rather than a
+ * reuse of `g`/`r`, and the separation is load-bearing: {@link CALLBACK_VERBS}
+ * maps every decision verb onto a grant or a reject, so a checkpoint button
+ * spelled `g` would be a button {@link parseCallbackData} hands to the decision
+ * path — where an unknown nonce becomes an action-reference lookup, and a
+ * signature gesture starts hunting for a request to approve. Two vocabularies,
+ * two parsers, and neither can be read as the other.
+ *
+ * No action key and no reference in the bytes: a checkpoint names no request,
+ * and the head it covers is held by the process that issued the nonce, exactly
+ * as a digest's member set is. Nothing that can reach the bot chooses what gets
+ * signed.
+ */
+export function checkpointCallbackData(verb, nonce) {
+    return `${verb}:${nonce}`;
+}
+/** `k:<nonce>` / `x:<nonce>`, or `null` for anything else. Never throws. */
+export function parseCheckpointCallback(data) {
+    if (typeof data !== "string")
+        return null;
+    const verb = data.slice(0, 1);
+    if ((verb !== "k" && verb !== "x") || data.slice(1, 2) !== ":")
+        return null;
+    const nonce = data.slice(2);
+    if (nonce.length === 0 || nonce.includes(":"))
+        return null;
+    return { sign: verb === "k", nonce };
+}
+const CALLBACK_VERBS = {
+    g: { decision: "grant", scope: "one" },
+    r: { decision: "reject", scope: "one" },
+    G: { decision: "grant", scope: "all" },
+    R: { decision: "reject", scope: "all" },
+};
+export function parseCallbackData(data) {
+    if (typeof data !== "string")
+        return null;
+    const first = data.indexOf(":");
+    if (first === -1)
+        return null;
+    const verb = CALLBACK_VERBS[data.slice(0, first)];
+    if (verb === undefined)
+        return null;
+    const rest = data.slice(first + 1);
+    const second = rest.indexOf(":");
+    const nonce = second === -1 ? rest : rest.slice(0, second);
+    if (nonce.length === 0)
+        return null;
+    return {
+        decision: verb.decision,
+        scope: verb.scope,
+        nonce,
+        actionRef: second === -1 ? null : rest.slice(second + 1),
+    };
+}
+// ---------------------------------------------------------------------------
+// Review cards (APRV-299)
+// ---------------------------------------------------------------------------
+/**
+ * The headline of a retrospective review card.
+ *
+ * Deliberately not {@link TELEGRAM_PROMPT_HEADING} and deliberately not a
+ * question. A sample is an action that ALREADY RAN: nothing is pending, no
+ * token is minted by any button on this message, and a card that said
+ * "APPROVAL REQUIRED" would be telling the approver they are holding something
+ * up. The supervised bargain (SPEC.md §5.2) is "execute now, a fraction is
+ * reviewed after", and this is the "after".
+ */
+export const TELEGRAM_REVIEW_HEADING = "REVIEW — THIS ALREADY RAN";
+/** The headline a recorded review puts on the card it settles. */
+export const TELEGRAM_REVIEW_RECORDED = "✓ REVIEWED";
+/** The headline a recorded DENIAL puts on the card it settles. */
+export const TELEGRAM_REVIEW_DENIED = "✗ REVIEWED — DENIED";
+/**
+ * The headline a card wears while a first Deny tap is armed and nothing has
+ * been recorded.
+ */
+export const TELEGRAM_REVIEW_ARMED = "DENY ARMED — nothing is recorded yet";
+/**
+ * What a review tap's single answer says (APRV-302).
+ *
+ * {@link TELEGRAM_ACK_HEARD}'s "deciding" is a request card's word: something is
+ * pending, and the tap just settled it. A review decides nothing — the action
+ * ran, and what the tap does is record what a person thought of it — so a
+ * reviewer told they were "deciding" is being told the wrong thing about the
+ * card in front of them. The load-bearing half is carried over unchanged: this
+ * claims only that the tap ARRIVED, never that anything was appended, because at
+ * the moment it is sent nothing has been and `core/audit.ts` may still refuse.
+ * What became of it is on the card edit that follows.
+ */
+export const TELEGRAM_REVIEW_ACK = "Heard — recording your review. The card will say what the log recorded.";
+/** The toast a first Deny tap gets: it says plainly that nothing was written. */
+export const TELEGRAM_REVIEW_ARM_TOAST = "Deny armed — nothing recorded. Tap Deny again to record it, or a reaction to record it with a grade.";
+/** The toast a reaction that needs the human's own words gets. */
+export const TELEGRAM_REVIEW_NOTE_TOAST = "Heard — reply to the prompt with why. Nothing is recorded until it arrives.";
+/**
+ * What the ForceReply prompt asks for.
+ *
+ * A separate message rather than a second keyboard, because Telegram's inline
+ * keyboards have no text input at all — the same limitation the reject path
+ * documents. The prompt is bound to its card by the message id the reply names,
+ * which this process holds and the network does not.
+ */
+export function reviewNotePromptLines(reaction, verdict, actionKey) {
+    return [
+        `WHY ${reaction.toUpperCase()}?`,
+        `Reply to this message with the reason. It is recorded verbatim beside a ${verdict} review of ${actionKey}.`,
+        "Nothing has been appended yet, and a blank reply appends nothing: the grade an agent is most likely to act on is the one it can least interpret alone.",
+    ];
+}
+/**
+ * The six things a review card's buttons can say (APRV-299).
+ *
+ * `ok` and `deny` are the verdict, which is enforcement; the four reactions are
+ * the grade, which is not (SPEC.md §11.1 invariant 10). Both travel in the same
+ * closed vocabulary because they arrive through the same six buttons, and a
+ * seventh word would be a button nobody drew.
+ */
+export const REVIEW_CHOICES = ["ok", "deny", ...REACTIONS];
+/**
+ * `callback_data` for one review button: `v:<nonce>:<choice>`.
+ *
+ * Its own verb, for exactly the reason the checkpoint prompt's is its own
+ * (APRV-257): {@link CALLBACK_VERBS} maps every DECISION verb onto a grant or a
+ * reject, so a review button spelled `g` would be handed to the decision path,
+ * where an unresolved nonce falls back to an action-reference lookup and a
+ * gesture about something that already happened would start hunting for a
+ * request to approve. Three vocabularies, three parsers, and none can be read
+ * as another.
+ *
+ * No action reference in the bytes, and no sample seq: the card names a
+ * DELIVERY, and which sample that delivery is about is held by the process that
+ * issued the nonce. Nothing that can reach the bot chooses what gets reviewed.
+ * There is also no stale-copy ladder underneath it: a review is never urgent,
+ * a lost card leaves the sample open, and the next cycle offers it again.
+ */
+export function reviewCallbackData(choice, nonce) {
+    return `v:${nonce}:${choice}`;
+}
+/** `v:<nonce>:<choice>`, or `null` for anything else. Never throws. */
+export function parseReviewCallback(data) {
+    if (typeof data !== "string")
+        return null;
+    if (data.slice(0, 2) !== "v:")
+        return null;
+    const rest = data.slice(2);
+    const split = rest.indexOf(":");
+    if (split <= 0)
+        return null;
+    const nonce = rest.slice(0, split);
+    const choice = rest.slice(split + 1);
+    const found = REVIEW_CHOICES.find((candidate) => candidate === choice);
+    return found === undefined ? null : { nonce, choice: found };
+}
+/**
+ * The label each button carries. Emoji live here and never in message text.
+ *
+ * Bare emoji, no words (APRV-302). The first live cards put a word beside every
+ * glyph, which bought nothing: six labelled buttons on a phone wrap, and the
+ * words repeated what the card had already said in full sentences above them.
+ * The layout is what carries the meaning now: row one is the verdict (record it
+ * as fine, or arm the denial), row two is the grade, worst to best, in the same
+ * order `REACTIONS` gives everywhere else.
+ */
+const REVIEW_BUTTON_LABELS = {
+    ok: "✅",
+    deny: "🛑",
+    disliked: "👎",
+    indifferent: "😐",
+    liked: "👍",
+    loved: "❤️",
+};
+/**
+ * How much of one refusal message a card carries.
+ *
+ * The audit refusals are paragraphs — they explain what the reviewer meant and
+ * how to say it instead — and a card carrying one whole can overrun Telegram's
+ * message limit, at which point the edit fails and the human is told nothing at
+ * all. So the prose is cut and the cut is marked. The CODE is never cut: it is
+ * the machine-readable half, it is short, and it is on its own line above.
+ */
+const REVIEW_NOTICE_MAX = 900;
+function trimNotice(text) {
+    return text.length <= REVIEW_NOTICE_MAX
+        ? text
+        : `${text.slice(0, REVIEW_NOTICE_MAX)}… (cut to fit one message; the whole refusal is on the listener's stderr)`;
+}
+/**
+ * The card's message: the rows, whatever notice the last tap produced, and the
+ * keyboard.
+ *
+ * No paragraph explaining the buttons (APRV-302). The heading
+ * ({@link TELEGRAM_REVIEW_HEADING}) is what says a review is not a request, and
+ * the deny latch says itself: the first tap is answered by
+ * {@link TELEGRAM_REVIEW_ARM_TOAST} and the card's own heading becomes
+ * {@link TELEGRAM_REVIEW_ARMED} until it is spent. Four sentences of rules under
+ * every card said the same thing to a reader who had already read them once, and
+ * pushed the rows a review is actually about off the first screen.
+ *
+ * Pure. Two things it deliberately does NOT carry, and both are the same rule
+ * read twice: no payload region, and no approve button. SPEC.md §10.3 requires
+ * the canonical rendering in front of an approver before a DECISION is
+ * collected, and this collects none — the action ran, the review says only what
+ * a person thought of it, and a card that offered an approve would be
+ * presenting a settled fact as a live authorization. A sample is never
+ * delivered as an approval request and never accepts a token.
+ */
+export function renderReviewCard(state) {
+    const card = state.card;
+    const key = card.fields.action_key.value;
+    if (state.settled !== null) {
+        return {
+            text: [
+                `<b>${escapeHtml(state.settled.headline)}</b>`,
+                `<code>${escapeHtml(key)}</code>`,
+                "",
+                ...state.settled.detail.map((entry) => escapeHtml(trimNotice(entry))),
+            ].join("\n"),
+            keyboard: null,
+        };
+    }
+    const computedLines = [];
+    const claimedLines = [];
+    for (const row of REVIEW_CARD_ROWS) {
+        const candidate = reviewRow(card.fields, row);
+        if (candidate === null)
+            continue;
+        if (candidate.line.kind === "computed")
+            computedLines.push(candidate.line);
+        else
+            claimedLines.push(candidate.line);
+    }
+    computedLines.push(line("ran_at", card.ranAt, "ran at", card.ranAt.value));
+    computedLines.push(line("verdict", card.verdict, "verdict", card.verdict.value));
+    const render = (entry) => `• <b>${escapeHtml(entry.label)}:</b> ${escapeHtml(entry.text)} <i>(${escapeHtml(entry.origin)})</i>`;
+    const author = originOf(card.fields.summary);
+    const lines = [
+        `<b>${escapeHtml(state.denyArmed ? `${TELEGRAM_REVIEW_HEADING} — ${TELEGRAM_REVIEW_ARMED}` : TELEGRAM_REVIEW_HEADING)}</b>`,
+        `<code>${escapeHtml(key)}</code>`,
+        "",
+        "<b>COMPUTED — derived by the runtime from the log, the policy and the payload bytes</b>",
+        ...computedLines.map(render),
+        "",
+        `<b>CLAIMED — authored by ${escapeHtml(author)}, NOT verified by the runtime</b>`,
+        ...claimedLines.map(render),
+    ];
+    if (state.notice !== null) {
+        lines.push("", `<b>${escapeHtml(state.notice.headline)}</b>`, ...state.notice.lines.map((entry) => escapeHtml(trimNotice(entry))));
+    }
+    const button = (choice) => ({
+        text: REVIEW_BUTTON_LABELS[choice],
+        callback_data: reviewCallbackData(choice, state.nonce),
+    });
+    return {
+        text: lines.join("\n"),
+        keyboard: {
+            inline_keyboard: [
+                [button("ok"), button("deny")],
+                REACTIONS.map((reaction) => button(reaction)),
+            ],
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Errors and redaction
+// ---------------------------------------------------------------------------
+/** A Bot API call that did not produce a usable result. */
+export class TelegramApiError extends Error {
+    method;
+    status;
+    description;
+    constructor(message, method, 
+    /**
+     * The HTTP status, when the failure was an HTTP one. `null` for a transport
+     * failure, an unparseable body, or an `ok: false` envelope that arrived
+     * with a 200 (APRV-277).
+     */
+    status = null, 
+    /**
+     * The Bot API's own `description` for this failure, redacted, when the
+     * error body carried one. `null` when the body was absent, unreadable, not
+     * JSON, or carried no description.
+     */
+    description = null) {
+        super(message);
+        this.method = method;
+        this.status = status;
+        this.description = description;
+        this.name = "TelegramApiError";
+    }
+}
+/**
+ * Telegram's wording for "that edit would have changed nothing" (APRV-277).
+ *
+ * Matched on the description rather than the status alone, because 400 is also
+ * every malformed edit, every wrong chat and every deleted message.
+ */
+const TELEGRAM_NOT_MODIFIED = /message is not modified/iu;
+/**
+ * Whether a failed call is the Bot API saying an edit changed nothing
+ * (APRV-277).
+ *
+ * `editMessageText` answers 400 "Bad Request: message is not modified" when the
+ * text and the keyboard it was handed are already what the message holds. Every
+ * caller here re-annotates from the verified log rather than from memory, so a
+ * message annotated once and derived again produces exactly that: the phone
+ * already shows the outcome, and the operator has nothing to be told. It is the
+ * one 400 that means the intended state stands, which is why it is the only one
+ * that goes unreported.
+ */
+export function isMessageNotModified(cause) {
+    return (cause instanceof TelegramApiError &&
+        cause.status === 400 &&
+        cause.description !== null &&
+        TELEGRAM_NOT_MODIFIED.test(cause.description));
+}
+export class TelegramChannel {
+    name = "telegram";
+    token;
+    chatId;
+    apiBase;
+    fetchImpl;
+    pollTimeoutSeconds;
+    requestTimeoutMs;
+    backoffMs;
+    maxBackoffMs;
+    complain;
+    makeNonce;
+    /** The policy's approval TTL, or `null` when it declares none (APRV-135). */
+    approvalTtlMs;
+    now;
+    /** The listener's verified-log probe for a stale tap (APRV-196), or null. */
+    describeAction;
+    /** The policy's row layout for this channel (APRV-218). Read-only, and pure input to the renderer. */
+    layout;
+    /** When {@link sweep} last ran, so the poll loop can call it every cycle. */
+    lastSweepMs = Number.NEGATIVE_INFINITY;
+    /**
+     * The callback query being handled, and whether an ack has been attempted for
+     * it (APRV-196). Set and cleared by {@link handleUpdate}, which processes
+     * updates one at a time and awaits each.
+     */
+    ack = null;
+    handler = null;
+    /**
+     * What to do with a bot command (APRV-216). Absent unless the runtime asked
+     * for commands, and its absence is what keeps `message` out of
+     * `allowed_updates` — see {@link onCommand}.
+     */
+    commandHandler = null;
+    /**
+     * What to do with a checkpoint tap (APRV-257). Absent unless the runtime
+     * registered one, and its absence makes {@link offerCheckpoint} refuse: a
+     * button nobody is listening for is a button that spins on a phone.
+     */
+    checkpointHandler = null;
+    /**
+     * Checkpoint nonce -> the head that prompt asked about, and the message it is
+     * on. **In memory only**, like every other map in this class and for the same
+     * reason (SPEC.md §10.3: channels hold no state that is a source of truth).
+     *
+     * The head lives HERE and not in the callback bytes, so what is signed is
+     * what this process put on the screen. Losing the map to a restart costs a
+     * tap its meaning — the button answers `unknown-callback` and the listener
+     * offers again on its next lapse — and can never cost a signature over
+     * something nobody was shown.
+     */
+    checkpointNonces = new Map();
+    /**
+     * What to do with a review tap (APRV-299). Absent unless the runtime
+     * registered one, and its absence makes {@link offerReview} refuse, for the
+     * reason {@link offerCheckpoint} refuses: a button nobody is listening for is
+     * a button that spins on a phone.
+     */
+    reviewHandler = null;
+    /**
+     * Review card message id -> what is on it. Delivery bookkeeping, never truth
+     * (SPEC.md §10.3). Losing it to a restart costs the card its buttons; the
+     * sample stays open in the log, `approval audit list` still names it, and the
+     * next cycle offers a fresh card.
+     */
+    reviewCards = new Map();
+    /** Review nonce -> the card message it was issued for. */
+    reviewNonces = new Map();
+    /** Note-prompt message id -> the card whose reply it is waiting for. */
+    reviewNotePrompts = new Map();
+    deliveries = new Map();
+    /** Digest message id -> what is on it. Delivery bookkeeping, never truth. */
+    digests = new Map();
+    /** "All" nonce -> the digest message it was issued for. */
+    allNonces = new Map();
+    rendered = [];
+    offset = 0;
+    counter = 0;
+    stopped = false;
+    inFlight = null;
+    counters = {
+        notified: 0,
+        updates: 0,
+        decisions: 0,
+        pollErrors: 0,
+        anomalies: {
+            "foreign-chat": 0,
+            "malformed-callback": 0,
+            "unknown-callback": 0,
+            "key-mismatch": 0,
+            "stale-copy": 0,
+            "unknown-command": 0,
+        },
+        staleCopyDecisions: 0,
+        commands: 0,
+        reviews: 0,
+    };
+    constructor(config) {
+        this.token = config.token;
+        this.chatId = String(config.chatId);
+        this.apiBase = (config.apiBase ?? TELEGRAM_DEFAULT_API_BASE).replace(/\/+$/u, "");
+        this.fetchImpl = config.fetch ?? globalThis.fetch;
+        this.pollTimeoutSeconds = config.pollTimeoutSeconds ?? DEFAULT_POLL_TIMEOUT_SECONDS;
+        this.requestTimeoutMs = config.requestTimeoutMs ?? null;
+        this.backoffMs = config.backoffMs ?? DEFAULT_BACKOFF_MS;
+        this.maxBackoffMs = config.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+        this.complain =
+            config.log ??
+                ((message) => {
+                    process.stderr.write(`${message}\n`);
+                });
+        this.approvalTtlMs = config.approvalTtlMs ?? null;
+        this.now = config.now ?? (() => Date.now());
+        this.describeAction = config.describeAction ?? null;
+        this.layout = config.layout ?? TELEGRAM_PROMPT_LAYOUT;
+        this.makeNonce =
+            config.nonce ??
+                (() => {
+                    this.counter += 1;
+                    return `${this.counter.toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+                });
+    }
+    // -------------------------------------------------------------------------
+    // Channel
+    // -------------------------------------------------------------------------
+    onDecision(handler) {
+        this.handler = handler;
+    }
+    /**
+     * Register what to do with a checkpoint tap (APRV-257).
+     *
+     * The handler is the runtime's, on the runtime's side of the boundary, and it
+     * is where the vault passphrase and the signing live. This channel holds a
+     * nonce, a message id and a `(seq, hash)`, and hands the head back when the
+     * button is pressed — the same shape as {@link onDecision}, for the same
+     * reason: a channel that signed anything would be a channel with authority.
+     */
+    onCheckpoint(handler) {
+        this.checkpointHandler = handler;
+    }
+    /**
+     * Put one `CHECKPOINT DUE` prompt in the chat, with a Sign and a Not now
+     * button (APRV-257).
+     *
+     * A unit like any other: the paced walkthrough sends it as one thing to read,
+     * and it is never grouped into a digest, because a digest is a set of
+     * SIMILAR REQUESTS decided together and a checkpoint is neither a request nor
+     * similar to one.
+     *
+     * Refuses when no handler is registered, rather than sending a dead button.
+     */
+    async offerCheckpoint(prompt) {
+        if (this.checkpointHandler === null) {
+            throw new Error("no checkpoint handler is registered on the telegram channel; the runtime registers one before offerCheckpoint(), and a channel that signed its own checkpoint would be deciding rather than transporting (SPEC.md §10.3)");
+        }
+        const nonce = this.makeNonce();
+        const result = await this.call("sendMessage", {
+            chat_id: this.chatId,
+            text: prompt.lines
+                .map((entry, index) => (index === 0 ? `<b>${escapeHtml(entry)}</b>` : escapeHtml(entry)))
+                .join("\n"),
+            parse_mode: "HTML",
+            disable_web_page_preview: true,
+            reply_markup: {
+                inline_keyboard: [
+                    [
+                        { text: "Sign", callback_data: checkpointCallbackData("k", nonce) },
+                        { text: "Not now", callback_data: checkpointCallbackData("x", nonce) },
+                    ],
+                ],
+            },
+        });
+        const deliveryId = String(result.message_id);
+        this.checkpointNonces.set(nonce, { deliveryId, head: prompt.head });
+        return deliveryId;
+    }
+    /**
+     * Register what to do with a review tap (APRV-299).
+     *
+     * The handler is the runtime's, on the runtime's side of the boundary, and it
+     * is where the human-only `reviewSample` lives — same shape as
+     * {@link onDecision} and {@link onCheckpoint}, for the same reason: a channel
+     * that appended an `audit.reviewed` of its own would be a supervision backlog
+     * emptying itself through its own transport.
+     *
+     * Registering it, like registering a command handler, is what makes this
+     * channel read `message` updates at all: the note a `loved` or `disliked`
+     * asks for arrives as a reply, and an inline keyboard has no text input.
+     */
+    onReview(handler) {
+        this.reviewHandler = handler;
+    }
+    /**
+     * Put one retrospective review card in the chat (APRV-299).
+     *
+     * A unit like a checkpoint prompt: one thing to read, never grouped into a
+     * digest, and never delivered through {@link notify} — a digest is a set of
+     * similar pending REQUESTS decided together, and a sample is neither pending
+     * nor a request. It sends ONE message: no payload region, and a keyboard
+     * whose six buttons collect a verdict and a grade and mint nothing.
+     *
+     * Refuses when no handler is registered, rather than sending a dead button.
+     */
+    async offerReview(card) {
+        if (this.reviewHandler === null) {
+            throw new Error("no review handler is registered on the telegram channel; the runtime registers one before offerReview(), and a channel that recorded its own audit.reviewed would be the party under oversight closing its own audit item (SPEC.md §5.2, §10.3)");
+        }
+        const nonce = this.makeNonce();
+        const state = {
+            // Assigned once the message exists; nothing consults it before then.
+            deliveryId: "",
+            card,
+            nonce,
+            denyArmed: false,
+            settled: null,
+            notice: null,
+            awaitingNote: null,
+            deliveredAtMs: this.now(),
+        };
+        const drawn = renderReviewCard(state);
+        const result = await this.call("sendMessage", {
+            chat_id: this.chatId,
+            text: drawn.text,
+            parse_mode: "HTML",
+            disable_web_page_preview: true,
+            ...(drawn.keyboard === null ? {} : { reply_markup: drawn.keyboard }),
+        });
+        const deliveryId = String(result.message_id);
+        state.deliveryId = deliveryId;
+        // Armed only now: until the message with the buttons on it exists there is
+        // nothing a callback could legitimately answer.
+        this.reviewCards.set(deliveryId, state);
+        this.reviewNonces.set(nonce, deliveryId);
+        return deliveryId;
+    }
+    /**
+     * Register what to do with `/queue`, `/skip` and `/next` (APRV-216).
+     *
+     * **Registering is what makes this channel read messages at all.** Until a
+     * handler is here, `getUpdates` asks for `callback_query` only, exactly as it
+     * did before this task, so a listener in `burst` delivery consumes no message
+     * updates — which matters because `approval setup channel telegram`
+     * discovers the approver chat by reading one (APRV-74), and a listener that
+     * swallowed it would break the bootstrap of the very channel it runs on.
+     *
+     * The handler owns whatever answer the human gets. This class sends nothing
+     * of its own for a command: it holds no queue to summarise (SPEC.md §10.3),
+     * so the sentence a command produces is written where the pending set is
+     * re-derived, in `cli/channel-telegram.ts`.
+     */
+    onCommand(handler) {
+        this.commandHandler = handler;
+    }
+    health() {
+        const missing = [];
+        if (this.token.length === 0)
+            missing.push(TELEGRAM_TOKEN_ENV);
+        if (this.chatId.length === 0)
+            missing.push(TELEGRAM_CHAT_ENV);
+        if (missing.length > 0) {
+            return { ok: false, detail: `unconfigured: ${missing.join(", ")} is empty` };
+        }
+        const anomalies = Object.values(this.counters.anomalies).reduce((sum, n) => sum + n, 0);
+        const detail = `chat ${this.chatId} via ${this.apiBase}; ${this.counters.notified} notified, ` +
+            `${this.counters.decisions} decision(s), ${this.counters.pollErrors} recovered poll error(s), ` +
+            `${anomalies} ignored callback(s)`;
+        return { ok: true, detail };
+    }
+    /** The rendering split of the most recent `notify`, for the conformance suite. */
+    lastRendered() {
+        return this.rendered;
+    }
+    /** Delivery, decision and anomaly counters. Live; read from anywhere. */
+    stats() {
+        return { ...this.counters, anomalies: { ...this.counters.anomalies } };
+    }
+    /** Ignored callbacks so far. Exposed for `health()` and for operators. */
+    anomalyCount(kind) {
+        if (kind !== undefined)
+            return this.counters.anomalies[kind];
+        return Object.values(this.counters.anomalies).reduce((sum, n) => sum + n, 0);
+    }
+    /**
+     * Put a request, or a set of them, in front of the approver.
+     *
+     * One request is one prompt: its header, its payload chunks, and the
+     * Approve/Reject keyboard on the last message, whose `message_id` is the
+     * delivery id. A {@link ChannelBatch} goes through {@link notifyBatch} and
+     * comes back as a digest when it can be one; either way it gets one shared
+     * batch delivery id, which is what this returns and what every resulting
+     * event will carry.
+     */
+    async notify(target) {
+        if ("requests" in target)
+            return (await this.notifyBatch(target)).batchDeliveryId;
+        const delivered = await this.deliverOne(target, undefined);
+        this.rendered = [delivered.rendered];
+        return delivered.deliveryId;
+    }
+    /**
+     * Deliver a set as one digest, or as one message per member when it cannot
+     * be one (APRV-115).
+     *
+     * The fallback is taken for a set of fewer than two, and for one whose digest
+     * text would not fit inside {@link TELEGRAM_MAX_MESSAGE_CHARS}. Both are the
+     * same rule: the approver sees every member before any button that decides
+     * more than one appears, and when that cannot be arranged the channel sends
+     * MORE messages rather than fewer.
+     *
+     * Not atomic, and it cannot be: a `sendMessage` that fails part way leaves
+     * the messages already sent in the chat, and this throws. Nothing is armed —
+     * the member nonces are registered only once the digest message carrying
+     * their buttons exists — so the caller's retry re-sends the set and the
+     * approver gets a duplicate prompt, never a live button on a half-sent one.
+     */
+    async notifyBatch(batch) {
+        const members = batch.requests;
+        const batchDeliveryId = batch.deliveryId ?? `tg-batch-${this.makeNonce()}`;
+        const digest = members.length < 2 ? null : await this.deliverDigest(members, batchDeliveryId);
+        if (digest !== null) {
+            this.rendered = digest.rendered;
+            return digest;
+        }
+        const rendered = [];
+        const delivered = [];
+        for (const member of members) {
+            const one = await this.deliverOne(member, batchDeliveryId);
+            rendered.push(one.rendered);
+            delivered.push({ action_key: member.action_key.value, delivery_id: one.deliveryId });
+        }
+        this.rendered = rendered;
+        return { batchDeliveryId, digestId: null, members: delivered, rendered };
+    }
+    /**
+     * Deliver a set of stale pending requests as ONE message with a reject-all
+     * button (APRV-287).
+     *
+     * Returns `null` when the message would not fit, and the caller then leaves
+     * the members undelivered so the next cycle shows them the ordinary way:
+     * SPEC.md §10.3's rule for this bookkeeping is that losing it degrades to
+     * showing a request again, never to a pending request nobody is shown.
+     */
+    async notifyStale(members, stale) {
+        if (members.length === 0)
+            return null;
+        return this.deliverDigest(members, `tg-batch-${this.makeNonce()}`, stale);
+    }
+    /**
+     * The digest itself: every member's prompt and payload, then the one message
+     * that carries the buttons.
+     *
+     * Returns `null` when the digest message would not fit, so the caller falls
+     * back — and it decides that BEFORE sending anything, because a fallback
+     * discovered after four member prompts had gone out would double them.
+     *
+     * `stale` (APRV-287) makes it the collapsed re-delivery instead: no member
+     * prompts, no payload, one reject-all button. See {@link StaleSummary}.
+     */
+    async deliverDigest(members, batchDeliveryId, stale = null) {
+        const allNonce = this.makeNonce();
+        const deliveredAtMs = this.now();
+        const state = {
+            deliveredAtMs,
+            // Assigned once the message exists; nothing consults it before then.
+            deliveryId: "",
+            batchDeliveryId,
+            allNonce,
+            stale,
+            facts: stale === null ? digestFacts(members) : [],
+            author: originOf(members[0].summary),
+            members: members.map((member) => ({
+                actionKey: member.action_key.value,
+                nonce: this.makeNonce(),
+                summary: member.summary.value ?? "(none given)",
+                cost: `$${member.est_cost_usd.value.toFixed(2)}`,
+                settled: null,
+            })),
+        };
+        const drawn = renderDigest(state);
+        if (drawn.text.length > TELEGRAM_MAX_MESSAGE_CHARS)
+            return null;
+        // APRV-287. When every member binds to the SAME payload — the several
+        // classes of one tool call — the payload is sent once instead of once per
+        // member. The approver still reads every byte they are deciding about
+        // before any button appears (SPEC.md §10.3), because there is one set of
+        // bytes and it is above the digest; what goes away is five copies of one
+        // command, which was five messages of the flood this task is about.
+        // A collapsed re-delivery sends no payload at all, which is the whole of
+        // what makes it one message; its own text says so and offers no approve, so
+        // it renders no request and claims none.
+        const shared = sharedPayload(members);
+        const rendered = [];
+        if (stale !== null) {
+            // Nothing to render: no prompt goes out for a member here.
+        }
+        else if (shared === null) {
+            for (const [index, member] of members.entries()) {
+                const one = await this.sendPrompt(member, `REQUEST ${index + 1} OF ${members.length} — decide it on the digest below`, null);
+                rendered.push({ ...one.rendered, batchDeliveryId });
+            }
+        }
+        else {
+            const one = await this.sendPrompt(shared, `THE COMMAND ALL ${members.length} REQUESTS ARE ABOUT — decide it on the digest below`, null);
+            for (const member of members) {
+                rendered.push({
+                    ...one.rendered,
+                    action_key: member.action_key.value,
+                    batchDeliveryId,
+                });
+            }
+        }
+        const result = await this.call("sendMessage", {
+            chat_id: this.chatId,
+            text: drawn.text,
+            parse_mode: "HTML",
+            disable_web_page_preview: true,
+            ...(drawn.keyboard === null ? {} : { reply_markup: drawn.keyboard }),
+        });
+        const deliveryId = String(result.message_id);
+        state.deliveryId = deliveryId;
+        // Armed only now, and all at once: until the message with the buttons on it
+        // exists there is nothing a callback could legitimately answer.
+        for (const member of state.members) {
+            this.deliveries.set(member.nonce, {
+                actionKey: member.actionKey,
+                actionRef: actionRefOf(member.actionKey),
+                deliveryId,
+                batchDeliveryId,
+                deliveredAtMs,
+            });
+        }
+        this.digests.set(deliveryId, state);
+        this.allNonces.set(allNonce, deliveryId);
+        this.counters.notified += members.length;
+        return {
+            batchDeliveryId,
+            digestId: deliveryId,
+            members: state.members.map((member) => ({
+                action_key: member.actionKey,
+                delivery_id: deliveryId,
+            })),
+            rendered,
+        };
+    }
+    /**
+     * Send one request's messages: the computed header, the payload chunks, then
+     * the claimed block, with `keyboard` (when there is one) on the last.
+     *
+     * The claimed block goes last because it is the human-meaningful description
+     * of the act, and the message a reader answers on should be the one that says
+     * what they are answering about; bookkeeping above it is context, not the
+     * question. SPEC §10.3 allows claimed material to sit around the canonical
+     * block while it stays visibly separated and labelled, which the heading on
+     * every claimed message keeps. It is always sent, so a missing summary is a
+     * visible "(none given)" rather than an absent message, and so the keyboard
+     * has one message it can always ride on.
+     *
+     * Shared by the ordinary prompt and by a digest member, which differ in
+     * exactly two things: the heading, and whether anything is armed.
+     */
+    async sendPrompt(request, heading, keyboard) {
+        const rendering = renderTelegram(request, heading, this.layout);
+        const segments = [rendering.header];
+        if (rendering.payloadText !== null) {
+            const chunks = chunkForTelegram(rendering.payloadText);
+            for (const [index, chunk] of chunks.entries()) {
+                const label = chunks.length === 1
+                    ? `<b>${PAYLOAD_CHUNK_LABEL}</b>`
+                    : `<b>PAYLOAD ${index + 1}/${chunks.length} — ${PAYLOAD_CHUNK_LABEL_TAIL}</b>`;
+                segments.push(`${label}\n<pre>${escapeHtml(chunk)}</pre>`);
+            }
+        }
+        for (const [index, chunk] of chunkClaimedForTelegram(rendering.claimedText).entries()) {
+            segments.push(index === 0 ? chunk : `<b>${TELEGRAM_CLAIMED_CONTINUED_HEADING}</b>\n${chunk}`);
+        }
+        let deliveryId = "";
+        for (const [index, segment] of segments.entries()) {
+            const last = index === segments.length - 1;
+            const result = await this.call("sendMessage", {
+                chat_id: this.chatId,
+                text: segment,
+                parse_mode: "HTML",
+                disable_web_page_preview: true,
+                ...(last && keyboard !== null ? { reply_markup: keyboard } : {}),
+            });
+            if (last)
+                deliveryId = String(result.message_id);
+        }
+        const fields = rendering.lines.map((entry) => ({
+            field: entry.field,
+            kind: entry.kind,
+            text: entry.text,
+        }));
+        return {
+            deliveryId,
+            rendered: {
+                action_key: request.action_key.value,
+                fields,
+                fullPayloadText: rendering.payloadText,
+            },
+        };
+    }
+    async deliverOne(request, batchDeliveryId) {
+        const actionKey = request.action_key.value;
+        const nonce = this.makeNonce();
+        const keyboard = {
+            inline_keyboard: [
+                [
+                    { text: "✅ Approve", callback_data: callbackData("g", nonce, actionKey) },
+                    { text: "🛑 Reject", callback_data: callbackData("r", nonce, actionKey) },
+                ],
+            ],
+        };
+        const sent = await this.sendPrompt(request, TELEGRAM_PROMPT_HEADING, keyboard);
+        this.counters.notified += 1;
+        this.deliveries.set(nonce, {
+            actionKey,
+            actionRef: actionRefOf(actionKey),
+            deliveryId: sent.deliveryId,
+            deliveredAtMs: this.now(),
+            ...(batchDeliveryId === undefined ? {} : { batchDeliveryId }),
+        });
+        return {
+            deliveryId: sent.deliveryId,
+            rendered: {
+                ...sent.rendered,
+                ...(batchDeliveryId === undefined ? {} : { batchDeliveryId }),
+            },
+        };
+    }
+    /**
+     * Forget every nonce issued for `deliveryId`, and report the action key it
+     * was issued for.
+     *
+     * Called by {@link annotate} before the edit goes out, so a tap on a button
+     * the edit does not manage to remove resolves to nothing and is answered as
+     * a `stale-copy` rather than carried to the gate as a decision attempt.
+     * Forgetting is never the channel growing state, and forgetting a SETTLED
+     * request is what stops APRV-196's action-reference fallback from finding it:
+     * the ladder rescues a tap on an old copy of a request still open here, and
+     * a decided one is not that.
+     */
+    disarm(deliveryId) {
+        let actionKey = "";
+        // Deleting the current entry mid-iteration is defined behaviour for a Map,
+        // and every nonce for this message id goes — a re-notify of the same
+        // message would otherwise leave an older nonce still resolving.
+        for (const [nonce, delivery] of this.deliveries) {
+            if (delivery.deliveryId !== deliveryId)
+                continue;
+            actionKey = delivery.actionKey;
+            this.deliveries.delete(nonce);
+        }
+        const digest = this.digests.get(deliveryId);
+        if (digest !== undefined) {
+            this.allNonces.delete(digest.allNonce);
+            this.digests.delete(deliveryId);
+        }
+        return actionKey;
+    }
+    /**
+     * Drop the delivery bookkeeping no callback can still be honoured against
+     * (APRV-135).
+     *
+     * The condition is both halves of the sentence, evaluated per entry:
+     *
+     * 1. **Every member is terminal.** For a digest that means every member
+     *    carries a `settled` outcome; for a unit delivery it is automatic in the
+     *    other direction, since annotating a decided, expired or withdrawn
+     *    request already forgets its nonces ({@link disarm}), so a delivery still
+     *    in the map is one this process has not seen settled. A request past its
+     *    approval TTL is terminal too — the gate refuses every decision on it —
+     *    which is what lets an unannotated delivery be swept at all.
+     * 2. **Older than the retention window**, which is the policy's approval TTL
+     *    when it declares one and {@link TELEGRAM_DEFAULT_RETENTION_MS} when it
+     *    does not. Measured from the moment THIS process delivered the message,
+     *    which is at or after the `approval.requested` the TTL actually runs
+     *    from, so the window this sweep waits out is never shorter than the one
+     *    the gate enforces.
+     *
+     * Both together are what makes forgetting safe: a live button can never
+     * reference a dropped entry, because the state in which no callback can still
+     * be honoured is exactly the state in which the entry is dropped. A tap that
+     * arrives anyway is answered by the stale-callback path a restarted
+     * listener's buttons already take: `stale-copy` since APRV-196, counted,
+     * toasted with what the log says became of the request, never carried to the
+     * gate.
+     *
+     * Process memory only. No event, no message edit, no log read. `nowMs`
+     * defaults to the configured clock and is a parameter so a test can run a
+     * simulated week without one.
+     */
+    sweep(nowMs = this.now()) {
+        this.lastSweepMs = nowMs;
+        const retention = this.approvalTtlMs ?? TELEGRAM_DEFAULT_RETENTION_MS;
+        const expired = (deliveredAtMs) => nowMs - deliveredAtMs >= retention;
+        // Past the approval TTL the gate refuses every decision, so the request is
+        // terminal whether or not this process saw it settle. With no TTL declared
+        // nothing expires, and only an observed settlement makes an entry droppable.
+        const lapsed = (deliveredAtMs) => this.approvalTtlMs !== null && nowMs - deliveredAtMs >= this.approvalTtlMs;
+        let digests = 0;
+        for (const [deliveryId, digest] of this.digests) {
+            const terminal = digest.members.every((member) => member.settled !== null);
+            if (!(terminal || lapsed(digest.deliveredAtMs)) || !expired(digest.deliveredAtMs))
+                continue;
+            this.digests.delete(deliveryId);
+            this.allNonces.delete(digest.allNonce);
+            digests += 1;
+        }
+        let deliveries = 0;
+        for (const [nonce, delivery] of this.deliveries) {
+            // A nonce whose digest is still remembered is still armed on a message
+            // with buttons, whatever its own age says; the digest is the entry that
+            // decides, and it was just judged above.
+            if (this.digests.has(delivery.deliveryId))
+                continue;
+            if (!lapsed(delivery.deliveredAtMs) || !expired(delivery.deliveredAtMs))
+                continue;
+            this.deliveries.delete(nonce);
+            deliveries += 1;
+        }
+        // APRV-299. A review card is droppable on the same pair of conditions read
+        // for a thing that has no TTL: the runtime recorded an answer for it (so no
+        // button on it can still be honoured — the nonce is already gone) AND it is
+        // older than the retention window. An UNSETTLED card is never swept, and
+        // that is the safe direction: its sample stays open in the log whatever
+        // this map holds, so keeping the buttons alive costs a map entry and
+        // dropping them early would cost a human their thumb.
+        for (const [deliveryId, card] of this.reviewCards) {
+            if (card.settled === null || !expired(card.deliveredAtMs))
+                continue;
+            this.reviewCards.delete(deliveryId);
+            this.reviewNonces.delete(card.nonce);
+            if (card.awaitingNote !== null)
+                this.reviewNotePrompts.delete(card.awaitingNote.promptId);
+        }
+        return { deliveries, digests };
+    }
+    /** How many entries the bookkeeping holds. For tests and for operators. */
+    bookkeepingSize() {
+        return {
+            deliveries: this.deliveries.size,
+            digests: this.digests.size,
+            allNonces: this.allNonces.size,
+            reviewCards: this.reviewCards.size,
+        };
+    }
+    /**
+     * Mark one digest member settled and redraw the digest (APRV-115).
+     *
+     * The member's own nonce is forgotten first, so a tap on a button the redraw
+     * does not manage to remove resolves to nothing rather than reaching the
+     * gate. The other members keep theirs: a partially decided digest is a real
+     * state and the rest of it is still answerable.
+     */
+    async settleMember(digest, actionKey, outcome, detail) {
+        const member = digest.members.find((entry) => entry.actionKey === actionKey);
+        if (member === undefined || member.settled !== null)
+            return;
+        member.settled = { headline: outcome, detail };
+        this.deliveries.delete(member.nonce);
+        if (digest.members.every((entry) => entry.settled !== null)) {
+            this.allNonces.delete(digest.allNonce);
+        }
+        await this.redraw(digest);
+    }
+    /** One `editMessageText` that replaces a digest's text and its keyboard. */
+    async redraw(digest) {
+        const drawn = renderDigest(digest);
+        await this.call("editMessageText", {
+            chat_id: this.chatId,
+            message_id: Number(digest.deliveryId),
+            text: drawn.text,
+            parse_mode: "HTML",
+            disable_web_page_preview: true,
+            ...(drawn.keyboard === null ? {} : { reply_markup: drawn.keyboard }),
+        });
+    }
+    /**
+     * Edit a delivered message to say what became of its question, and remove the
+     * buttons (APRV-106 for withdrawal, generalized in APRV-113 to every terminal
+     * state).
+     *
+     * ONE `editMessageText` call, not two. Telegram's `editMessageText` replaces
+     * the reply markup along with the text, and omitting `reply_markup` clears
+     * it — so the annotation and the disarming land together, and there is no
+     * window in which the message reads "approved" and still offers a tap.
+     *
+     * The text is REPLACED rather than appended to, because this class does not
+     * remember what it sent (it remembers a nonce and a message id) and refetching
+     * a message to append to it would be the channel reconstructing state it is
+     * not supposed to hold. What the approver keeps is the outcome, the action key
+     * and the detail lines, which is what a chat transcript needs to stay readable.
+     *
+     * `outcome` is a headline word (see {@link TELEGRAM_TERMINAL_HEADLINES}) and
+     * `detail` the lines under it; both are HTML-escaped here, and neither may
+     * carry an execution token — no caller in this repository has one to give,
+     * since {@link DecisionOutcome} deliberately does not carry it.
+     *
+     * Best effort: {@link TelegramApiError} propagates to the caller, which logs
+     * it and carries on. A message that could not be edited is a cosmetic
+     * problem — the log has already settled the request, so a tap on the stale
+     * buttons is refused by the gate and answered with the refusal toast.
+     */
+    async annotate(deliveryId, outcome, detail, 
+    /**
+     * Which request this settles, when `deliveryId` names a digest (APRV-115).
+     * A digest holds several, so an annotation without one can only mean the
+     * whole delivery is over — which is handled by falling through to the
+     * message-replacing path below, buttons and all.
+     */
+    actionKey) {
+        const digest = this.digests.get(deliveryId);
+        if (digest !== undefined && actionKey !== undefined) {
+            await this.settleMember(digest, actionKey, outcome, detail);
+            return;
+        }
+        const settledKey = this.disarm(deliveryId);
+        const text = [
+            `<b>${escapeHtml(outcome)}</b>`,
+            `<code>${escapeHtml(actionKey ?? settledKey)}</code>`,
+            "",
+            ...detail.map((entry) => escapeHtml(entry)),
+        ].join("\n");
+        await this.call("editMessageText", {
+            chat_id: this.chatId,
+            message_id: Number(deliveryId),
+            text,
+            parse_mode: "HTML",
+            disable_web_page_preview: true,
+        });
+    }
+    /**
+     * The withdrawal case of {@link annotate} (APRV-106), and the one the
+     * {@link Channel} interface names. Its wording is unchanged.
+     */
+    async retract(deliveryId, reason, actionKey) {
+        await this.annotate(deliveryId, TELEGRAM_TERMINAL_HEADLINES.withdrawn, [reason], actionKey);
+    }
+    /**
+     * Send one plain message that carries no question (APRV-196).
+     *
+     * Used for the re-delivery banner the listener puts in front of a startup
+     * batch. It arms nothing, remembers nothing, and names no action key: a
+     * banner is a sentence about the messages that follow, and a reader who
+     * mistook it for a request would be a reader the banner had made worse off.
+     * `lines` are escaped here, exactly as everything else interpolated into an
+     * HTML-mode message is.
+     */
+    async announce(lines) {
+        const result = await this.call("sendMessage", {
+            chat_id: this.chatId,
+            text: lines
+                .map((entry, index) => index === 0 ? `<b>${escapeHtml(entry)}</b>` : escapeHtml(entry))
+                .join("\n"),
+            parse_mode: "HTML",
+            disable_web_page_preview: true,
+        });
+        return String(result.message_id);
+    }
+    // -------------------------------------------------------------------------
+    // Long polling
+    // -------------------------------------------------------------------------
+    /**
+     * Long-poll `getUpdates` until {@link stop} is called (or one batch, with
+     * `once`).
+     *
+     * **The loop survives the network.** A poll that times out, is refused, drops
+     * its socket, returns a 5xx, or answers with something that is not JSON is
+     * counted, complained about on stderr, and retried after a doubling backoff.
+     * There is no failure mode in which the listener quietly stops listening: the
+     * whole value of a push channel is that a human's inbox keeps receiving, and
+     * a listener that died at 3am on a transient 502 would fail exactly when the
+     * queue was filling up.
+     *
+     * Each iteration begins with {@link TelegramListenOptions.beforePoll} when
+     * one is supplied, which is where the runtime's dispatch cycle runs: the
+     * loop is therefore "deliver anything newly pending, then wait for a
+     * decision", not "deliver once at startup, then wait forever".
+     */
+    async listen(options = {}) {
+        this.stopped = false;
+        let backoff = this.backoffMs;
+        while (!this.stopped) {
+            try {
+                if (options.beforePoll !== undefined) {
+                    await options.beforePoll();
+                    if (this.stopped)
+                        return;
+                }
+                await this.pollOnce();
+                backoff = this.backoffMs;
+                if (options.once === true)
+                    return;
+            }
+            catch (cause) {
+                if (this.stopped)
+                    return;
+                this.counters.pollErrors += 1;
+                this.complain(`approval: telegram getUpdates failed (${this.describe(cause)}); retrying in ${backoff}ms — the listener is still up`);
+                await sleep(backoff);
+                backoff = Math.min(backoff * 2, this.maxBackoffMs);
+            }
+        }
+    }
+    /** Stop the loop and abort any in-flight request. */
+    stop() {
+        this.stopped = true;
+        this.inFlight?.abort();
+    }
+    /**
+     * One `getUpdates` batch, processed. Throws on a transport failure — which is
+     * what {@link listen} catches and retries.
+     */
+    async pollOnce() {
+        // APRV-135. Before the long poll, not after: this is where the loop is
+        // about to block for up to `pollTimeoutSeconds`, and a sweep that ran after
+        // the block would be a sweep that never runs on a quiet chat. Rate-limited
+        // so a driver calling `pollOnce` in a tight loop does not spend its time
+        // walking two maps.
+        const nowMs = this.now();
+        if (nowMs - this.lastSweepMs >= TELEGRAM_SWEEP_INTERVAL_MS)
+            this.sweep(nowMs);
+        const updates = await this.call("getUpdates", {
+            offset: this.offset,
+            timeout: this.pollTimeoutSeconds,
+            // APRV-216. `message` is asked for only while a command handler is
+            // registered: see {@link onCommand} for why a listener that reads
+            // messages nobody asked for would break `approval setup channel
+            // telegram`'s chat discovery.
+            // APRV-299 adds the second reason to read messages: a `loved` or
+            // `disliked` on a review card collects the human's words as a REPLY,
+            // because an inline keyboard has no text input.
+            allowed_updates: this.commandHandler === null && this.reviewHandler === null
+                ? ["callback_query"]
+                : ["callback_query", "message"],
+        }, this.requestTimeoutMs ?? (this.pollTimeoutSeconds + 10) * 1000);
+        const result = {
+            updates: 0,
+            outcomes: [],
+            ignored: [],
+            commands: [],
+            reviews: [],
+        };
+        for (const raw of updates) {
+            const update = (raw ?? {});
+            const id = update["update_id"];
+            if (typeof id === "number")
+                this.offset = Math.max(this.offset, id + 1);
+            this.counters.updates += 1;
+            result.updates += 1;
+            await this.handleUpdate(update, result);
+        }
+        return result;
+    }
+    /**
+     * Exactly one `answerCallbackQuery` per callback query, on every path
+     * (APRV-196).
+     *
+     * The incident this closes: a tap that reached no branch with a toast on it
+     * spun on the approver's phone until Telegram gave up, and the human — with
+     * no way to tell a swallowed tap from a slow one — tapped again. So the ack
+     * is a property of the WRAPPER rather than of each branch: every route below
+     * still writes its own, better sentence, and anything that fails to (a throw
+     * halfway through, a branch a later change forgets) is caught here and
+     * answered with {@link TELEGRAM_ACK_FALLBACK}.
+     *
+     * A thrown handler is answered and swallowed rather than propagated, and that
+     * is deliberate: `pollOnce` throwing puts `listen` into its backoff, so one
+     * malformed update would cost the whole batch and the poll after it. Nothing
+     * is lost by continuing — the gate has already appended whatever it appended,
+     * and the log is what says so.
+     *
+     * APRV-206 moved WHEN that one answer is sent on the decision path: it now
+     * goes out before the gate runs, so the spinner on the phone is one Bot API
+     * call long instead of one decision long. The guarantee is unchanged and is
+     * now enforced in one place — {@link safeAnswer} answers a query at most once,
+     * so the fallback below cannot follow an early ack with a second call.
+     */
+    async handleUpdate(update, result) {
+        const callback = update["callback_query"];
+        if (typeof callback !== "object" || callback === null) {
+            // APRV-216. Swallowed for the same reason a thrown decision handler is:
+            // letting it out would reach `pollOnce`, and a listener that dropped into
+            // backoff because one command failed would be a listener that stopped
+            // listening over something that wrote nothing.
+            try {
+                await this.handleMessage(update, result);
+            }
+            catch (cause) {
+                this.complain(`approval: telegram failed while handling a command: ${this.describe(cause)} — nothing was appended and the listener is still up`);
+            }
+            return;
+        }
+        const query = callback;
+        const callbackId = typeof query["id"] === "string" ? query["id"] : "";
+        this.ack = { id: callbackId, answered: false };
+        try {
+            await this.routeCallback(query, callbackId, result);
+        }
+        catch (cause) {
+            this.complain(`approval: telegram failed while handling a callback: ${this.describe(cause)} — the tap is answered; whatever the gate appended stands`);
+            await this.safeAnswer(callbackId, TELEGRAM_ACK_FALLBACK);
+        }
+        finally {
+            const pending = this.ack;
+            this.ack = null;
+            if (pending !== null && !pending.answered) {
+                await this.safeAnswer(callbackId, TELEGRAM_ACK_FALLBACK);
+            }
+        }
+    }
+    /**
+     * A `message` update: the bot-command path (APRV-216).
+     *
+     * Three rules, in this order, and each of them is a refusal to act on
+     * something the network said:
+     *
+     * 1. **No handler, no reading.** A channel with no command handler wants no
+     *    message updates and did not ask for any; one that arrives anyway (a
+     *    webhook backlog, a poll issued before the handler was registered) is
+     *    dropped without a counter, because there is nothing wrong with it.
+     * 2. **The configured chat only.** A message from anywhere else is counted
+     *    `foreign-chat` and answered with nothing at all. Not even a refusal
+     *    reply: a stranger who can reach the bot learns from silence that the
+     *    bot is there, and learns from a reply what it is for.
+     * 3. **A closed vocabulary.** `/queue`, `/skip`, `/next`. Anything else
+     *    beginning with `/` is counted `unknown-command`; anything not beginning
+     *    with `/` is ordinary chat and is ignored silently.
+     *
+     * A command decides nothing and appends nothing — it cannot, because it
+     * never reaches {@link handler}. The handler it does reach reorders what the
+     * runtime shows next, which is process memory on the runtime's side of the
+     * boundary (SPEC.md §10.3).
+     */
+    async handleMessage(update, result) {
+        const handler = this.commandHandler;
+        if (handler === null && this.reviewHandler === null)
+            return;
+        const raw = update["message"];
+        if (typeof raw !== "object" || raw === null)
+            return;
+        const message = raw;
+        const text = message["text"];
+        if (typeof text !== "string")
+            return;
+        // APRV-299, before the command vocabulary: a reply to an outstanding note
+        // prompt is the human's own words, and it is bound to its card by the
+        // message id THIS process issued, never by anything the reply asserts about
+        // itself. A reply naming a prompt this process is not holding falls through
+        // and is ordinary chat.
+        if (await this.handleNoteReply(message, text, result))
+            return;
+        if (handler === null || !text.trim().startsWith("/"))
+            return;
+        const chat = (message["chat"] ?? {});
+        const chatId = chat["id"] === undefined ? "" : String(chat["id"]);
+        if (chatId !== this.chatId) {
+            this.counters.anomalies["foreign-chat"] += 1;
+            result.ignored.push({
+                kind: "foreign-chat",
+                detail: `command from chat ${JSON.stringify(chatId)}, which is not the configured approver chat`,
+            });
+            this.complain(`approval: telegram ignored a command (foreign-chat): from chat ${JSON.stringify(chatId)}, which is not the configured approver chat`);
+            return;
+        }
+        const command = parseBotCommand(text);
+        if (command === null) {
+            this.counters.anomalies["unknown-command"] += 1;
+            result.ignored.push({ kind: "unknown-command", detail: this.redact(text.trim()) });
+            return;
+        }
+        this.counters.commands += 1;
+        result.commands.push(command);
+        // A throw here is caught by `handleUpdate`, which complains and carries on:
+        // a command that failed must not cost the batch or the poll after it, and
+        // there is nothing to undo, because a command writes nothing.
+        await handler(command);
+    }
+    async routeCallback(query, callbackId, result) {
+        const message = (query["message"] ?? {});
+        const chat = (message["chat"] ?? {});
+        const chatId = chat["id"] === undefined ? "" : String(chat["id"]);
+        // (a) Not our chat. Counted, answered, never decided, never logged.
+        if (chatId !== this.chatId) {
+            await this.ignore(result, callbackId, "foreign-chat", `callback from chat ${JSON.stringify(chatId)}, which is not the configured approver chat`, "This bot only accepts decisions from its configured approval chat.");
+            return;
+        }
+        // APRV-257, before the decision vocabulary and in a parser of its own. A
+        // checkpoint button decides no request, so it must never reach the ladder
+        // below — where an unresolved nonce falls back to an action reference, and
+        // a signature gesture would start looking for something to approve.
+        const checkpoint = parseCheckpointCallback(query["data"]);
+        if (checkpoint !== null) {
+            await this.handleCheckpointTap(checkpoint, callbackId, result);
+            return;
+        }
+        // APRV-299, before the decision vocabulary and in a parser of its own, for
+        // the same reason the checkpoint one is: a review button decides no request
+        // and must never reach the ladder below, where an unresolved nonce falls
+        // back to an action reference and a gesture about something that already
+        // happened would start looking for something to approve.
+        const review = parseReviewCallback(query["data"]);
+        if (review !== null) {
+            await this.handleReviewTap(review, callbackId, result);
+            return;
+        }
+        const parsed = parseCallbackData(query["data"]);
+        if (parsed === null) {
+            await this.ignore(result, callbackId, "malformed-callback", `callback_data ${JSON.stringify(query["data"])} is not a decision this channel issued`, "Unrecognized button.");
+            return;
+        }
+        // APRV-115. An "all" button names a digest, not a request: the set it
+        // decides is whatever is still open on that delivery right now, which this
+        // process knows and the callback bytes deliberately do not say.
+        if (parsed.scope === "all") {
+            await this.handleDigestAll(parsed.decision, parsed.nonce, callbackId, result);
+            return;
+        }
+        // The resolution ladder (APRV-196). A tap is answered by the nonce when
+        // this process issued it, by the action reference when it did not, and by
+        // the log when neither is holding the action open.
+        let delivery = this.deliveries.get(parsed.nonce);
+        let viaStaleCopy = false;
+        if (delivery === undefined && parsed.actionRef !== null) {
+            // The pre-restart copy. Its nonce died with the process that issued it,
+            // but the request it names is one THIS process has since re-delivered, so
+            // the tap decides that request — on the live copy's message, which is
+            // where the annotation belongs. The bytes select among what this listener
+            // has itself put in this chat and can name nothing else; the gate then
+            // does everything it does for any other tap.
+            delivery = this.liveDeliveryFor(parsed.actionRef);
+            viaStaleCopy = delivery !== undefined;
+        }
+        if (delivery === undefined) {
+            if (parsed.actionRef !== null) {
+                // Nothing open here for that action. Say what the log says, which is
+                // the only thing that knows: decided, lapsed, withdrawn, or unknown.
+                const described = this.describeAction?.(parsed.actionRef) ?? null;
+                await this.ignore(result, callbackId, "stale-copy", `no open delivery for action ref ${JSON.stringify(parsed.actionRef)} (an earlier copy of a request this listener is not holding open)`, described ?? TELEGRAM_STALE_UNKNOWN);
+                return;
+            }
+            await this.ignore(result, callbackId, "unknown-callback", `no delivery for nonce ${JSON.stringify(parsed.nonce)} (a restarted listener forgets its buttons; the pending queue is re-sent on start)`, 
+            // Two ways to get here, and the reply has to serve both: a button this
+            // process never issued (a restart forgot it), and a button on a message
+            // this process has already annotated (APRV-113 forgets the nonce with
+            // the edit). Either way the message text is the thing to read.
+            "This button is no longer live — read the message for the outcome, or the newest message for the request.");
+            return;
+        }
+        if (!viaStaleCopy && parsed.actionRef !== null && parsed.actionRef !== delivery.actionRef) {
+            await this.ignore(result, callbackId, "key-mismatch", `callback references ${JSON.stringify(parsed.actionRef)} but the nonce was issued for ${JSON.stringify(delivery.actionKey)}`, "That button does not match a delivered request.");
+            return;
+        }
+        const decision = {
+            action_key: delivery.actionKey,
+            decision: parsed.decision,
+            deliveryId: delivery.deliveryId,
+            ...(delivery.batchDeliveryId === undefined
+                ? {}
+                : { batchDeliveryId: delivery.batchDeliveryId }),
+            ...(parsed.decision === "reject"
+                ? { note: `${TELEGRAM_REJECT_NOTE} (callback ${callbackId})` }
+                : {}),
+        };
+        if (this.handler === null) {
+            await this.ignore(result, callbackId, "unknown-callback", "a callback arrived before the runtime registered a decision handler", "The runtime is not ready to record decisions.");
+            return;
+        }
+        // APRV-206. The ack goes out BEFORE the gate runs, and it is the only
+        // answer this query will get. Everything below — reading the verified log,
+        // re-checking the budgets, appending under the lock — used to happen while
+        // the button spun, so the spinner's length was the log's length. It claims
+        // no decision (see {@link TELEGRAM_ACK_HEARD}): at this instant nothing has
+        // been appended, and the annotation below is what says what the log holds.
+        await this.safeAnswer(callbackId, `${viaStaleCopy ? TELEGRAM_STALE_COPY_PREFIX : ""}${TELEGRAM_ACK_HEARD}`);
+        // APRV-206. A handler that throws is the one case the early ack cannot be
+        // taken back: the human has been told their tap arrived, and the toast that
+        // used to say "this listener could not finish reading your tap" is spent. So
+        // the message says it instead, and the throw still reaches `handleUpdate`,
+        // which complains and keeps the poll loop alive exactly as before.
+        let outcome;
+        try {
+            outcome = this.handler(decision);
+        }
+        catch (cause) {
+            await this.annotateQuietly(delivery.deliveryId, delivery.actionKey, TELEGRAM_NOT_RECORDED, [
+                TELEGRAM_HANDLER_FAILED,
+            ]);
+            throw cause;
+        }
+        this.counters.decisions += 1;
+        if (viaStaleCopy) {
+            this.counters.staleCopyDecisions += 1;
+            this.complain(`approval: telegram resolved a tap on an earlier copy of ${delivery.actionKey} to the live delivery (message ${delivery.deliveryId})`);
+        }
+        result.outcomes.push({ action_key: delivery.actionKey, outcome });
+        // APRV-113, and since APRV-206 the ONLY place the outcome is stated. The
+        // tap is visible in the transcript rather than in a toast that vanishes,
+        // and the words come from the record the gate actually appended.
+        //
+        // Best effort in the same sense `retract` is — a failed edit is complained
+        // about and dropped, because the decision is already in the log and nothing
+        // about it depends on a chat message being redrawn.
+        if (!outcome.ok) {
+            // APRV-206. A refusal used to be a toast; the single answer is now spent
+            // on the ack, so it is said here or nowhere. `annotate` disarms the
+            // message, which is right in both directions: a terminal request has no
+            // decision left to collect, and a still-pending one is re-delivered as a
+            // fresh prompt by the next dispatch cycle.
+            await this.annotateQuietly(delivery.deliveryId, delivery.actionKey, TELEGRAM_NOT_RECORDED, [
+                this.answerFor(outcome),
+            ]);
+            return;
+        }
+        const record = outcome.record;
+        const headline = outcome.decision === "grant"
+            ? TELEGRAM_TERMINAL_HEADLINES.granted
+            : TELEGRAM_TERMINAL_HEADLINES.rejected;
+        try {
+            await this.annotate(delivery.deliveryId, headline, [decidedLine(record.actor, record.ts, record.seq)], delivery.actionKey);
+        }
+        catch (cause) {
+            // APRV-277: the one failure that is not one. See isMessageNotModified.
+            if (isMessageNotModified(cause))
+                return;
+            this.complain(`approval: telegram could not annotate the decided ${delivery.actionKey} (message ${delivery.deliveryId}): ${this.describe(cause)} — the decision is recorded; only the message is stale`);
+        }
+    }
+    /**
+     * One tap over every still-open member of a digest (APRV-115).
+     *
+     * **N decisions, never one.** Each member is turned into its own
+     * {@link ChannelDecision} — its own action key, its own payload binding — and
+     * handed to the runtime's handler on its own, which records it through the
+     * gate's compare-and-append on its own. There is no code path here that could
+     * produce a single event covering two actions, because there is no call here
+     * that writes anything at all.
+     *
+     * A member that refuses (already decided elsewhere, expired, withdrawn) does
+     * not stop the rest, for the reason `channels/batch.ts` sets out: abandoning
+     * four answers because the fifth had lapsed would discard a human's decision,
+     * and un-appending the ones already written is not a thing the log permits.
+     * The toast says how many landed and how many did not.
+     *
+     * The digest is redrawn ONCE at the end rather than per member: N edits of
+     * the same message would show the approver their own decisions arriving one
+     * at a time, and would spend N Bot API calls to end in the same place.
+     */
+    async handleDigestAll(decision, nonce, callbackId, result) {
+        const deliveryId = this.allNonces.get(nonce);
+        const digest = deliveryId === undefined ? undefined : this.digests.get(deliveryId);
+        if (digest === undefined) {
+            await this.ignore(result, callbackId, "unknown-callback", `no digest for nonce ${JSON.stringify(nonce)} (a restarted listener forgets its buttons; the pending queue is re-sent on start)`, "This button is no longer live — read the message for the outcome, or the newest message for the requests.");
+            return;
+        }
+        if (this.handler === null) {
+            await this.ignore(result, callbackId, "unknown-callback", "a callback arrived before the runtime registered a decision handler", "The runtime is not ready to record decisions.");
+            return;
+        }
+        // APRV-206, and this path needs it most: an "all" tap runs one gate
+        // decision per open member, so its old post-hoc toast made the spinner N
+        // decisions long. The redraw below is what says how each member ended.
+        await this.safeAnswer(callbackId, TELEGRAM_ACK_HEARD);
+        const open = digest.members.filter((member) => member.settled === null);
+        let landed = 0;
+        const refusals = [];
+        for (const member of open) {
+            const one = {
+                action_key: member.actionKey,
+                decision,
+                deliveryId: digest.deliveryId,
+                batchDeliveryId: digest.batchDeliveryId,
+                ...(decision === "reject"
+                    ? { note: `${TELEGRAM_REJECT_NOTE} (callback ${callbackId}, all)` }
+                    : {}),
+            };
+            const outcome = this.handler(one);
+            this.counters.decisions += 1;
+            result.outcomes.push({ action_key: member.actionKey, outcome });
+            if (!outcome.ok) {
+                refusals.push(outcome.code);
+                continue;
+            }
+            landed += 1;
+            // Bookkeeping only: the words come from the record the gate appended.
+            member.settled = {
+                headline: outcome.decision === "grant"
+                    ? TELEGRAM_TERMINAL_HEADLINES.granted
+                    : TELEGRAM_TERMINAL_HEADLINES.rejected,
+                detail: [decidedLine(outcome.record.actor, outcome.record.ts, outcome.record.seq)],
+            };
+            this.deliveries.delete(member.nonce);
+        }
+        if (digest.members.every((member) => member.settled !== null)) {
+            this.allNonces.delete(digest.allNonce);
+        }
+        const word = decision === "grant" ? "Approved" : "Rejected";
+        const summary = refusals.length === 0
+            ? `${word} ${landed} — one log event each.`
+            : `${word} ${landed}; ${refusals.length} refused (${[...new Set(refusals)].join(", ")}). Nothing was recorded for those.`;
+        // APRV-206: the summary is no longer a toast (the tap's one answer was
+        // spent acknowledging it). The approver reads the outcome off the redrawn
+        // digest, member by member, and the operator gets the tally here.
+        this.complain(`approval: telegram digest ${digest.deliveryId}: ${summary}`);
+        try {
+            await this.redraw(digest);
+        }
+        catch (cause) {
+            // APRV-277: the one failure that is not one. See isMessageNotModified.
+            if (isMessageNotModified(cause))
+                return;
+            this.complain(`approval: telegram could not redraw the digest (message ${digest.deliveryId}): ${this.describe(cause)} — the decisions are recorded; only the message is stale`);
+        }
+    }
+    /**
+     * {@link annotate}, with a failed edit complained about rather than thrown
+     * (APRV-206).
+     *
+     * Every caller on the decision path wants the same thing from a failed edit:
+     * say so on the operator's terminal and carry on, because whatever the gate
+     * did or did not append has already happened and no chat message changes it.
+     *
+     * The exception is {@link isMessageNotModified}, which says the message
+     * already reads the way this call wanted it to read (APRV-277). Nothing is
+     * printed for it: there is no staleness to warn about.
+     */
+    async annotateQuietly(deliveryId, actionKey, headline, detail) {
+        try {
+            await this.annotate(deliveryId, headline, detail, actionKey);
+        }
+        catch (cause) {
+            // APRV-277: the one failure that is not one. See isMessageNotModified.
+            if (isMessageNotModified(cause))
+                return;
+            this.complain(`approval: telegram could not annotate ${actionKey} (message ${deliveryId}): ${this.describe(cause)} — the log is what it is; only the message is stale`);
+        }
+    }
+    /**
+     * What a refused tap is told, in the message edit (APRV-206; it was the toast
+     * until the single answer moved to the early ack).
+     *
+     * The duplicate case is the one worth naming: a second tap on a request the
+     * gate has already decided produces `already-decided`, no second event, and
+     * this text. Telegram redelivers callbacks on its own, so this path is
+     * ordinary traffic, not an error.
+     *
+     * The sentences themselves moved to `channels/contract.ts` in APRV-235, so
+     * that this message edit and the line the terminal channel prints are the
+     * same words and cannot drift apart: a human who taps on their phone and
+     * then reads the operator's terminal should not have to decide which of two
+     * wordings to believe. The edit puts {@link TELEGRAM_NOT_RECORDED} above it
+     * and clears the buttons, in `annotate`'s single call.
+     */
+    answerFor(outcome) {
+        return refusedDecisionLine(outcome.code);
+    }
+    /**
+     * A tap on `Sign` or `Not now` (APRV-257).
+     *
+     * The nonce is authoritative and there is no fallback ladder underneath it:
+     * a checkpoint names no request, so there is no action reference to rescue a
+     * stale copy with, and a tap this process cannot resolve is answered as
+     * `unknown-callback` rather than guessed at. The cost is one dead button
+     * after a restart, and the listener offers again on its next lapse.
+     *
+     * The nonce is consumed BEFORE the handler runs, so a double tap cannot
+     * produce two records: the second tap finds nothing and says so. Even if it
+     * did, `appendCheckpointAt` is a compare-and-append and the log would carry
+     * two honest checkpoints over the same head, which is harmless — but a human
+     * who taps twice should be told what happened rather than shown two
+     * successes.
+     *
+     * The ack goes out FIRST (APRV-206's rule), because signing reads a vault
+     * and appends to a log, and a spinner that lasted a decision long is what
+     * that task removed.
+     */
+    async handleCheckpointTap(tap, callbackId, result) {
+        const held = this.checkpointNonces.get(tap.nonce);
+        if (held === undefined) {
+            await this.ignore(result, callbackId, "unknown-callback", `checkpoint nonce ${JSON.stringify(tap.nonce)} was not issued by this process`, "This checkpoint prompt is from an earlier run. A fresh one is offered when the next is due.");
+            return;
+        }
+        this.checkpointNonces.delete(tap.nonce);
+        const handler = this.checkpointHandler;
+        if (handler === null) {
+            await this.ignore(result, callbackId, "unknown-callback", "a checkpoint tap arrived with no handler registered", TELEGRAM_ACK_FALLBACK);
+            return;
+        }
+        await this.safeAnswer(callbackId, tap.sign ? "Heard — signing. The message will say what the log recorded." : "Not now.");
+        const response = await handler({ sign: tap.sign, head: held.head });
+        // Edited here rather than through `annotate`, which renders an action key
+        // under its headline. A checkpoint has none, and an empty `<code></code>`
+        // where a request's key belongs would be this channel implying a request.
+        // Sending no `reply_markup` is what takes the buttons away.
+        await this.call("editMessageText", {
+            chat_id: this.chatId,
+            message_id: Number(held.deliveryId),
+            text: [
+                `<b>${escapeHtml(response.headline)}</b>`,
+                "",
+                ...response.detail.map((entry) => escapeHtml(entry)),
+            ].join("\n"),
+            parse_mode: "HTML",
+            disable_web_page_preview: true,
+        });
+    }
+    /**
+     * A tap on one of a review card's six buttons (APRV-299).
+     *
+     * The nonce is authoritative and there is no fallback ladder underneath it,
+     * for the reason {@link reviewCallbackData} gives: a review is never urgent,
+     * a card this process is not holding leaves its sample open, and the next
+     * cycle offers a fresh one. An unresolvable tap is answered
+     * `unknown-callback` rather than guessed at.
+     *
+     * Which combinations are legal is decided by `core/audit.ts` and by nothing
+     * here. A denied review that says the human loved the work is refused by
+     * `reviewSample` before it reads the log, with the code SPEC.md §11.2 names,
+     * and this method's job is to put that pair in front of it rather than to
+     * re-implement the rule. The one thing this method owns is the ARMING, which
+     * is process memory that appends nothing.
+     */
+    async handleReviewTap(tap, callbackId, result) {
+        const deliveryId = this.reviewNonces.get(tap.nonce);
+        const state = deliveryId === undefined ? undefined : this.reviewCards.get(deliveryId);
+        if (state === undefined || state.settled !== null) {
+            await this.ignore(result, callbackId, "unknown-callback", `no open review card for nonce ${JSON.stringify(tap.nonce)} (a restarted listener forgets its buttons; the sample stays open and is offered again)`, "This review card is no longer live — the sample is still open, and a fresh card is sent on a later cycle. `approval audit review` names it from a terminal.");
+            return;
+        }
+        if (this.reviewHandler === null) {
+            await this.ignore(result, callbackId, "unknown-callback", "a review tap arrived before the runtime registered a review handler", "The runtime is not ready to record reviews.");
+            return;
+        }
+        // The first Deny tap arms and writes nothing. Stated on the card, so the
+        // approver reads the state rather than inferring it from a toast.
+        if (tap.choice === "deny" && !state.denyArmed) {
+            state.denyArmed = true;
+            state.notice = null;
+            await this.safeAnswer(callbackId, TELEGRAM_REVIEW_ARM_TOAST);
+            await this.redrawReview(state);
+            return;
+        }
+        const verdict = state.denyArmed ? "denied" : "ok";
+        if (tap.choice === "ok" || tap.choice === "deny") {
+            // `ok` with deny armed is a correction, and it disarms: a human who
+            // reached for Deny and then chose OK meant OK, and nothing was written in
+            // between for the change of mind to contradict.
+            const chosen = tap.choice === "deny" ? "denied" : "ok";
+            state.denyArmed = chosen === "denied";
+            await this.safeAnswer(callbackId, TELEGRAM_REVIEW_ACK);
+            await this.recordReview(state, { sampleSeq: state.card.sampleSeq, verdict: chosen }, result);
+            return;
+        }
+        const reaction = tap.choice;
+        // The two grades that require the human's own words ask for them FIRST, and
+        // nothing is appended until the reply arrives. The exception is the pair
+        // `core/audit.ts` refuses outright: a denied review that says liked or
+        // loved is answered with `reaction-conflicts-verdict` before any log is
+        // read, so asking for a note to go with it would collect words for a record
+        // that was never going to exist.
+        const conflicts = verdict === "denied" && (reaction === "liked" || reaction === "loved");
+        if (!conflicts && (reaction === "loved" || reaction === "disliked")) {
+            await this.safeAnswer(callbackId, TELEGRAM_REVIEW_NOTE_TOAST);
+            await this.askForNote(state, verdict, reaction);
+            return;
+        }
+        await this.safeAnswer(callbackId, TELEGRAM_REVIEW_ACK);
+        await this.recordReview(state, { sampleSeq: state.card.sampleSeq, verdict, reaction }, result);
+    }
+    /**
+     * Send the ForceReply prompt a `loved` or `disliked` needs, and remember what
+     * its reply will record (APRV-299).
+     *
+     * The pending grade lives HERE and not in the reply's own text, exactly as a
+     * checkpoint's head lives in this process rather than in the callback bytes:
+     * what gets recorded is what this process put on the screen. Losing the map
+     * to a restart costs the reply its meaning — nothing is appended, the sample
+     * stays open, and a fresh card is offered — and can never cost a record
+     * nobody asked for.
+     *
+     * A second prompt replaces the first: only one grade can be outstanding on
+     * one card, and the older prompt stops resolving so a late reply to it lands
+     * nowhere rather than recording a grade the human moved on from.
+     */
+    async askForNote(state, verdict, reaction) {
+        if (state.awaitingNote !== null)
+            this.reviewNotePrompts.delete(state.awaitingNote.promptId);
+        const lines = reviewNotePromptLines(reaction, verdict, state.card.fields.action_key.value);
+        const sent = await this.call("sendMessage", {
+            chat_id: this.chatId,
+            text: lines
+                .map((entry, index) => (index === 0 ? `<b>${escapeHtml(entry)}</b>` : escapeHtml(entry)))
+                .join("\n"),
+            parse_mode: "HTML",
+            disable_web_page_preview: true,
+            reply_markup: { force_reply: true },
+        });
+        const promptId = String(sent.message_id);
+        state.awaitingNote = { promptId, verdict, reaction };
+        this.reviewNotePrompts.set(promptId, state.deliveryId);
+    }
+    /**
+     * A message replying to an outstanding note prompt (APRV-299).
+     *
+     * Returns `true` when this update was a note reply and has been dealt with,
+     * so the command path below never sees it. Three refusals to act on something
+     * the network said, in order: a reply naming no prompt this process issued is
+     * not ours, a reply from another chat is counted `foreign-chat` and answered
+     * with nothing at all, and the words themselves are passed to the runtime
+     * verbatim — a blank one included, because whether blank is a note is
+     * `core/audit.ts`'s rule and not this channel's.
+     */
+    async handleNoteReply(message, text, result) {
+        const replyTo = message["reply_to_message"];
+        if (typeof replyTo !== "object" || replyTo === null)
+            return false;
+        const promptId = String(replyTo["message_id"] ?? "");
+        const deliveryId = this.reviewNotePrompts.get(promptId);
+        if (deliveryId === undefined)
+            return false;
+        const chat = (message["chat"] ?? {});
+        const chatId = chat["id"] === undefined ? "" : String(chat["id"]);
+        if (chatId !== this.chatId) {
+            this.counters.anomalies["foreign-chat"] += 1;
+            result.ignored.push({
+                kind: "foreign-chat",
+                detail: `note reply from chat ${JSON.stringify(chatId)}, which is not the configured approver chat`,
+            });
+            this.complain(`approval: telegram ignored a review note (foreign-chat): from chat ${JSON.stringify(chatId)}, which is not the configured approver chat`);
+            return true;
+        }
+        const state = this.reviewCards.get(deliveryId);
+        const pending = state?.awaitingNote ?? null;
+        this.reviewNotePrompts.delete(promptId);
+        if (state === undefined || pending === null || pending.promptId !== promptId)
+            return true;
+        state.awaitingNote = null;
+        await this.recordReview(state, {
+            sampleSeq: state.card.sampleSeq,
+            verdict: pending.verdict,
+            reaction: pending.reaction,
+            note: text,
+        }, result);
+        return true;
+    }
+    /**
+     * Hand one review tap to the runtime and redraw the card from its answer
+     * (APRV-299).
+     *
+     * A recorded review settles the card and forgets its nonce, so a tap on a
+     * button the edit does not manage to remove resolves to nothing rather than
+     * recording a second human observation of one item. A REFUSAL does neither:
+     * nothing was appended, the sample is still open, and the codes that get here
+     * are ones the reviewer can act on — `reaction-conflicts-verdict` asks them
+     * to say which half they meant, and `note-required` asks for words — so the
+     * buttons stay, with the refusal rendered above them and the arming intact.
+     */
+    async recordReview(state, tap, result) {
+        const handler = this.reviewHandler;
+        if (handler === null)
+            return;
+        let response;
+        try {
+            response = await handler(tap);
+        }
+        catch (cause) {
+            state.notice = { headline: TELEGRAM_NOT_RECORDED, lines: [TELEGRAM_HANDLER_FAILED] };
+            await this.redrawReview(state);
+            throw cause;
+        }
+        this.counters.reviews += 1;
+        result.reviews.push({ tap, ok: response.ok });
+        if (response.ok) {
+            state.settled = { headline: response.headline, detail: response.detail };
+            state.notice = null;
+            state.denyArmed = false;
+            this.reviewNonces.delete(state.nonce);
+            if (state.awaitingNote !== null) {
+                this.reviewNotePrompts.delete(state.awaitingNote.promptId);
+                state.awaitingNote = null;
+            }
+        }
+        else {
+            state.notice = { headline: response.headline, lines: response.detail };
+        }
+        await this.redrawReview(state);
+    }
+    /** One `editMessageText` that replaces a review card's text and its keyboard. */
+    async redrawReview(state) {
+        const drawn = renderReviewCard(state);
+        try {
+            await this.call("editMessageText", {
+                chat_id: this.chatId,
+                message_id: Number(state.deliveryId),
+                text: drawn.text,
+                parse_mode: "HTML",
+                disable_web_page_preview: true,
+                ...(drawn.keyboard === null ? {} : { reply_markup: drawn.keyboard }),
+            });
+        }
+        catch (cause) {
+            // APRV-277: the one failure that is not one. See isMessageNotModified.
+            if (isMessageNotModified(cause))
+                return;
+            // Cosmetic in the same sense every other failed edit here is: whatever
+            // the runtime appended has already happened, and no chat message changes
+            // it. The sample's state is the log's answer, never this card's text.
+            this.complain(`approval: telegram could not redraw the review card for sample seq ${String(state.card.sampleSeq)} (message ${state.deliveryId}): ${this.describe(cause)} — the log is what it is; only the message is stale`);
+        }
+    }
+    async ignore(result, callbackId, kind, detail, reply) {
+        this.counters.anomalies[kind] += 1;
+        result.ignored.push({ kind, detail });
+        this.complain(`approval: telegram ignored a callback (${kind}): ${detail}`);
+        // A refusal toast is a courtesy, not part of the decision path: it is best
+        // effort and its failure is not the listener's problem. Through
+        // {@link safeAnswer} since APRV-196, so that this counts as THE ack for the
+        // query and `handleUpdate`'s guarantee does not add a second, vaguer one on
+        // top of the sentence this path already chose.
+        await this.safeAnswer(callbackId, reply);
+    }
+    async answer(callbackId, text) {
+        if (callbackId.length === 0)
+            return;
+        await this.call("answerCallbackQuery", { callback_query_id: callbackId, text });
+    }
+    /**
+     * Answer, and never throw (APRV-196).
+     *
+     * A toast is a courtesy on every path, including the successful one: the
+     * decision is already in the log by the time the ack is attempted, and an
+     * `answerCallbackQuery` that fails (Telegram drops a query after its own
+     * window, and a phone on a train produces plenty of late taps) must not
+     * abandon the annotation or push the poll loop into backoff.
+     *
+     * The attempt is recorded either way, so {@link handleUpdate}'s guarantee
+     * does not turn one failed ack into a second doomed call.
+     *
+     * **Idempotent per callback query since APRV-206.** A query that has already
+     * been answered in this handling is not answered again: the early ack the
+     * decision path sends is THE answer, and every later sentence — a branch's
+     * own toast, the wrapper's fallback — becomes a no-op rather than a second
+     * `answerCallbackQuery`. APRV-196's "exactly one per callback" therefore
+     * holds structurally, in this one method, instead of by every branch
+     * remembering to return.
+     */
+    async safeAnswer(callbackId, text) {
+        if (this.ack !== null && this.ack.id === callbackId) {
+            if (this.ack.answered)
+                return;
+            this.ack.answered = true;
+        }
+        if (callbackId.length === 0)
+            return;
+        try {
+            await this.answer(callbackId, text);
+        }
+        catch (cause) {
+            this.complain(`approval: telegram could not answer a callback (${this.describe(cause)}) — the tap has no toast; the log is unaffected`);
+        }
+    }
+    /**
+     * The delivery this process is holding open for an action reference, if any
+     * (APRV-196).
+     *
+     * A linear walk of the delivery map rather than a second index: the map is
+     * bounded by the pending queue and swept (APRV-135), this runs only on the
+     * uncommon path where a nonce did not resolve, and a second map would be a
+     * second thing to keep in step with `disarm`, `settleMember` and `sweep` —
+     * three places where forgetting is the safety property.
+     *
+     * Digest members are eligible: a member's nonce is deleted the moment it is
+     * settled, so a member still in the map is one still armed on a live message.
+     */
+    liveDeliveryFor(actionRef) {
+        for (const delivery of this.deliveries.values()) {
+            if (delivery.actionRef === actionRef)
+                return delivery;
+        }
+        return undefined;
+    }
+    // -------------------------------------------------------------------------
+    // Transport
+    // -------------------------------------------------------------------------
+    /** Replace the token with a placeholder anywhere it appears in `text`. */
+    redact(text) {
+        return this.token.length === 0 ? text : text.split(this.token).join("<token redacted>");
+    }
+    describe(cause) {
+        return this.redact(cause instanceof Error ? cause.message : String(cause));
+    }
+    /**
+     * The Bot API's own `description` for a failed response, redacted (APRV-277).
+     *
+     * `null` whenever there is nothing trustworthy to quote: the body could not
+     * be read, it was not JSON, or it carried no description. Every failure mode
+     * here is silent by design, because this runs on a path that is already
+     * reporting a failure and a second one thrown from the diagnostic would
+     * replace the real reason with a worse one.
+     */
+    async describeFailure(response) {
+        let body;
+        try {
+            body = await response.text();
+        }
+        catch {
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            return null;
+        }
+        if (parsed === null || typeof parsed !== "object")
+            return null;
+        const description = parsed["description"];
+        if (typeof description !== "string" || description.length === 0)
+            return null;
+        return this.redact(description);
+    }
+    /**
+     * One Bot API call.
+     *
+     * The token is in the URL, which is how the Bot API works — there is no
+     * header form. It is therefore never put in a message body, an error string,
+     * or a log line: {@link redact} scrubs everything that leaves this class, and
+     * the test suite scans every request body and every log byte for it.
+     */
+    async call(method, body, timeoutMs = this.requestTimeoutMs ?? 30_000) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        if (method === "getUpdates")
+            this.inFlight = controller;
+        let raw;
+        try {
+            const response = await this.fetchImpl(`${this.apiBase}/bot${this.token}/${method}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                // APRV-277. The Bot API puts its reason in the error body's
+                // `description`, and dropping it made every failure read as a bare
+                // status: an edit that changed nothing and an edit into a chat the bot
+                // was thrown out of were the same "HTTP 400" on the operator's
+                // terminal. Read best effort — a status is still worth reporting when
+                // the body is missing, truncated, or not JSON at all.
+                const description = await this.describeFailure(response);
+                throw new TelegramApiError(description === null
+                    ? `${method}: HTTP ${response.status}`
+                    : `${method}: HTTP ${response.status} (${description})`, method, response.status, description);
+            }
+            raw = await response.text();
+        }
+        catch (cause) {
+            if (cause instanceof TelegramApiError)
+                throw cause;
+            throw new TelegramApiError(`${method}: ${this.describe(cause)}`, method);
+        }
+        finally {
+            clearTimeout(timer);
+            if (method === "getUpdates")
+                this.inFlight = null;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new TelegramApiError(`${method}: response was not JSON`, method);
+        }
+        const envelope = (parsed ?? {});
+        if (envelope["ok"] !== true) {
+            const said = envelope["description"];
+            const description = typeof said === "string" && said.length > 0 ? this.redact(said) : null;
+            // Unchanged wording: anything the Bot API put here is still shown, and an
+            // absent one is still "no description". `description` is the narrower
+            // field — a non-empty string only — because that is what a caller is
+            // entitled to match on (APRV-277).
+            const shown = said === undefined || said === null ? "no description" : this.redact(String(said));
+            throw new TelegramApiError(`${method}: the Bot API refused (${shown})`, method, 
+            // No HTTP status: this envelope arrived on a 2xx. The description is
+            // carried anyway so a caller reads the same field whichever shape the
+            // failure took (APRV-277).
+            null, description);
+        }
+        return envelope["result"];
+    }
+}
+//# sourceMappingURL=telegram.js.map