approval-md 0.1.0 → 0.3.0

package/dist/src/cli/channel-telegram.d.ts

@@ -0,0 +1,879 @@
+/**
+ * `approval channel telegram listen | health` — the runtime half of the
+ * Telegram channel (SPEC.md §10.3, APRV-26).
+ *
+ * As everywhere else in this CLI, **no logic lives here**. The rendering and
+ * the Bot API are `channels/telegram.ts`; turning a button press into an event
+ * is `channels/contract.ts`'s `recordChannelDecision`, which calls the
+ * human-only `decide()` in `core/gate.ts`. This file resolves configuration,
+ * builds the pending queue, wires the two together, and chooses an exit code.
+ *
+ * Three things it does that the channel deliberately cannot:
+ *
+ * 1. **It reads the environment.** `APPROVAL_TG_TOKEN` and `APPROVAL_TG_CHAT`
+ *    are read here and passed to the channel as values (SPEC.md §5.1: policy
+ *    carries the env-var *names*, never the secrets). Nothing in `channels/`
+ *    touches `process.env`.
+ * 2. **It declares the identity the process itself acts under.** `--as` /
+ *    `APPROVAL_HUMAN` is what this listener is, and it is what a decision is
+ *    recorded as whenever the policy maps no sender for this channel: SPEC.md
+ *    §11's config-declared identity, where the trust boundary is the local
+ *    machine and everyone who can reach the configured chat can approve as that
+ *    actor. Since APRV-324 a policy MAY map Telegram account ids to approvers,
+ *    and then the decision is recorded against the person the operator attested
+ *    the tapping account to, and an unmapped account is refused rather than
+ *    recorded as this listener. Either way the choosing happens in
+ *    `channels/contract.ts` against the attested policy, never here and never
+ *    in the channel. Both settings are stated in `--help` because an operator
+ *    has to be able to see which one they are in without reading the source.
+ * 3. **It holds the token.** A grant mints a single-use execution token;
+ *    `recordChannelDecision` returns it to *this* handler, which prints it on
+ *    **stdout** and never hands it back to the channel. It is never sent to
+ *    Telegram — see the module doc of `channels/telegram.ts` for why a chat
+ *    transcript is not a credential store, and for the flag on that decision.
+ *
+ * ## Payload material — the store, and why `--payloads` still exists
+ *
+ * SPEC.md §6.2 records a `payload_hash` in the log and never the bytes, and
+ * §10.4 requires a channel to present the full payload for a manual action. So
+ * the bytes must come from somewhere the runtime can reach. Since APRV-28 that
+ * somewhere is the payload store beside the log (`.approval/payloads/`, written
+ * by `approval request --payload`), and a listener ordinarily needs no payload
+ * flag at all. `--payloads` remains an override for bytes an operator holds
+ * elsewhere: a JSON file mapping action key to that action's payload value,
+ * consulted before the store. The tagger
+ * (`channels/tagging.ts`) re-hashes whatever it is given and refuses anything
+ * that does not match the recorded binding, so a wrong or stale file cannot put
+ * different bytes in front of an approver than the token will execute — it
+ * produces a visible skip instead. Requests whose material is missing are
+ * reported on stderr and NOT delivered: a manual request rendered without its
+ * payload would be exactly the §10.4 violation the contract refuses.
+ *
+ * ## Dispatch: where it lives, and why it lives here (APRV-55) — flagged
+ *
+ * SPEC.md §10.2 lists "dispatches channel notifications" among the daemon's
+ * jobs. At v0.1 the reference runtime performs that dispatch **in this
+ * listener**, on every poll cycle, and the placement is deliberate:
+ *
+ * 1. The listener already holds the channel connection (the bot token, the
+ *    chat id) and the approver identity. The daemon holds neither, and giving
+ *    it either would put a credential and a human identity into a process
+ *    whose job is to read files and append events.
+ * 2. The daemon is the sole writer of the log; dispatch appends nothing. Moving
+ *    a read-and-send out of the daemon costs the single-writer stance nothing,
+ *    because dispatch was never a write.
+ * 3. A network round-trip inside the daemon's tick couples the projection loop
+ *    to Telegram's availability. A slow Bot API would delay TTL expiry and
+ *    write-back, which are the daemon's actual obligations.
+ *
+ * So this is an implementation placement, not a change to the daemon's stated
+ * role: a later build MAY move dispatch into the daemon (or a supervisor) with
+ * no change to the log or to any event shape. SPEC.md §10.3 records the same.
+ *
+ * ### The cycle
+ *
+ * {@link dispatchPending} runs before every `getUpdates` — the startup send and
+ * every later cycle are the same call with the same state, the startup one
+ * merely finding an empty delivered set. Each call **re-derives** the pending
+ * queue from the verified log ({@link buildPendingQueue}), so which requests
+ * are pending is always the log's answer and never this process's memory. A
+ * request appended while the listener is running is therefore delivered on the
+ * next cycle, without a restart; a request that was decided or whose TTL lapsed
+ * simply stops appearing in the derivation and is never sent.
+ *
+ * What *is* remembered, and only in {@link DispatchState} for this process's
+ * lifetime, is which action keys this listener has already put on the phone.
+ * Losing that memory (a restart, a crash) re-sends everything still pending:
+ * a duplicate on the phone, never silence. That direction is the whole design
+ * (SPEC.md §10.3: channels hold no state that is a source of truth).
+ *
+ * APRV-196 made that re-send legible rather than rarer. The first batch a
+ * process sends is preceded by one banner naming how many are coming, the
+ * copies already in the chat keep working (`actionRefOf` in
+ * `channels/telegram.ts` resolves their buttons to the same request), and the
+ * bookkeeping above is pruned as requests settle and age out instead of growing
+ * for the life of a listener that `approval up` keeps running for weeks.
+ *
+ * ### Send failures
+ *
+ * A key that fails to send stays undelivered, so the next cycle retries it.
+ * There is **no attempt limit**: giving up would turn a transient outage into a
+ * pending request no human ever sees, which is the one failure this project
+ * exists to prevent. The retry rate is bounded by the poll cycle itself (the
+ * long-poll timeout, or the channel's doubling backoff after a poll error), and
+ * the stderr warnings are throttled after {@link DISPATCH_LOUD_ATTEMPTS}
+ * consecutive failures for one key so a long outage cannot bury the terminal.
+ * The one exception is the **startup** dispatch, which still exits non-zero on
+ * a send failure: an operator who has just mistyped a chat id or a token should
+ * learn it immediately rather than watch a listener retry forever.
+ */
+import type { DecideOptions } from "../core/gate.js";
+import { type ChannelRequest, type DeliveryId } from "../channels/contract.js";
+import { type ChannelTagRefusalCode, type TagOptions } from "../channels/tagging.js";
+import { type CheckpointTap } from "./checkpoint-tap.js";
+import { TelegramChannel, type CheckpointTapResponse, type ReviewCard, type ReviewTapResponse, type TelegramCommand, type TelegramTerminalState } from "../channels/telegram.js";
+import { type TelegramDelivery } from "../core/telegram-config.js";
+import { type InstanceFinding } from "../core/instance.js";
+import { type ChannelSender } from "../core/sender-identity.js";
+import { type ParsedFlags } from "./args.js";
+import { type GlossRunner } from "./gloss.js";
+import { type GlossRunnerFactoryOptions } from "./gloss-options.js";
+import type { Streams } from "./main.js";
+/**
+ * The gloss runner this listener will use, as a spreadable fragment (APRV-197).
+ *
+ * ON unless `--no-gloss`. Two flags rather than one because the pair reads
+ * honestly next to `channel cli`, where the default is the other way round:
+ * `--gloss` is accepted here (and is simply the default restated) so that one
+ * command line works on both verbs, and `--no-gloss` wins a tie, because the
+ * flag that removes a language model from the path should never lose one.
+ *
+ * A fragment rather than a value so that "no runner" is the ABSENCE of the
+ * key. {@link ListenSetup.gloss} being optional is what lets every
+ * programmatic caller of `dispatchPending` spawn nothing without saying so.
+ *
+ * `passphraseEnv` is the name this policy's `vault.passphrase_env` gives, and
+ * the only thing the APRV-207 scrub needs from a policy: the subprocess is
+ * spawned starved either way, and naming the variable covers the deployment
+ * that renamed it out from under the credential prefixes.
+ */
+export declare function glossWiring(flags: ParsedFlags, passphraseEnv?: string | null, factories?: Omit<GlossRunnerFactoryOptions, "passphraseEnv">): {
+    gloss?: GlossRunner;
+};
+export interface ListenSetup {
+    channel: TelegramChannel;
+    logPath: string;
+    actor: string;
+    json: boolean;
+    once: boolean;
+    gateOptions: DecideOptions;
+    tagOptions: TagOptions;
+    /**
+     * How this listener puts the pending set in front of the approver (APRV-216):
+     * `paced`, one question at a time, or `burst`, everything not yet sent on
+     * every cycle.
+     *
+     * REQUIRED rather than defaulted, so that every construction site states
+     * which of the two it means. The policy's answer is resolved once, in
+     * {@link prepareListen}, and the default that answer falls back to lives in
+     * `core/telegram-config.ts` beside the other Telegram policy readings.
+     */
+    delivery: TelegramDelivery;
+    /**
+     * Cross-instance findings `--allow-cross-instance` let through (APRV-390).
+     *
+     * Empty on every ordinary start, because a finding without the flag is a
+     * refusal. Carried on the setup rather than printed inside `prepareListen`
+     * for the reason that function prints nothing at all: `approval up` and
+     * `approval channel telegram listen` choose their own stream, and this is
+     * the one thing an overridden refusal still owes the operator.
+     */
+    crossInstance: readonly InstanceFinding[];
+    /**
+     * `--allow-cross-instance` as passed (APRV-390).
+     *
+     * Carried as well as applied, because the flag overrides TWO refusals and
+     * only one of them can be decided synchronously. The credential check is
+     * `prepareListen`'s; the bot-ownership claim needs a `getMe`, so it happens
+     * later and has to be able to ask whether the operator already said yes.
+     */
+    allowCrossInstance: boolean;
+    /**
+     * The Bot API base this listener talks to (APRV-390).
+     *
+     * Part of the bot's identity in the ownership registry, because a bot id is
+     * unique within one Bot API deployment and nothing more.
+     */
+    apiBase: string;
+    /**
+     * How the one-sentence model gloss is obtained (APRV-144).
+     *
+     * OPT-IN, and absent by default. The verb wires in the production runner
+     * (`claude -p --model haiku`, hard timeout, failing toward absence); every
+     * other caller — the test suite above all — gets no gloss unless it hands
+     * over a runner. A default that spawned would make a subprocess an implicit
+     * dependency of anything that drives a dispatch cycle, and would put a model
+     * inside a test suite that must never invoke one.
+     *
+     * Injectable so the tests drive both branches, answered and absent, against
+     * a stub.
+     */
+    gloss?: GlossRunner;
+    /**
+     * Where a checkpoint key may come from, and where the cadence is read
+     * (APRV-257).
+     *
+     * Present at every construction site, because every one of them knows a log
+     * path and a policy. Whether a checkpoint is ever OFFERED is the policy's
+     * answer — `audit.checkpoint_every` plus `audit.checkpoint_keys` — and
+     * {@link checkpointOfferFor} gives up before it walks a log when the policy
+     * names neither, so a gate that has not turned checkpoints on pays a policy
+     * load per cycle and nothing else.
+     */
+    checkpoint: CheckpointTap;
+}
+/**
+ * Claim this listener's bot before it polls (APRV-390).
+ *
+ * ONE `getMe`, once per process, before the first `getUpdates`. Two things
+ * come out of it: the bot's identity, which is the only thing that can tell
+ * two instances holding two differently-named copies of one token apart; and
+ * a claim in the per-machine registry, which is what makes the SECOND such
+ * listener refuse instead of joining a 409 loop.
+ *
+ * ## Why an unreachable Bot API is not a refusal
+ *
+ * A `getMe` that fails says nothing about ownership. The machine may be behind
+ * a captive portal, the API may be rate-limiting, the network may be down for
+ * four seconds. Refusing to start on that would mean a transient network fault
+ * took the phone channel down until somebody noticed, in exchange for no
+ * safety: an unreachable Bot API is also a `getUpdates` that cannot conflict
+ * with anything. So the preflight says what happened and lets the listener
+ * start, where the existing retry loop is already the right behaviour. The
+ * refusal is reserved for the case this task is about, which is a bot that is
+ * demonstrably somebody else's.
+ */
+export declare function claimListenerBot(setup: ListenSetup, report: (message: string) => void): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    code: ListenRefusalCode;
+    message: string;
+}>;
+/**
+ * What to append to a runtime 409, naming the other instance if one is known.
+ *
+ * Read at the moment of the conflict rather than captured at start-up, because
+ * the other gate may have claimed the bot in between: the registry is the only
+ * thing that knows, and it is cheap to re-read.
+ */
+export declare function conflictAdviceFor(setup: ListenSetup): () => string | null;
+/**
+ * Why a listener could not be built. A closed union, because more than one
+ * caller now branches on it: the verb turns each into an exit code, and
+ * `approval up` turns each into a part it will not start (SPEC.md §11.1
+ * invariant 6 — a refusal is machine-readable and distinct).
+ */
+export declare const LISTEN_REFUSAL_CODES: readonly [
+/** A credential variable the policy names is unset or empty. */
+"not-configured", 
+/** No `human:<id>` was declared, so nothing could be recorded against one. */
+"no-identity", 
+/** `--poll-timeout` was not a whole number of seconds. */
+"poll-timeout", 
+/** The log could not be read (or its directory does not exist). */
+"log-unreadable", 
+/** `--payloads` did not hold a JSON object of action key -> payload. */
+"payloads-unreadable", 
+/**
+ * A credential variable holds a value this instance did not configure
+ * (APRV-390): it was exported before the process started and is not this
+ * instance's own `approval env` export, or `.approval/env` names another
+ * instance's keystore item. Refused rather than warned since APRV-390 — the
+ * warning is what let a demo gate spend an evening on the production bot.
+ * `--allow-cross-instance` is the deliberate case.
+ */
+"cross-instance-credential", 
+/**
+ * `getMe` named a bot another instance on this machine has already claimed
+ * (APRV-390). Refused BEFORE the first `getUpdates`, so the operator reads
+ * which two gates are involved instead of an HTTP 409 loop.
+ */
+"bot-owned-elsewhere"];
+export type ListenRefusalCode = (typeof LISTEN_REFUSAL_CODES)[number];
+/** Everything {@link prepareListen} needs, already resolved to absolute paths. */
+export interface ListenRequest {
+    /** The log to derive the queue from and append decisions to. */
+    logPath: string;
+    /** Policy location, with `loadPolicy`'s semantics. */
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    /** `--as` as typed, or `null` to fall back to `APPROVAL_HUMAN`. */
+    as: string | null;
+    /** `--payloads`, already absolute, or `null` for the payload store alone. */
+    payloads: string | null;
+    /** `--api-base`, or `null` for the Bot API. */
+    apiBase: string | null;
+    /** `--poll-timeout` as typed, or `null` for the channel's own default. */
+    pollTimeout: string | null;
+    once: boolean;
+    json: boolean;
+    /**
+     * `--allow-cross-instance` (APRV-390): start on a credential this instance
+     * did not configure, saying so, instead of refusing.
+     */
+    allowCrossInstance?: boolean;
+    /** Where the channel's operational complaints go. Ordinarily stderr. */
+    log(message: string): void;
+    /** The gloss runner, if the caller wants one. See {@link ListenSetup.gloss}. */
+    gloss?: GlossRunner;
+}
+export type ListenPreparation = {
+    ok: true;
+    setup: ListenSetup;
+} | {
+    ok: false;
+    code: ListenRefusalCode;
+    message: string;
+};
+/**
+ * Everything that can fail without touching the network, in order.
+ *
+ * Deliberately sequential and deliberately synchronous: an operator who typed
+ * the wrong thing learns it before a bot message is sent, and the async half
+ * below can then assume its configuration is whole.
+ *
+ * It PRINTS NOTHING and CHOOSES NO EXIT CODE (APRV-110). The verb below turns
+ * each refusal into the usage or I/O error it always was; `approval up` turns
+ * the same refusal into a channel it declines to start, reported in doctor's
+ * vocabulary while the other parts carry on. Two callers, one set of checks,
+ * one set of sentences — which is the only way the two surfaces can agree about
+ * what "telegram is not configured" means.
+ */
+export declare function prepareListen(request: ListenRequest): ListenPreparation;
+/**
+ * What to tell a human who tapped a button for an action this listener is not
+ * holding open (APRV-196).
+ *
+ * The one place a stale tap gets a real answer instead of a shrug. It reads the
+ * VERIFIED log (SPEC.md §11.1(1): a sentence a human reads about what the log
+ * says is derived from a log that verified, or it is not derived at all) and
+ * answers from `requestState`, the same derivation the gate and the pending
+ * queue use. Nothing here decides anything, nothing is appended, and nothing is
+ * remembered between calls: an unreadable log answers `null`, which the channel
+ * renders as its "not open here" toast.
+ *
+ * The argument is an action REFERENCE and never a key. The string came off the
+ * network, so this hashes the keys the log actually carries and looks for a
+ * match; a caller cannot make it describe a request by naming one, and a ref
+ * matching nothing simply answers `null`.
+ *
+ * The walk is over `approval.requested` records, which is the set of things
+ * that could ever have had a button. Run only on a stale tap, which is rare by
+ * construction.
+ */
+export declare function describeActionFor(logPath: string): (actionRef: string) => string | null;
+/**
+ * Consecutive failures for one action key after which stderr warnings thin out.
+ *
+ * Not an attempt limit: the send is retried on every cycle forever (see the
+ * module doc). Only the complaining is throttled, to every tenth attempt.
+ */
+export declare const DISPATCH_LOUD_ATTEMPTS = 3;
+/**
+ * How long an unannotated delivery stays in the bookkeeping before it is
+ * dropped (APRV-196). Twenty-four hours, matching the channel's own
+ * `TELEGRAM_DEFAULT_RETENTION_MS`.
+ *
+ * It is a floor on forgetting and not a deadline for anything: a request that
+ * is still pending is never dropped however old it is, because the pending
+ * queue is checked first. What this bounds is the memory a long-lived listener
+ * holds for questions the log has finished with.
+ */
+export declare const DISPATCH_RETENTION_MS: number;
+/**
+ * The line that introduces the first batch a listener process sends (APRV-196).
+ *
+ * **Why a banner and not an edit of the earlier copies.** The incident was a
+ * restart re-sending five pending requests with no warning, on top of five
+ * copies whose buttons had quietly stopped working. Editing those earlier
+ * copies to say "superseded" would read better — and it is not a design that
+ * can be relied on, because it requires this process to know their message ids,
+ * which a restart by definition does not: SPEC.md §10.3 forbids channel state
+ * that is a source of truth, and a crash loses a cache whether or not one is
+ * allowed. A design that only works when the crash was gentle is a design that
+ * fails on the day it is needed. So the banner is unconditional, and the
+ * earlier copies are made harmless instead of tidy: their buttons resolve by
+ * action reference to the request this process has just re-delivered
+ * (`actionRefOf` in `channels/telegram.ts`), so a human who taps the copy they
+ * can see decides the request they meant.
+ *
+ * It says "started" rather than "restarted" because a listener cannot tell the
+ * two apart, having deliberately kept nothing that would let it, and a first
+ * start that claimed to be a restart would be this channel's own text lying
+ * about the system's history.
+ */
+export declare function bannerLines(pending: number): string[];
+/**
+ * The summary line that precedes a paced send, and the body of `/queue`.
+ *
+ * One message, and everything in it is arithmetic on the verified log at the
+ * instant it is written: how many requests are pending, how long the oldest has
+ * waited, and which classes they are. Nothing is remembered between calls, so
+ * two summaries a minute apart can disagree only because the log moved.
+ *
+ * The class tally is the part worth the space. The count alone says how much
+ * work is waiting; the classes say what KIND of work, which is what tells an
+ * approver whether the queue is six identical `network.call`s they can walk
+ * through or one `policy.edit` they should read carefully.
+ */
+export declare function summaryLines(requests: ChannelRequest[], now: string): string[];
+/**
+ * `/queue`'s reply: the summary, then one numbered line per pending request.
+ *
+ * Derived, like the summary, from the verified log at reply time and not from
+ * anything this process is holding: the numbering is positional and names no
+ * button, so a stale copy of this list cannot be used to decide anything. The
+ * marker says which one this listener has selected and once delivered, because
+ * the question `/queue` is usually asked to answer is "what else is there
+ * besides the one I am looking at" — and, since APRV-256, its unhappy twin,
+ * "where is the one I am supposed to be looking at".
+ *
+ * The footer answers that second question the only honest way available to a
+ * process whose knowledge of the chat ends at "a send returned success": it
+ * says what was sent, says it cannot tell whether the card survived, and then
+ * spends its remaining words on recovery rather than reassurance.
+ */
+export declare function queueLines(requests: ChannelRequest[], now: string, shown: readonly string[]): string[];
+/**
+ * What this process is showing, and in what order (APRV-216). **In memory
+ * only**, like every other field of {@link DispatchState} and for the same
+ * reason (SPEC.md §10.3).
+ *
+ * None of this is truth, and the check that proves it is what happens when it
+ * is lost: a restarted listener re-derives the pending set from the verified
+ * log, rebuilds the order from log order, and shows the oldest — which is
+ * exactly what a fresh start does anyway. What a crash costs is the human's
+ * place in a walkthrough, never a request that stays pending in the log and is
+ * never shown.
+ */
+export interface PacedState {
+    /**
+     * Every pending action key, in the order this process will show them.
+     *
+     * Seeded from log order (oldest first, which is what `buildPendingQueue`
+     * returns) and rearranged by `/skip` alone. Keys the log no longer calls
+     * pending are dropped on every cycle, and newly pending ones join the back.
+     */
+    order: string[];
+    /**
+     * The action keys of the unit in front of the approver, or `null` when
+     * nothing is.
+     *
+     * A unit rather than a key because a digest (APRV-115) is one thing to read
+     * and several things to decide. It is released when the log says none of its
+     * members is pending any more, which is what makes a decision — at any
+     * surface, on any copy — advance the walkthrough.
+     */
+    current: string[] | null;
+    /** Whether any summary has been sent yet, i.e. whether this is the start. */
+    summarySent: boolean;
+    /** The pending count the last summary named, so growth can be recognised. */
+    announced: number;
+}
+/**
+ * The retrospective walkthrough this process is running (APRV-299). **In memory
+ * only**, exactly like {@link PacedState} and under the same rule (SPEC.md
+ * §10.3).
+ *
+ * Its loss is the check that it is not truth: a restarted listener re-derives
+ * the open samples from the verified log, rebuilds the order from log order,
+ * and offers the oldest — which is what a fresh start does anyway. A card that
+ * never arrives, or that a human scrolls past, leaves the sample OPEN: it stays
+ * in `approval audit list`, in `.approval/QUEUE.md`, and reviewable with
+ * `approval audit review <seq>`. Nothing here can empty the backlog, which is
+ * the property a sampled-audit backlog exists to have.
+ */
+export interface ReviewWalkthrough {
+    /** Every open sample's seq, in the order this process will show them. */
+    order: number[];
+    /** The sample whose card is in front of the approver, or `null`. */
+    current: number | null;
+    /** Sample seq -> the message this process sent the card as. */
+    readonly delivered: Map<number, DeliveryId>;
+    /** Whether any review summary has been sent yet. */
+    summarySent: boolean;
+    /** The open count the last summary named, so growth can be recognised. */
+    announced: number;
+    /**
+     * The log's size in bytes when this pass last derived the backlog, or `null`
+     * before the first one.
+     *
+     * A cost guard and nothing else, and it is sound for exactly one reason: the
+     * log is APPEND-ONLY, so a size that has not changed is a record set that has
+     * not changed. It is read only to skip a full verified walk on the cycle
+     * where a card is already in front of the approver and nothing has been
+     * written — which, with a 25-second poll and a human who answers in minutes,
+     * is most cycles. Every other cycle re-derives from the log as usual, and a
+     * lost or stale value costs one extra read rather than a wrong answer.
+     */
+    logSize: number | null;
+}
+/**
+ * The summary line that precedes a review card, and `/queue`'s review footer.
+ *
+ * Arithmetic on the verified log at the instant it is written, exactly as
+ * {@link summaryLines} is: how many samples are awaiting review, how old the
+ * oldest is, and which classes they are. The last clause is the one that stops
+ * a reader treating this like the pending queue: nothing here is waiting on
+ * them, because all of it has already happened.
+ */
+export declare function reviewSummaryLines(cards: ReviewCard[], now: string): string[];
+/**
+ * What one listener process remembers between cycles. **In memory only.**
+ *
+ * SPEC.md §10.3: channels hold no state that is a source of truth. Nothing here
+ * is truth — the pending set is re-derived from the verified log every cycle,
+ * and this only prevents a second copy of a message this process already sent.
+ * Its loss (restart, crash) degrades to a re-send, never to a request that is
+ * pending in the log and absent from the approver's phone.
+ */
+export interface DispatchState {
+    /**
+     * action key -> the delivery id this process sent it under.
+     *
+     * Pruned (APRV-196): an entry goes when the request reaches a terminal state
+     * and its message has been annotated, and a straggler goes when it is older
+     * than {@link DISPATCH_RETENTION_MS} and the pending queue no longer carries
+     * it. Neither prune can cost a re-send, because `buildPendingQueue` only ever
+     * returns requests the verified log says are pending — the same reason losing
+     * the whole map to a restart is safe.
+     */
+    readonly delivered: Map<string, DeliveryId>;
+    /** action key -> when this process sent it, ms since epoch (APRV-196). */
+    readonly sentAtMs: Map<string, number>;
+    /**
+     * Whether the re-delivery banner has been sent (APRV-196).
+     *
+     * A box rather than a field because {@link DispatchState} is `readonly`
+     * everywhere else, and for the same reason: a cycle may write what it did,
+     * and nothing may swap the state out from under one.
+     */
+    readonly banner: {
+        sent: boolean;
+    };
+    /** action key -> consecutive failed send attempts. Cleared on success. */
+    readonly attempts: Map<string, number>;
+    /** `<action key>:<code>` skips already reported, so cycles do not repeat them. */
+    readonly warned: Set<string>;
+    /**
+     * Keys this process has already annotated on the approver's phone (APRV-106
+     * for withdrawal, APRV-113 for every other terminal state). In memory, like
+     * `delivered`, and for the same reason: it stops a second edit of the same
+     * message, and its loss costs a duplicate edit at worst.
+     *
+     * The memory that matters here is `delivered`, and losing it degrades to
+     * un-annotated messages, NEVER to wrong annotations: a process that does not
+     * remember sending a message cannot edit it, and one that does re-reads the
+     * outcome from the verified log every cycle. A fresh listener also never
+     * sends a settled request in the first place — `buildPendingQueue` re-derives
+     * from the verified log and only `requested` is pending — so a restart leaves
+     * stale text on old messages whose buttons the gate refuses anyway, and
+     * nothing worse.
+     */
+    readonly annotated: Set<string>;
+    /**
+     * The walkthrough this process is running under `delivery: paced`
+     * (APRV-216). Present under `burst` too and simply never read there, so that
+     * one state shape serves both modes and a policy change between two runs
+     * needs no different bookkeeping.
+     */
+    readonly paced: PacedState;
+    /**
+     * The checkpoint prompt this process has outstanding (APRV-257). **In memory
+     * only**, like everything else here.
+     *
+     * `offeredSince` is the newest checkpoint's seq at the moment a prompt went
+     * out (`null` for a log that had never been checkpointed), and it is what
+     * makes "at most one outstanding, and never a nag" a single condition: a
+     * cadence that has lapsed keeps producing an offer on every cycle, and this
+     * process asks once per lapse. The value changes only when a checkpoint
+     * actually lands, which is also the moment due-ness goes false — so the next
+     * prompt comes from the next lapse and never from this one repeating.
+     *
+     * `offered: false` means nothing is outstanding. Losing the box to a restart
+     * costs one duplicate prompt for a checkpoint that is genuinely owed, which
+     * is the same direction every other piece of this bookkeeping degrades in.
+     */
+    readonly checkpoint: {
+        offered: boolean;
+        offeredSince: number | null;
+    };
+    /**
+     * The retrospective walkthrough (APRV-299), paced in both delivery modes.
+     *
+     * Always paced, and deliberately so even under `burst`: a review is never
+     * urgent, nobody is blocked on one, and a restart that put sixty of them on a
+     * phone at once would be the flood APRV-287 collapsed in the other direction.
+     * One card at a time, behind a summary, is the whole of the design.
+     */
+    readonly review: ReviewWalkthrough;
+}
+export declare function newDispatchState(): DispatchState;
+/** What one {@link dispatchPending} call did. Total: it never throws. */
+export interface DispatchResult {
+    /** Requests put in front of the approver by this cycle. */
+    delivered: {
+        action_key: string;
+        delivery_id: DeliveryId;
+    }[];
+    /** Sends that failed and will be retried on the next cycle. */
+    failed: {
+        action_key: string;
+        attempts: number;
+        message: string;
+    }[];
+    /**
+     * The queue could not be derived at all: the log is unreadable or does not
+     * verify. Nothing was sent. Fatal at startup, retried on later cycles.
+     */
+    queueError?: {
+        code: ChannelTagRefusalCode;
+        message: string;
+    };
+    /**
+     * Deliveries annotated with their terminal outcome and disarmed this cycle
+     * (APRV-106 for `withdrawn`, APRV-113 for the rest).
+     */
+    annotated: {
+        action_key: string;
+        delivery_id: DeliveryId;
+        outcome: TelegramTerminalState;
+    }[];
+    /**
+     * Digests sent this cycle (APRV-115): the message that carries the buttons,
+     * the batch delivery id every member's event will carry, and the members.
+     * A group that fell back to one message per member produces no entry here.
+     */
+    digests: {
+        delivery_id: DeliveryId;
+        batch_delivery_id: DeliveryId;
+        action_keys: string[];
+    }[];
+    /**
+     * The re-delivery banner, when this cycle sent one (APRV-196): the message
+     * that precedes a startup batch and says how many requests are coming.
+     */
+    banner?: {
+        delivery_id: DeliveryId;
+        pending: number;
+    };
+    /**
+     * The paced summary this cycle sent, when it sent one (APRV-216): the line
+     * that precedes the request being shown and says how many are waiting behind
+     * it. Sent by the first paced cycle that has something to show, and again
+     * whenever the pending set has grown while nothing was in front of the
+     * approver. Never both this and {@link banner}: they are the two modes'
+     * openings, and a process runs one mode.
+     */
+    summary?: {
+        delivery_id: DeliveryId;
+        pending: number;
+    };
+    /**
+     * Action keys dropped from the delivery bookkeeping this cycle (APRV-196),
+     * with why. Neither kind can cost a re-send: the pending queue is the log's
+     * answer, and a dropped key that is still pending is simply re-delivered.
+     */
+    pruned: {
+        action_key: string;
+        reason: "settled" | "stale";
+    }[];
+    /**
+     * The collapsed re-delivery this cycle sent, when it sent one (APRV-287):
+     * the one message that stood in for a batch of requests nobody is waiting on
+     * any more, and the keys it covers. At most one, on a process's first cycle.
+     */
+    collapsed?: {
+        delivery_id: DeliveryId;
+        action_keys: string[];
+        oldest_ms: number;
+    };
+    /**
+     * The `CHECKPOINT DUE` prompt this cycle sent, when it sent one (APRV-257):
+     * the message it is on and the head it asks about. At most one per lapse.
+     */
+    checkpoint?: {
+        delivery_id: DeliveryId;
+        seq: number;
+        hash: string;
+    };
+    /**
+     * The review card this cycle sent, when it sent one (APRV-299): the message
+     * it is on, the `audit.sampled` seq it is drawn for, and the action it is
+     * about. At most one per cycle, and none while a request is in front of the
+     * approver.
+     */
+    reviewCard?: {
+        delivery_id: DeliveryId;
+        sample_seq: number;
+        action_key: string;
+    };
+    /**
+     * The review summary this cycle sent, when it sent one (APRV-299): the line
+     * saying how many samples are awaiting review and how old the oldest is.
+     */
+    reviewSummary?: {
+        delivery_id: DeliveryId;
+        open: number;
+    };
+    /**
+     * The review backlog could not be derived: the log is unreadable or does not
+     * verify. No card was sent. Never fatal — a review is not a decision anyone
+     * is blocked on — and retried on the next cycle.
+     */
+    reviewError?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * One dispatch cycle: re-derive the pending queue from the verified log, send
+ * whatever this process has not already sent.
+ *
+ * `now` is a parameter, not a clock read: TTL judgment inside
+ * {@link buildPendingQueue} is deterministic and the tests drive it at chosen
+ * instants. Requests that are decided, expired, or not yet requested are absent
+ * from the derivation and so are never sent.
+ */
+export declare function dispatchPending(setup: ListenSetup, streams: Streams, state: DispatchState, now: string): Promise<DispatchResult>;
+/**
+ * How old a pending request must be, on a listener's first cycle, to be one
+ * nobody is waiting on (APRV-287).
+ *
+ * The hook's own wait PLUS its retry grace, read from the same module the hook
+ * reads (`core/harness-wait.ts`), because two numbers would be two answers to
+ * "is anybody still holding this". Past the wait alone a hook process has
+ * stopped blocking and a retry can still adopt the question, so those are
+ * ordinary pending requests. Past the wait and the grace together nothing will
+ * adopt it: that is the moment the hook itself takes such a request back, and a
+ * request still pending here is one whose session never came back at all —
+ * exactly the dozen that arrived on a phone behind a dead daemon on
+ * 2026-09-06.
+ *
+ * Collapsing is not deciding. These stay pending, listable by `/queue`, and
+ * decidable from any copy already delivered; what changes is how many messages
+ * it takes to say they are there.
+ */
+export declare const COLLAPSE_STALE_AFTER_MS: number;
+/** The computed lines a collapsed re-delivery leads with (APRV-287). */
+export declare function staleLines(requests: ChannelRequest[], now: string): string[];
+export declare function checkpointHandlerFor(setup: ListenSetup, streams: Streams): (tap: {
+    sign: boolean;
+    head: {
+        seq: number;
+        hash: string;
+    };
+    sender?: ChannelSender;
+}) => CheckpointTapResponse;
+/**
+ * What a review tap does: the human-only `reviewSample`, and nothing else
+ * (APRV-299).
+ *
+ * The one path from a button on a phone to an `audit.reviewed`, and it is the
+ * SAME path `approval audit review` takes — same function, same refusals, same
+ * record shape — so a reaction given on a card and one given at a terminal are
+ * indistinguishable to `approval feedback`, which is the whole of AC3.
+ *
+ * The actor is `setup.actor`, the human identity this listener was configured
+ * with (`--as` / `APPROVAL_HUMAN`), exactly as a grant's is. It is never read
+ * off the tap, never off the callback, and never out of a payload field: this
+ * channel does not authenticate the person who pressed the button, and SPEC.md
+ * §11's config-declared identity is what a review is recorded against. Anyone
+ * who can reach the configured chat reviews as that actor, which is the same
+ * trust boundary a tapped grant already stands on.
+ *
+ * The reaction is passed through untouched and NOTHING here reads it (SPEC.md
+ * §11.1 invariant 10): it is a field on a record, chosen by a human, on its way
+ * to the log.
+ */
+export declare function reviewHandlerFor(setup: ListenSetup, streams: Streams): (tap: {
+    sampleSeq: number;
+    verdict: "ok" | "denied";
+    reaction?: "disliked" | "indifferent" | "liked" | "loved";
+    note?: string;
+    sender?: ChannelSender;
+}) => ReviewTapResponse;
+/**
+ * `/queue`, `/skip`, `/next` — the paced walkthrough's three verbs (APRV-216).
+ *
+ * **None of them appends anything**, and the reason is structural rather than
+ * careful: this function never touches `recordChannelDecision`, so there is no
+ * path from a typed word to the log. A decision is a button, always, because a
+ * button carries the nonce and the action reference that bind an answer to the
+ * bytes an approver was shown, and a word typed into a chat carries neither.
+ *
+ * What they do move is process memory:
+ *
+ * - `/queue` reads the verified log and replies with the summary and a numbered
+ *   list. It changes nothing, and it works while a request is selected, because
+ *   the list is derived and not held. The reply says outright that it carries no
+ *   buttons and that it cannot vouch for a card it once sent (APRV-256).
+ * - `/skip` sends the shown unit to the BACK of this process's order and
+ *   forgets having delivered it, so the next cycle shows the next question and
+ *   this one comes round again after the rest. The copy already in the chat
+ *   keeps its buttons, and they still decide the same request by action
+ *   reference (APRV-196), so a skip is "later", never "gone".
+ * - `/next` releases the shown unit without reordering, so this process moves
+ *   past it and does not show it again. The same copy stays live in the chat:
+ *   the approver has kept the question and given up their place in the queue,
+ *   which is the opposite trade from `/skip`.
+ *
+ * A command that finds nothing to do says so, because silence in a chat window
+ * is indistinguishable from a listener that has died.
+ */
+export declare function commandHandlerFor(setup: ListenSetup, streams: Streams, state: DispatchState, 
+/**
+ * When the command arrived. A clock read in production, because a command is
+ * answered when a human types it; injectable for the same reason
+ * {@link dispatchPending} takes `now` as a parameter, since the ages a reply
+ * states are arithmetic against it and a suite must be able to choose them.
+ */
+clock?: () => string): (command: TelegramCommand) => Promise<void>;
+/**
+ * How one run of the listen loop ended (APRV-110).
+ *
+ * `stopped` is the ordinary ending: a signal, or `--once` completing. The two
+ * failures are the ones the startup cycle has always treated as fatal, hoisted
+ * out of the verb so that a supervisor can treat them as a part that fell over
+ * rather than as a process that must exit.
+ */
+export type ListenerOutcome = {
+    kind: "stopped";
+} | {
+    kind: "queue-error";
+    code: ChannelTagRefusalCode;
+    message: string;
+} | {
+    kind: "send-failed";
+    message: string;
+};
+/** A listen loop that is already running. {@link stop} ends it cleanly. */
+export interface RunningListener {
+    /** Settles when the loop ends. Never rejects for a listener-shaped failure. */
+    readonly done: Promise<ListenerOutcome>;
+    /** Stop the loop, now or as soon as it reaches its first poll. */
+    stop(): void;
+}
+/**
+ * Start the dispatch-and-poll loop. **Installs no signal handler** and chooses
+ * no exit code (APRV-110): both are the caller's, because `approval up` runs
+ * this beside a daemon loop and a web server under one set of handlers.
+ *
+ * A FRESH {@link DispatchState} per call, which is the whole of the restart
+ * story: a supervisor that restarts a fallen listener re-derives the pending
+ * queue from the verified log and re-sends everything still pending, exactly as
+ * a restarted process would. A duplicate on the phone, never a silence.
+ */
+export declare function startListener(setup: ListenSetup, streams: Streams): RunningListener;
+/**
+ * The listener verb. Returns a promise, which is why `main` treats `channel`
+ * specially: it is the only long-lived command in the CLI.
+ */
+export declare function commandTelegramListen(argv: string[], streams: Streams, cwd: string): number | Promise<number>;
+/**
+ * Configuration health, offline.
+ *
+ * It answers one question — "is this runtime configured to talk to Telegram?"
+ * — and deliberately makes no network call: a health check that contacted the
+ * Bot API would leak the existence of the bot from any shell, and would fail
+ * for reasons (a captive portal, a rate limit) that say nothing about whether
+ * the operator's configuration is right. The *live* counters (deliveries,
+ * decisions, ignored callbacks, recovered poll errors) belong to a running
+ * listener and are surfaced by `TelegramChannel.health()` / `stats()` in
+ * process, and on the listener's stderr as they happen.
+ */
+export declare function commandTelegramHealth(argv: string[], streams: Streams, cwd: string): number;
+export declare function commandTelegram(argv: string[], streams: Streams, cwd: string): number | Promise<number>;