approval-md 0.1.0 → 0.2.0

package/dist/src/channels/telegram.d.ts

@@ -0,0 +1,1832 @@
+/**
+ * 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 type { ChannelBatch, ChannelDecision, ChannelHealth, ChannelRequest, DecisionOutcome, DeliveryId, RenderedRequest, TaggedField, TestableChannel } from "./contract.js";
+import { type Reaction, type ReviewVerdict } from "../core/audit.js";
+import { type PromptLayout } from "../core/prompt-layout.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 declare const TELEGRAM_DEFAULT_API_BASE = "https://api.telegram.org";
+/** Telegram's hard limit on a message's text. */
+export declare const TELEGRAM_MAX_MESSAGE_CHARS = 4096;
+/** Telegram's hard limit on `callback_data`, in bytes. */
+export declare const TELEGRAM_MAX_CALLBACK_BYTES = 64;
+/** The note recorded on a rejection collected from a button. */
+export declare 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 declare const TELEGRAM_ACK_FALLBACK = "Received \u2014 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 declare const TELEGRAM_ACK_HEARD = "Heard \u2014 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 declare const TELEGRAM_NOT_RECORDED = "\u2717 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 declare const TELEGRAM_HANDLER_FAILED = "This listener failed while recording your tap. Check `approval queue` \u2014 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 declare const TELEGRAM_STALE_COPY_PREFIX = "Earlier copy of this request \u2014 ";
+/**
+ * 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 declare const TELEGRAM_STALE_UNKNOWN = "This request is not open here \u2014 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 declare 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 declare const PAYLOAD_CHUNK_LABEL_TAIL = "the canonical rendering this approval's display_hash names; raw bytes at the store path inside";
+export declare const PAYLOAD_CHUNK_LABEL = "PAYLOAD \u2014 the canonical rendering this approval's display_hash names; raw bytes at the store path inside";
+/**
+ * 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 declare const TELEGRAM_CLAIMED_HEADING_PREFIX = "WHAT THIS DOES \u2014 CLAIMED by";
+export declare const TELEGRAM_CLAIMED_HEADING_SUFFIX = "NOT verified by the runtime";
+export declare const TELEGRAM_CLAIMED_CONTINUED_HEADING = "WHAT THIS DOES (continued) \u2014 CLAIMED, NOT verified by the runtime";
+/**
+ * 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 declare 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 declare const TELEGRAM_TERMINAL_HEADLINES: {
+    readonly granted: "✓ APPROVED";
+    readonly rejected: "✗ REJECTED";
+    readonly revoked: "✗ REVOKED — the grant was taken back";
+    readonly expired: "✗ EXPIRED — the approval window closed";
+    readonly withdrawn: "WITHDRAWN — no decision is needed";
+};
+/** A state {@link TELEGRAM_TERMINAL_HEADLINES} has a word for. */
+export type TelegramTerminalState = keyof typeof TELEGRAM_TERMINAL_HEADLINES;
+/** Whether a derived request state is one an annotation can settle a message on. */
+export declare function isTelegramTerminalState(state: string): state is TelegramTerminalState;
+/**
+ * `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 declare function utcClock(ts: string): string;
+/** The "who decided, when, and which record says so" line of an annotation. */
+export declare function decidedLine(actor: string, ts: string, seq: number): string;
+/**
+ * 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 declare const TELEGRAM_DEFAULT_RETENTION_MS: number;
+/** Least time between two sweeps. A sweep is O(map); once a minute is plenty. */
+export declare const TELEGRAM_SWEEP_INTERVAL_MS = 60000;
+/**
+ * The slice of `fetch` this module uses, structurally.
+ *
+ * Declared here rather than imported so the channel depends on a shape, not on
+ * a lib: a test can hand over a stub, and the default is the global `fetch`
+ * that Node ≥ 20 ships.
+ */
+export type TelegramFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+export interface TelegramConfig {
+    /**
+     * The bot token. Resolved by the *verb* from the variable
+     * {@link telegramTokenEnvFor} names ({@link TELEGRAM_TOKEN_ENV} by default);
+     * this constructor takes the value, so nothing in the channel reads the
+     * environment and a test cannot accidentally pick up a real token.
+     */
+    token: string;
+    /** The approver chat id, as a string. Callbacks from any other chat are ignored. */
+    chatId: string;
+    /** Bot API base. Defaults to {@link TELEGRAM_DEFAULT_API_BASE}. */
+    apiBase?: string;
+    /** Injectable `fetch`, for tests. Defaults to the global. */
+    fetch?: TelegramFetch;
+    /** `getUpdates` long-poll timeout, in seconds. */
+    pollTimeoutSeconds?: number;
+    /**
+     * Transport timeout for one call, in milliseconds. Defaults to the long-poll
+     * timeout plus ten seconds, which is the only sane default: a `getUpdates`
+     * that is *supposed* to hang for 25s must not be aborted at 30s of total
+     * silence for the wrong reason. Overridable because a server that accepts a
+     * request and then says nothing at all is a real failure mode, and both an
+     * operator on a flaky link and this repo's test suite want to bound it.
+     */
+    requestTimeoutMs?: number;
+    /** First backoff step after a failed poll, in milliseconds. */
+    backoffMs?: number;
+    /** Backoff ceiling, in milliseconds. */
+    maxBackoffMs?: number;
+    /**
+     * Where operational complaints go. Defaults to stderr. Every message passes
+     * through {@link redact} first, so a token cannot reach it even by accident.
+     */
+    log?: (message: string) => void;
+    /** Injectable nonce source, for deterministic tests. */
+    nonce?: () => string;
+    /**
+     * The policy's `defaults.approval_ttl` in milliseconds, or `null` when it
+     * declares none (APRV-135).
+     *
+     * Passed in by the verb, which has already loaded the policy; the channel
+     * neither reads a policy file nor holds an opinion about what the TTL should
+     * be. It is used for one thing: deciding when a delivery this process
+     * remembers can no longer be the subject of a decision, and can therefore be
+     * forgotten. See {@link TelegramChannel.sweep}.
+     */
+    approvalTtlMs?: number | null;
+    /**
+     * Injectable monotonic-ish clock, in milliseconds, for the sweep.
+     *
+     * Defaults to `Date.now`. It exists so a test can run a week of deliveries in
+     * a millisecond; nothing else in this class reads a clock, and nothing that
+     * reaches a human or the log reads this one.
+     */
+    now?: () => number;
+    /**
+     * What to tell a human who tapped a button for an action this process is not
+     * holding open (APRV-196). One sentence, or `null` for "nothing is known".
+     *
+     * Supplied by the listener, which reads the VERIFIED log and can therefore
+     * say whether the request was granted, rejected, revoked, expired or
+     * withdrawn. The channel asks the question and repeats the answer; it does
+     * not derive one, does not cache one, and could not, because the only thing
+     * that knows is the log.
+     *
+     * The argument is an {@link actionRefOf} digest rather than an action key,
+     * for the same reason the button carries one: the string came off the
+     * network, and the probe's job is to look for a record whose key hashes to
+     * it, never to trust a name it was handed. Optional, and absent by default —
+     * a channel with no probe falls back to a toast that names no outcome.
+     */
+    describeAction?: (actionRef: string) => string | null;
+    /**
+     * Which rows the prompt shows (APRV-218), from `channels.telegram.prompt`.
+     *
+     * Passed in by the verb, which has already loaded the policy, for the reason
+     * {@link TelegramConfig.approvalTtlMs} is: this channel neither reads a
+     * policy file nor holds an opinion about what an operator should see.
+     * Defaults to {@link TELEGRAM_PROMPT_LAYOUT}, the layout APRV-143 and
+     * APRV-163 left behind, so a channel constructed without one renders exactly
+     * what it rendered before the key existed.
+     */
+    layout?: PromptLayout;
+}
+/**
+ * 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 declare const TELEGRAM_ANOMALY_KINDS: readonly [
+/** 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 type TelegramAnomalyKind = (typeof TELEGRAM_ANOMALY_KINDS)[number];
+export interface TelegramStats {
+    /** Messages successfully delivered by `notify`. */
+    notified: number;
+    /** Updates received from `getUpdates`, of any kind. */
+    updates: number;
+    /** Callbacks handed to the runtime's decision handler. */
+    decisions: number;
+    /** Failed `getUpdates` attempts the loop recovered from. */
+    pollErrors: number;
+    /** Ignored callbacks, by reason. Never a decision, never a log event. */
+    anomalies: Record<TelegramAnomalyKind, number>;
+    /**
+     * Taps that arrived on a copy whose nonce this process never issued and were
+     * carried to the gate anyway, because the action they reference is one this
+     * process is holding open (APRV-196). Not an anomaly: it is the duplicate-copy
+     * trap being defused, and it is counted so an operator can see how often a
+     * restart is costing the approver a wrong tap.
+     */
+    staleCopyDecisions: number;
+    /**
+     * Bot commands handed to the runtime's command handler (APRV-216). Never a
+     * decision and never a log event: a command reorders what this process shows
+     * and nothing else.
+     */
+    commands: number;
+    /**
+     * Review taps handed to the runtime's review handler (APRV-299). Counted
+     * whether the handler recorded or refused, because what this number measures
+     * is how much of the retrospective backlog reached a human's thumb; what
+     * became of each one is in the log and nowhere else.
+     */
+    reviews: number;
+}
+/**
+ * The bot commands the paced listener answers (APRV-216).
+ *
+ * A closed set, and deliberately a small one. Each is a verb about ATTENTION —
+ * what to put in front of the approver next — and none of them is a verb about
+ * the log: there is no `/grant`, and there will not be one, because a decision
+ * must name the request it decides and a typed command names nothing the
+ * runtime could bind a payload hash to. Buttons decide; commands navigate.
+ */
+/**
+ * The prompt a checkpoint tap is drawn on (APRV-257).
+ *
+ * `head` is the `(seq, hash)` the human is being asked to sign and `lines` is
+ * what they read. They are separate fields because the head must survive into
+ * the signature unchanged while the text is free to be reworded, and because
+ * the runtime — not this channel — decides both.
+ */
+export interface CheckpointPrompt {
+    head: {
+        seq: number;
+        hash: string;
+    };
+    lines: string[];
+}
+/** What the runtime did with a tap, as this channel reports it back. */
+export interface CheckpointTapResponse {
+    /** Whether a `log.checkpoint` landed. */
+    ok: boolean;
+    /** The headline for the edited message. */
+    headline: string;
+    /** The lines under it. */
+    detail: string[];
+    /** The toast on the button, which Telegram caps at a short sentence. */
+    toast: string;
+}
+/**
+ * What the runtime does with a checkpoint tap. `sign` is false for "Not now",
+ * which appends nothing and is not a refusal of anything.
+ */
+export type CheckpointTapHandler = (tap: {
+    sign: boolean;
+    head: {
+        seq: number;
+        hash: string;
+    };
+}) => CheckpointTapResponse | Promise<CheckpointTapResponse>;
+export declare const TELEGRAM_COMMANDS: readonly ["queue", "skip", "next"];
+export type TelegramCommand = (typeof TELEGRAM_COMMANDS)[number];
+/**
+ * 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 declare function parseBotCommand(text: unknown): TelegramCommand | null;
+/** The three characters Telegram's HTML mode treats as markup. */
+export declare function escapeHtml(text: string): string;
+/**
+ * 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 declare const TELEGRAM_GLOSS_SUFFIX = "(model, unverified)";
+/**
+ * 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 declare const TELEGRAM_ANOMALY_MARK = "\u26A0 ";
+/** One line of the message, and the request member it came from. */
+interface Line {
+    field: string;
+    kind: "computed" | "claimed";
+    label: string;
+    text: string;
+    origin: string;
+}
+/**
+ * The message body, split into the two regions SPEC.md §9 requires a channel to
+ * keep visibly apart.
+ *
+ * The split is the whole point: computed lines sit under a heading that names
+ * the runtime as their author, claimed lines under one that names the agent and
+ * says "not verified". The `lastRendered()` report is built from *this* value,
+ * not from a parallel description of it, so the conformance suite is checking
+ * the thing that was actually sent.
+ */
+export interface TelegramRendering {
+    /** Every line, in the order it appears, tagged as the request tagged it. */
+    lines: Line[];
+    /** The header segment: heading, action key, computed block. */
+    header: string;
+    /** The payload region, verbatim, or `null` when the request carries none. */
+    payloadText: string | null;
+    /**
+     * The claimed segment, sent LAST so it sits beside the buttons (APRV-165).
+     *
+     * The claimed lines are what the act means to a human — what this sends, to
+     * whom, why — and the approver decides on that, so it is the thing the thumb
+     * should be next to rather than the metadata above it. SPEC §10.3 permits
+     * claimed material around the canonical block on the condition this keeps:
+     * visibly separated, and headed by a label that names the claiming party and
+     * says the runtime did not check them.
+     *
+     * Never empty. A request with no gloss, no summary and no rationale still
+     * gets this message, because an absent description of the act is itself
+     * something the approver has to see, and because the keyboard needs one
+     * message that is always there to ride on.
+     */
+    claimedText: string;
+}
+/**
+ * The subset of a request's fields a review card also carries (APRV-299).
+ *
+ * A retrospective review card is not a request and must never be rendered as
+ * one, but the five rows below say exactly what they say on a prompt: which
+ * class this was, what the command did, which task it belonged to, what the
+ * agent claimed it would do, and the model's sentence about it where a listener
+ * attached one. Naming the subset as a type is what lets {@link reviewRow} and
+ * {@link telegramRow} share one implementation of those five without either
+ * side casting: a card supplies exactly these fields, and the compiler refuses
+ * a card that reaches for `budgets`, `fullPayload`, or anything else that only
+ * a pending question has.
+ */
+export type ReviewCardFields = Pick<ChannelRequest, "action_key" | "class" | "task" | "summary"> & Partial<Pick<ChannelRequest, "command_breakdown" | "gloss">>;
+/** The rows a review card renders, in the order it renders them (APRV-299). */
+export declare const REVIEW_CARD_ROWS: readonly ["class", "command_breakdown", "task", "summary", "gloss"];
+export type ReviewCardRow = (typeof REVIEW_CARD_ROWS)[number];
+/**
+ * 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 declare function renderTelegram(request: ChannelRequest, heading?: string, layout?: PromptLayout): TelegramRendering;
+/**
+ * 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 declare function chunkForTelegram(text: string, budget?: number): string[];
+/**
+ * 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 declare function chunkClaimedForTelegram(text: string, budget?: number): string[];
+/**
+ * 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 declare function payloadShapeKey(value: unknown): string;
+/**
+ * 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 declare function digestKeyOf(request: ChannelRequest): string;
+export declare function groupForDigest(requests: ChannelRequest[], max?: number): ChannelRequest[][];
+/** One button on a digest keyboard. */
+interface InlineButton {
+    text: string;
+    callback_data: string;
+}
+/** A digest member, as the delivering process remembers it. Never a decision. */
+export interface DigestMemberState {
+    actionKey: string;
+    /** The nonce this member's own two buttons were issued under. */
+    nonce: string;
+    /** The agent's one-line description of the effect. Claimed. */
+    summary: string;
+    /** The agent's cost estimate, formatted. Claimed. */
+    cost: string;
+    /**
+     * The terminal outcome, once one has been observed for this member. Written
+     * only from a gate record or the verified log, never inferred here.
+     */
+    settled: {
+        headline: string;
+        detail: string[];
+    } | null;
+}
+/**
+ * The lines a COLLAPSED delivery leads with, and the fact it is one (APRV-287).
+ *
+ * A listener starting or reconnecting re-derives the pending set from the
+ * verified log and re-delivers it, which is right for a queue somebody is
+ * waiting on and was a flood for a queue nobody is: on 2026-09-06 a restarted
+ * daemon put a dozen requests whose hooks had long since given up in front of
+ * an approver, one message each. Those go out as ONE message instead, and this
+ * is what distinguishes it from an ordinary digest.
+ *
+ * It carries a REJECT-ALL button and deliberately no approve. The payloads are
+ * not in this message, and SPEC.md §10.3 requires the canonical rendering of a
+ * manual action's payload in front of the approver before a decision is
+ * collected: an approve-all here would collect a decision for bytes nobody was
+ * shown. A rejection authorizes nothing, so it needs no such showing, and every
+ * one of these requests can still be approved on its own card or from a
+ * terminal.
+ */
+export interface StaleSummary {
+    /** Computed lines: how many, how old the oldest is, which classes. */
+    lines: string[];
+}
+/** One digest message, as the delivering process remembers it. */
+export interface DigestState {
+    /** The digest message's own id: what every member's annotation edits. */
+    deliveryId: DeliveryId;
+    /** Shared by every member's decision event (SPEC.md §10.3). */
+    batchDeliveryId: DeliveryId;
+    /** The nonce the "all" buttons were issued under. */
+    allNonce: string;
+    /** The computed facts every member shares, already rendered as text. */
+    facts: {
+        label: string;
+        text: string;
+        origin: string;
+    }[];
+    /**
+     * The collapsed re-delivery this message is, or `null` for an ordinary digest
+     * (APRV-287). See {@link StaleSummary}.
+     */
+    stale?: StaleSummary | null;
+    /** Who authored the claimed lines below. */
+    author: string;
+    members: DigestMemberState[];
+    /**
+     * When this process delivered the digest, on {@link TelegramConfig.now}'s
+     * clock (APRV-135). Read by the sweep and by nothing else: it is never
+     * displayed, never compared against a log timestamp, and never a deadline —
+     * the request's own `ts` remains the only instant a TTL is measured from.
+     */
+    deliveredAtMs: number;
+}
+/**
+ * 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 declare function digestFacts(members: ChannelRequest[]): {
+    label: string;
+    text: string;
+    origin: string;
+}[];
+/**
+ * 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 declare function renderDigest(digest: DigestState): {
+    text: string;
+    keyboard: {
+        inline_keyboard: InlineButton[][];
+    } | null;
+};
+/**
+ * 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 declare const ACTION_REF_HEX = 16;
+export declare function actionRefOf(actionKey: string): string;
+/**
+ * `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 declare function callbackData(verb: "g" | "r", nonce: string, actionKey: string): string;
+/**
+ * `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 declare function digestCallbackData(verb: "G" | "R", nonce: string): string;
+/**
+ * `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 declare function checkpointCallbackData(verb: "k" | "x", nonce: string): string;
+/** `k:<nonce>` / `x:<nonce>`, or `null` for anything else. Never throws. */
+export declare function parseCheckpointCallback(data: unknown): {
+    sign: boolean;
+    nonce: string;
+} | null;
+interface ParsedCallback {
+    decision: "grant" | "reject";
+    /** `all` for a digest's "all" button; `one` for every per-request button. */
+    scope: "one" | "all";
+    nonce: string;
+    /** {@link actionRefOf} of the action this button was drawn for, when present. */
+    actionRef: string | null;
+}
+export declare function parseCallbackData(data: unknown): ParsedCallback | null;
+/**
+ * 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 declare const TELEGRAM_REVIEW_HEADING = "REVIEW \u2014 THIS ALREADY RAN";
+/** The headline a recorded review puts on the card it settles. */
+export declare const TELEGRAM_REVIEW_RECORDED = "\u2713 REVIEWED";
+/** The headline a recorded DENIAL puts on the card it settles. */
+export declare const TELEGRAM_REVIEW_DENIED = "\u2717 REVIEWED \u2014 DENIED";
+/**
+ * The headline a card wears while a first Deny tap is armed and nothing has
+ * been recorded.
+ */
+export declare const TELEGRAM_REVIEW_ARMED = "DENY ARMED \u2014 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 declare const TELEGRAM_REVIEW_ACK = "Heard \u2014 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 declare const TELEGRAM_REVIEW_ARM_TOAST = "Deny armed \u2014 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 declare const TELEGRAM_REVIEW_NOTE_TOAST = "Heard \u2014 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 declare function reviewNotePromptLines(reaction: Reaction, verdict: ReviewVerdict, actionKey: string): string[];
+/**
+ * What a tap on a review card asks the runtime to record (APRV-299).
+ *
+ * The channel decides none of it. It reports which sample the card was drawn
+ * for, which verdict the taps add up to, the grade if one was given, and the
+ * human's words if a note prompt collected any — and the runtime's handler
+ * calls the human-only `reviewSample`, exactly as {@link ChannelDecision} goes
+ * to the human-only `decide()`. The actor is NOT here, for the reason it is not
+ * on a decision either: it is the identity the LISTENER was configured with,
+ * never a field that arrived from the network.
+ */
+export interface ReviewTap {
+    /** `seq` of the `audit.sampled` record this card was drawn for. */
+    sampleSeq: number;
+    verdict: ReviewVerdict;
+    /** The grade, when the human gave one. Absent means absent. */
+    reaction?: Reaction;
+    /** The human's words, when a note prompt collected any. */
+    note?: string;
+}
+/** What the runtime did with a review tap, as it reports it back. */
+export interface ReviewTapResponse {
+    /** Whether an `audit.reviewed` landed. */
+    ok: boolean;
+    /** The headline for the edited card. */
+    headline: string;
+    /** The lines under it: the record, or the refusal code and its message. */
+    detail: string[];
+    /** The toast, which Telegram caps at a short sentence. */
+    toast: string;
+}
+export type ReviewTapHandler = (tap: ReviewTap) => ReviewTapResponse | Promise<ReviewTapResponse>;
+/**
+ * One retrospective review card, as the runtime hands it over (APRV-299).
+ *
+ * Everything here is derived by the runtime from the verified log, the policy
+ * and the payload store; the channel adds the buttons and nothing else. The
+ * computed/claimed split of SPEC.md §9 is carried by the fields themselves, so
+ * a card cannot render a claimed summary with a computed line's authority any
+ * more than a prompt can.
+ */
+export interface ReviewCard {
+    /** `seq` of the `audit.sampled` record. What a review names. */
+    sampleSeq: number;
+    /** The rows a request prompt renders identically. */
+    fields: ReviewCardFields;
+    /** Computed: when the sampled execution started, and which record says so. */
+    ranAt: TaggedField<string>;
+    /**
+     * The same instant, machine-readable.
+     *
+     * Not displayed and not a {@link TaggedField} for that reason: it exists so
+     * that the runtime's "oldest awaiting review" arithmetic reads an instant off
+     * the log rather than parsing the sentence {@link ReviewCard.ranAt} renders.
+     * A display string is written for a person and is free to be reworded; a
+     * number a summary is computed from is not.
+     */
+    ranAtTs: string;
+    /** Computed: what the runtime did at the time, and why this is being reviewed. */
+    verdict: TaggedField<string>;
+}
+/** A review card, as the delivering process remembers it. Never a decision. */
+export interface ReviewCardState {
+    deliveryId: DeliveryId;
+    card: ReviewCard;
+    /** The nonce every button on this card was issued under. */
+    nonce: string;
+    /**
+     * Whether a first Deny tap has armed the card. **Process memory**, exactly
+     * like the digest bookkeeping: it appends nothing, it is stated on the card
+     * so the human can see it, and losing it to a restart costs a tap and can
+     * never cost a denial nobody meant. A card whose arming is lost is a card
+     * whose next Deny tap arms again.
+     */
+    denyArmed: boolean;
+    /**
+     * The outcome, once the runtime has recorded one. Written only from the
+     * handler's answer, never inferred here.
+     */
+    settled: {
+        headline: string;
+        detail: string[];
+    } | null;
+    /**
+     * What the last tap produced without settling anything: the arming, or a
+     * refusal the runtime returned. Rendered under the rows so the card keeps
+     * saying what it is about.
+     */
+    notice: {
+        headline: string;
+        lines: string[];
+    } | null;
+    /** The outstanding note prompt, and what its reply will record. */
+    awaitingNote: {
+        promptId: DeliveryId;
+        verdict: ReviewVerdict;
+        reaction: Reaction;
+    } | null;
+    /** When this process delivered the card, on {@link TelegramConfig.now}'s clock. */
+    deliveredAtMs: number;
+}
+/**
+ * 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 declare const REVIEW_CHOICES: readonly ["ok", "deny", "disliked", "indifferent", "liked", "loved"];
+export type ReviewChoice = (typeof REVIEW_CHOICES)[number];
+/**
+ * `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 declare function reviewCallbackData(choice: ReviewChoice, nonce: string): string;
+/** `v:<nonce>:<choice>`, or `null` for anything else. Never throws. */
+export declare function parseReviewCallback(data: unknown): {
+    nonce: string;
+    choice: ReviewChoice;
+} | null;
+/**
+ * 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 declare function renderReviewCard(state: ReviewCardState): {
+    text: string;
+    keyboard: {
+        inline_keyboard: InlineButton[][];
+    } | null;
+};
+/** A Bot API call that did not produce a usable result. */
+export declare class TelegramApiError extends Error {
+    readonly method: string;
+    /**
+     * 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).
+     */
+    readonly status: number | 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.
+     */
+    readonly description: string | null;
+    constructor(message: string, method: string, 
+    /**
+     * 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?: number | 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?: string | null);
+}
+/**
+ * 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 declare function isMessageNotModified(cause: unknown): boolean;
+/** What one `pollOnce()` did, for tests and for programmatic drivers. */
+export interface TelegramPollResult {
+    /** Updates received in this batch. */
+    updates: number;
+    /** Decisions the runtime recorded from this batch, in order. */
+    outcomes: {
+        action_key: string;
+        outcome: DecisionOutcome;
+    }[];
+    /** Callbacks ignored in this batch, with the reason. */
+    ignored: {
+        kind: TelegramAnomalyKind;
+        detail: string;
+    }[];
+    /** Bot commands handed to the runtime in this batch, in order (APRV-216). */
+    commands: TelegramCommand[];
+    /**
+     * Review taps handed to the runtime in this batch, in order (APRV-299), each
+     * with whether an `audit.reviewed` landed. `ok: false` is a refusal the
+     * runtime returned — the card says which code — and nothing was appended.
+     */
+    reviews: {
+        tap: ReviewTap;
+        ok: boolean;
+    }[];
+}
+export interface TelegramListenOptions {
+    /** Process exactly one successful `getUpdates` batch, then return. */
+    once?: boolean;
+    /**
+     * Run before every `getUpdates`, including the first and including the poll
+     * that follows a recovered poll error (APRV-55).
+     *
+     * This is how the runtime gets a dispatch cycle without the channel growing
+     * an opinion about what is pending: the callback belongs to
+     * `cli/channel-telegram.ts`, which re-derives the pending queue from the
+     * verified log and sends what it has not sent yet. The channel neither reads
+     * the log nor remembers a queue, so nothing here makes it stateful.
+     *
+     * It MUST NOT throw. A rejection is treated exactly like a poll failure
+     * (counted, complained about, retried after backoff) rather than being
+     * allowed to end the loop, because a listener that stops listening is the
+     * failure mode this loop exists to rule out.
+     */
+    beforePoll?: () => Promise<void>;
+}
+/**
+ * What {@link TelegramChannel.notifyBatch} did with a set (APRV-115).
+ *
+ * `digestId` is `null` when the set was delivered the old way, one message per
+ * member — the fallback every "cannot render this whole" path takes. `members`
+ * carries the message id each member's annotation must edit, which for a digest
+ * is the one digest message and for the fallback is the member's own.
+ */
+export interface TelegramBatchDelivery {
+    batchDeliveryId: DeliveryId;
+    digestId: DeliveryId | null;
+    members: {
+        action_key: string;
+        delivery_id: DeliveryId;
+    }[];
+    rendered: RenderedRequest[];
+}
+export declare class TelegramChannel implements TestableChannel {
+    readonly name = "telegram";
+    private readonly token;
+    private readonly chatId;
+    private readonly apiBase;
+    private readonly fetchImpl;
+    private readonly pollTimeoutSeconds;
+    private readonly requestTimeoutMs;
+    private readonly backoffMs;
+    private readonly maxBackoffMs;
+    private readonly complain;
+    private readonly makeNonce;
+    /** The policy's approval TTL, or `null` when it declares none (APRV-135). */
+    private readonly approvalTtlMs;
+    private readonly now;
+    /** The listener's verified-log probe for a stale tap (APRV-196), or null. */
+    private readonly describeAction;
+    /** The policy's row layout for this channel (APRV-218). Read-only, and pure input to the renderer. */
+    private readonly layout;
+    /** When {@link sweep} last ran, so the poll loop can call it every cycle. */
+    private lastSweepMs;
+    /**
+     * 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.
+     */
+    private ack;
+    private handler;
+    /**
+     * 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}.
+     */
+    private commandHandler;
+    /**
+     * 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.
+     */
+    private checkpointHandler;
+    /**
+     * 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.
+     */
+    private readonly checkpointNonces;
+    /**
+     * 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.
+     */
+    private reviewHandler;
+    /**
+     * 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.
+     */
+    private readonly reviewCards;
+    /** Review nonce -> the card message it was issued for. */
+    private readonly reviewNonces;
+    /** Note-prompt message id -> the card whose reply it is waiting for. */
+    private readonly reviewNotePrompts;
+    private readonly deliveries;
+    /** Digest message id -> what is on it. Delivery bookkeeping, never truth. */
+    private readonly digests;
+    /** "All" nonce -> the digest message it was issued for. */
+    private readonly allNonces;
+    private rendered;
+    private offset;
+    private counter;
+    private stopped;
+    private inFlight;
+    private readonly counters;
+    constructor(config: TelegramConfig);
+    onDecision(handler: (decision: ChannelDecision) => DecisionOutcome): void;
+    /**
+     * 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: CheckpointTapHandler): void;
+    /**
+     * 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.
+     */
+    offerCheckpoint(prompt: CheckpointPrompt): Promise<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: ReviewTapHandler): void;
+    /**
+     * 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.
+     */
+    offerReview(card: ReviewCard): Promise<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: (command: TelegramCommand) => Promise<void> | void): void;
+    health(): ChannelHealth;
+    /** The rendering split of the most recent `notify`, for the conformance suite. */
+    lastRendered(): RenderedRequest[];
+    /** Delivery, decision and anomaly counters. Live; read from anywhere. */
+    stats(): TelegramStats;
+    /** Ignored callbacks so far. Exposed for `health()` and for operators. */
+    anomalyCount(kind?: TelegramAnomalyKind): number;
+    /**
+     * 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.
+     */
+    notify(target: ChannelRequest | ChannelBatch): Promise<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.
+     */
+    notifyBatch(batch: ChannelBatch): Promise<TelegramBatchDelivery>;
+    /**
+     * 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.
+     */
+    notifyStale(members: ChannelRequest[], stale: StaleSummary): Promise<TelegramBatchDelivery | null>;
+    /**
+     * 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}.
+     */
+    private deliverDigest;
+    /**
+     * 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.
+     */
+    private sendPrompt;
+    private deliverOne;
+    /**
+     * 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.
+     */
+    private disarm;
+    /**
+     * 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?: number): {
+        deliveries: number;
+        digests: number;
+    };
+    /** How many entries the bookkeeping holds. For tests and for operators. */
+    bookkeepingSize(): {
+        deliveries: number;
+        digests: number;
+        allNonces: number;
+        reviewCards: number;
+    };
+    /**
+     * 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.
+     */
+    private settleMember;
+    /** One `editMessageText` that replaces a digest's text and its keyboard. */
+    private redraw;
+    /**
+     * 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.
+     */
+    annotate(deliveryId: DeliveryId, outcome: string, detail: string[], 
+    /**
+     * 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?: string): Promise<void>;
+    /**
+     * The withdrawal case of {@link annotate} (APRV-106), and the one the
+     * {@link Channel} interface names. Its wording is unchanged.
+     */
+    retract(deliveryId: DeliveryId, reason: string, actionKey?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    announce(lines: string[]): Promise<DeliveryId>;
+    /**
+     * 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".
+     */
+    listen(options?: TelegramListenOptions): Promise<void>;
+    /** Stop the loop and abort any in-flight request. */
+    stop(): void;
+    /**
+     * One `getUpdates` batch, processed. Throws on a transport failure — which is
+     * what {@link listen} catches and retries.
+     */
+    pollOnce(): Promise<TelegramPollResult>;
+    /**
+     * 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.
+     */
+    private handleUpdate;
+    /**
+     * 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).
+     */
+    private handleMessage;
+    private routeCallback;
+    /**
+     * 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.
+     */
+    private handleDigestAll;
+    /**
+     * {@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.
+     */
+    private annotateQuietly;
+    /**
+     * 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.
+     */
+    private answerFor;
+    /**
+     * 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.
+     */
+    private handleCheckpointTap;
+    /**
+     * 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.
+     */
+    private handleReviewTap;
+    /**
+     * 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.
+     */
+    private askForNote;
+    /**
+     * 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.
+     */
+    private handleNoteReply;
+    /**
+     * 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.
+     */
+    private recordReview;
+    /** One `editMessageText` that replaces a review card's text and its keyboard. */
+    private redrawReview;
+    private ignore;
+    private answer;
+    /**
+     * 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.
+     */
+    private safeAnswer;
+    /**
+     * 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.
+     */
+    private liveDeliveryFor;
+    /** Replace the token with a placeholder anywhere it appears in `text`. */
+    private redact;
+    private describe;
+    /**
+     * 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.
+     */
+    private describeFailure;
+    /**
+     * 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.
+     */
+    private call;
+}