approval-md 0.2.0 → 0.4.0

package/dist/src/channels/telegram.js

@@ -34,22 +34,59 @@
  * notify, long-poll, callbacks, failure modes — against a local mock Bot API
  * server and never touches the real network.
  *
+ * ## Two transports, one update path (APRV-424)
+ *
+ * An update reaches this channel either because it long-polled for it
+ * ({@link TelegramChannel.pollOnce}) or because Telegram posted it to a URL the
+ * runtime registered ({@link TelegramChannel.deliverUpdate}, fed by
+ * `channels/telegram-webhook.ts`). That is the WHOLE of the difference. Both
+ * entry points hand the update to the same {@link TelegramChannel.handleUpdate}
+ * and therefore to the same chat check, the same `senderOf`, the same
+ * resolution ladder, the same `onDecision` handler and the same
+ * annotate-after-decision edit; a decision does not know which door it came
+ * through, and there is no second copy of any of it to drift.
+ *
+ * The two are mutually exclusive per bot, and the Bot API says so first:
+ * `getUpdates` is refused outright while a webhook is set.
+ * {@link TelegramChannel.claimTransport} refuses the in-process form of the
+ * mistake, and the verbs above ask `getWebhookInfo` and the ownership registry
+ * about the cross-process one.
+ *
  * ## 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.
+ * What this channel authenticates, exactly: that the callback arrived **from
+ * the configured chat id**, and which **Telegram account** the Bot API
+ * attributes the tap to (`callback_query.from.id`). It authenticates no
+ * person, because no transport can: an account id is evidence about an
+ * account.
+ *
+ * What is done with the second fact is the operator's to decide, and since
+ * APRV-324 there are two settings:
+ *
+ * - **No `senders` block in the policy.** Nothing changes from every build
+ *   before it. The decision is recorded against the human actor the *runtime*
+ *   was configured with (`APPROVAL_HUMAN` / `--as`), 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.
+ * - **A `senders` block mapping account ids to approvers.** The decision is
+ *   recorded against the person the operator attested that account to, and a
+ *   tap from an account the policy does not name is REFUSED rather than
+ *   recorded under the listener's identity. The guarantee becomes "the account
+ *   the operator attested to alice tapped Approve", which is a statement about
+ *   Telegram's session handling and the operator's assertion, and still not a
+ *   proof of personhood. Cryptographic identity is future work and is not a
+ *   v0.1 claim.
+ *
+ * The channel itself resolves nothing either way. It reports the account it
+ * saw; `channels/contract.ts` resolves it against the attested policy, and
+ * `core/gate.ts` decides. See `design/channel-sender-identity.md`.
  *
  * ## Formatting: HTML, not MarkdownV2 — a deliberate choice
  *
@@ -370,6 +407,13 @@ const DEFAULT_MAX_BACKOFF_MS = 30_000;
 export const TELEGRAM_DEFAULT_RETENTION_MS = 24 * 60 * 60 * 1000;
 /** Least time between two sweeps. A sweep is O(map); once a minute is plenty. */
 export const TELEGRAM_SWEEP_INTERVAL_MS = 60_000;
+/**
+ * How many refused cards' nonces a channel remembers as dead (APRV-442).
+ *
+ * A bound on memory and nothing else: a nonce that falls off the end reaches
+ * the action-reference fallback, and the gate judges that tap in full.
+ */
+export const TELEGRAM_REFUSED_NONCE_CAP = 1024;
 // ---------------------------------------------------------------------------
 // Anomalies
 // ---------------------------------------------------------------------------
@@ -1206,6 +1250,42 @@ export function parseCheckpointCallback(data) {
         return null;
     return { sign: verb === "k", nonce };
 }
+/**
+ * The account the Bot API attributes a callback to (APRV-324, amended SPEC.md
+ * §10.3).
+ *
+ * `callback_query.from.id` and nothing else. Telegram assembles the `from`
+ * object itself, from the session the tap arrived on, which is why it is the
+ * one field on an update this channel treats as evidence about a person. Three
+ * neighbours are deliberately not read:
+ *
+ * - **`from.username`.** Mutable and reusable, so a mapping keyed on it would
+ *   hand an identity over with a handle. Never a key here and never recorded
+ *   (`core/sender-identity.ts` states the argument in full).
+ * - **`message.from`.** The author of the message the button sits on — this bot
+ *   — rather than the person who pressed it.
+ * - **`data`, and any text.** What the sender says about themselves, which
+ *   §11.1 invariant 4 says may raise scrutiny and never lower it. A callback
+ *   whose payload names a user id names it about itself; the id here comes from
+ *   the transport, and the two disagreeing changes nothing.
+ *
+ * `undefined` when the update carries no usable id: a sender this channel could
+ * not read is not a sender it may guess at, and the decision then travels with
+ * none, which the contract reads as today's configured attribution.
+ */
+export function senderOf(query, channel) {
+    const from = query["from"];
+    if (typeof from !== "object" || from === null)
+        return undefined;
+    const id = from["id"];
+    // Telegram sends a JSON number; a string is accepted for the same reason the
+    // chat check accepts one, and nothing else is: an object or an array here is
+    // a shape this channel does not understand rather than an id to stringify.
+    if (typeof id !== "number" && typeof id !== "string")
+        return undefined;
+    const text = String(id);
+    return text.length === 0 ? undefined : { channel, id: text };
+}
 const CALLBACK_VERBS = {
     g: { decision: "grant", scope: "one" },
     r: { decision: "reject", scope: "one" },
@@ -1494,6 +1574,60 @@ export function isMessageNotModified(cause) {
         cause.description !== null &&
         TELEGRAM_NOT_MODIFIED.test(cause.description));
 }
+/**
+ * Telegram's wording for "somebody else is already long-polling this bot".
+ *
+ * Matched on the description as well as the status, for the same reason
+ * {@link TELEGRAM_NOT_MODIFIED} is: 409 is a conflict, and the conflict this
+ * project cares about is specifically the terminated-by-other-getUpdates one.
+ */
+const TELEGRAM_POLL_CONFLICT = /terminated by other getupdates|make sure that only one bot/iu;
+/**
+ * Whether a failed poll is the Bot API saying another process holds this bot
+ * (APRV-390).
+ *
+ * It is the one poll failure that is not transient and not the network's
+ * fault: retrying it forever produces an identical line every few seconds and
+ * never recovers, because the other poller is not going to stop. {@link
+ * TelegramChannel.listen} reports it once, with whatever the caller knows
+ * about who the other process is, and then stops repeating itself.
+ */
+export function isPollConflict(cause) {
+    return (cause instanceof TelegramApiError &&
+        cause.method === "getUpdates" &&
+        (cause.status === 409 || (cause.description !== null && TELEGRAM_POLL_CONFLICT.test(cause.description))));
+}
+/** A fresh, empty batch report. One shape for both transports (APRV-424). */
+function emptyPollResult() {
+    return { updates: 0, outcomes: [], ignored: [], commands: [], reviews: [] };
+}
+/**
+ * Why a transport claim was refused. Frozen, per SPEC §11.1 invariant 6.
+ *
+ * One code, because there is one fact: this channel is already receiving
+ * updates by the other transport.
+ */
+export const TELEGRAM_TRANSPORT_REFUSAL_CODES = ["transport-conflict"];
+/**
+ * The in-process half of "long-poll and webhook are mutually exclusive"
+ * (APRV-424).
+ *
+ * It is a belt on the braces and says so. The exclusion that matters is per
+ * BOT and lives above this class, where a process can ask the Bot API
+ * (`getWebhookInfo`) and the per-machine ownership registry who else is
+ * receiving this bot's updates; a channel object knows only about itself.
+ * What this rules out is the one failure a caller could cause here and
+ * nowhere else: feeding one channel instance from both a poll loop and an
+ * HTTP handler, where `handleUpdate`'s single ack slot and the delivery maps
+ * would be written by two arrivals nobody ordered.
+ */
+export class TelegramTransportError extends Error {
+    code = "transport-conflict";
+    constructor(message) {
+        super(message);
+        this.name = "TelegramTransportError";
+    }
+}
 export class TelegramChannel {
     name = "telegram";
     token;
@@ -1569,11 +1703,60 @@ export class TelegramChannel {
     digests = new Map();
     /** "All" nonce -> the digest message it was issued for. */
     allNonces = new Map();
+    /**
+     * Action keys whose card this process disarmed on a tap the gate did NOT
+     * settle (APRV-442): a refusal (`sender-unmapped`, a budget, an unattested
+     * policy, anything `ok: false`) or a handler that threw. Drained by
+     * {@link takeReleased}.
+     *
+     * The disarm is right and stays, and {@link refusedNonces} keeps it final:
+     * the refused card's bytes resolve to nothing, not even through the
+     * action-reference fallback to the card that replaces it. What the disarm
+     * must not do is leave the listener believing the REQUEST is on the
+     * approver's phone, which is what `DispatchState.delivered` goes on saying
+     * until something tells it otherwise. This set is that something: it names
+     * a card, never an outcome, and the listener re-derives from the verified
+     * log whether the request is still pending before it offers a new card.
+     * Nothing here decides, and losing it to a restart costs nothing, because a
+     * restarted listener re-sends everything pending anyway.
+     */
+    released = new Set();
+    /**
+     * Nonces of cards a refused or failed tap disarmed (APRV-442), oldest first,
+     * capped at {@link TELEGRAM_REFUSED_NONCE_CAP}.
+     *
+     * Without this, a released request's fresh card would give the refused
+     * card's bytes somewhere to go: the nonce misses, the action reference
+     * resolves to the new live card, and a Telegram redelivery of the refused
+     * tap (a webhook retry) or a client replaying the removed buttons would be
+     * refused again, append again, disarm the new card and cause another
+     * re-send, once per replay. A nonce in this set never takes the fallback, so
+     * a refused card stays exactly as dead as it was before APRV-442 and only
+     * the REQUEST is offered again. Forgetting an entry past the cap degrades to
+     * the fallback, whose tap the gate still judges in full: volume, never a
+     * decision.
+     */
+    refusedNonces = new Set();
     rendered = [];
     offset = 0;
     counter = 0;
     stopped = false;
     inFlight = null;
+    /**
+     * The transport this channel has started receiving updates by, or `null`
+     * before the first one (APRV-424). Sticky for the life of the object: a
+     * process that stopped polling has not stopped being a poller, and the
+     * question this answers is which arrival path owns the maps below.
+     */
+    transport = null;
+    /**
+     * Everything {@link redact} scrubs out of anything that leaves this class.
+     *
+     * The bot token from construction, plus any secret a later call was handed:
+     * {@link registerWebhook} adds the `secret_token` before it sends it, so a
+     * Bot API error quoting the request cannot put it on an operator's terminal.
+     */
+    secrets;
     counters = {
         notified: 0,
         updates: 0,
@@ -1593,6 +1776,8 @@ export class TelegramChannel {
     };
     constructor(config) {
         this.token = config.token;
+        this.secrets =
+            config.token.length === 0 ? [] : [{ value: config.token, label: "<token redacted>" }];
         this.chatId = String(config.chatId);
         this.apiBase = (config.apiBase ?? TELEGRAM_DEFAULT_API_BASE).replace(/\/+$/u, "");
         this.fetchImpl = config.fetch ?? globalThis.fetch;
@@ -1855,8 +2040,15 @@ export class TelegramChannel {
     async deliverDigest(members, batchDeliveryId, stale = null) {
         const allNonce = this.makeNonce();
         const deliveredAtMs = this.now();
+        // The digest's window is the widest member's: it may be forgotten only when
+        // every member is past deciding, and a member nothing bounds keeps it.
+        const windows = members.map((member) => this.retentionWindowMs(member));
+        const windowMs = windows.includes(null)
+            ? null
+            : Math.max(...windows.filter((window) => window !== null));
         const state = {
             deliveredAtMs,
+            windowMs,
             // Assigned once the message exists; nothing consults it before then.
             deliveryId: "",
             batchDeliveryId,
@@ -1916,13 +2108,14 @@ export class TelegramChannel {
         state.deliveryId = deliveryId;
         // Armed only now, and all at once: until the message with the buttons on it
         // exists there is nothing a callback could legitimately answer.
-        for (const member of state.members) {
+        for (const [index, member] of state.members.entries()) {
             this.deliveries.set(member.nonce, {
                 actionKey: member.actionKey,
                 actionRef: actionRefOf(member.actionKey),
                 deliveryId,
                 batchDeliveryId,
                 deliveredAtMs,
+                windowMs: windows[index] ?? null,
             });
         }
         this.digests.set(deliveryId, state);
@@ -2014,6 +2207,7 @@ export class TelegramChannel {
             actionRef: actionRefOf(actionKey),
             deliveryId: sent.deliveryId,
             deliveredAtMs: this.now(),
+            windowMs: this.retentionWindowMs(request),
             ...(batchDeliveryId === undefined ? {} : { batchDeliveryId }),
         });
         return {
@@ -2054,6 +2248,31 @@ export class TelegramChannel {
         }
         return actionKey;
     }
+    /**
+     * How long after delivery the request behind a prompt can still be decided,
+     * on this process's clock, or `null` when nothing bounds it (APRV-423, second
+     * review pass).
+     *
+     * The SHORTER of two bounds, each of which is at or past the gate's own
+     * lapse, so the sweep never forgets a button a decision could still reach:
+     *
+     * - the request's `ttl_remaining_ms`, computed by the listener from the
+     *   verified log against the window the gate judges by (the policy's TTL
+     *   narrowed by the harness cap the requesting hook declared). It was
+     *   measured at tagging time, and delivery is at or after tagging, so
+     *   counting it from delivery ends at or after the real lapse;
+     * - the policy's own TTL ({@link TelegramConfig.approvalTtlMs}), counted from
+     *   delivery, which is at or after the `approval.requested` it really runs
+     *   from. This was the only bound before APRV-423 and it stays as one.
+     *
+     * A request neither bounds is decidable forever, and its entry is dropped
+     * only on an observed settlement. This channel still reads no policy and no
+     * log: both numbers arrive computed, by the verb and by the tagger.
+     */
+    retentionWindowMs(request) {
+        const bounds = [request.ttl_remaining_ms.value, this.approvalTtlMs].filter((bound) => bound !== null);
+        return bounds.length === 0 ? null : Math.min(...bounds);
+    }
     /**
      * Drop the delivery bookkeeping no callback can still be honoured against
      * (APRV-135).
@@ -2088,17 +2307,23 @@ export class TelegramChannel {
      */
     sweep(nowMs = this.now()) {
         this.lastSweepMs = nowMs;
-        const retention = this.approvalTtlMs ?? TELEGRAM_DEFAULT_RETENTION_MS;
-        const expired = (deliveredAtMs) => nowMs - deliveredAtMs >= retention;
-        // Past the approval TTL the gate refuses every decision, so the request is
-        // terminal whether or not this process saw it settle. With no TTL declared
-        // nothing expires, and only an observed settlement makes an entry droppable.
-        const lapsed = (deliveredAtMs) => this.approvalTtlMs !== null && nowMs - deliveredAtMs >= this.approvalTtlMs;
+        // APRV-423 (second review pass): both halves read the ENTRY's own window,
+        // which is the effective one the gate judges its request by, and fall back
+        // to the policy's TTL and then the default only for an entry that carries
+        // none (a review card, which has no request).
+        const retentionOf = (windowMs) => windowMs ?? this.approvalTtlMs ?? TELEGRAM_DEFAULT_RETENTION_MS;
+        const expired = (deliveredAtMs, windowMs) => nowMs - deliveredAtMs >= retentionOf(windowMs);
+        // Past its window the gate refuses every decision on the request, so it is
+        // terminal whether or not this process saw it settle. With nothing bounding
+        // it nothing expires, and only an observed settlement makes it droppable.
+        const lapsed = (deliveredAtMs, windowMs) => windowMs !== null && nowMs - deliveredAtMs >= windowMs;
         let digests = 0;
         for (const [deliveryId, digest] of this.digests) {
             const terminal = digest.members.every((member) => member.settled !== null);
-            if (!(terminal || lapsed(digest.deliveredAtMs)) || !expired(digest.deliveredAtMs))
+            if (!(terminal || lapsed(digest.deliveredAtMs, digest.windowMs)) ||
+                !expired(digest.deliveredAtMs, digest.windowMs)) {
                 continue;
+            }
             this.digests.delete(deliveryId);
             this.allNonces.delete(digest.allNonce);
             digests += 1;
@@ -2110,8 +2335,10 @@ export class TelegramChannel {
             // decides, and it was just judged above.
             if (this.digests.has(delivery.deliveryId))
                 continue;
-            if (!lapsed(delivery.deliveredAtMs) || !expired(delivery.deliveredAtMs))
+            if (!lapsed(delivery.deliveredAtMs, delivery.windowMs) ||
+                !expired(delivery.deliveredAtMs, delivery.windowMs)) {
                 continue;
+            }
             this.deliveries.delete(nonce);
             deliveries += 1;
         }
@@ -2123,7 +2350,7 @@ export class TelegramChannel {
         // this map holds, so keeping the buttons alive costs a map entry and
         // dropping them early would cost a human their thumb.
         for (const [deliveryId, card] of this.reviewCards) {
-            if (card.settled === null || !expired(card.deliveredAtMs))
+            if (card.settled === null || !expired(card.deliveredAtMs, null))
                 continue;
             this.reviewCards.delete(deliveryId);
             this.reviewNonces.delete(card.nonce);
@@ -2233,6 +2460,51 @@ export class TelegramChannel {
     async retract(deliveryId, reason, actionKey) {
         await this.annotate(deliveryId, TELEGRAM_TERMINAL_HEADLINES.withdrawn, [reason], actionKey);
     }
+    /**
+     * The action keys whose card a refused or failed tap disarmed since the last
+     * call, and forget them (APRV-442).
+     *
+     * The listener's dispatch cycle calls this once per cycle and offers a fresh
+     * card for every key the verified log still calls pending. It is a statement
+     * about this process's cards and nothing else: it carries no decision, no
+     * sender and no outcome, and a key in it that the log has since settled is
+     * simply not offered.
+     */
+    takeReleased() {
+        const keys = [...this.released];
+        this.released.clear();
+        return keys;
+    }
+    /**
+     * Mark `delivery`'s card dead and its request released, BEFORE the
+     * annotation that disarms it (APRV-442).
+     *
+     * Every nonce still armed for this request on this message is recorded in
+     * {@link refusedNonces}, together with the nonce the tap carried (which
+     * differs when the tap came from an earlier copy through the fallback), so
+     * none of those bytes can later resolve to the fresh card. On a digest only
+     * this member's nonce is taken: its siblings stay armed on the digest.
+     */
+    release(delivery, tapNonce) {
+        const dead = [tapNonce];
+        for (const [nonce, entry] of this.deliveries) {
+            if (entry.deliveryId === delivery.deliveryId && entry.actionKey === delivery.actionKey) {
+                dead.push(nonce);
+            }
+        }
+        for (const nonce of dead) {
+            // Re-inserted so a nonce marked again counts as the newest.
+            this.refusedNonces.delete(nonce);
+            this.refusedNonces.add(nonce);
+        }
+        while (this.refusedNonces.size > TELEGRAM_REFUSED_NONCE_CAP) {
+            const oldest = this.refusedNonces.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.refusedNonces.delete(oldest);
+        }
+        this.released.add(delivery.actionKey);
+    }
     /**
      * Send one plain message that carries no question (APRV-196).
      *
@@ -2255,6 +2527,32 @@ export class TelegramChannel {
         return String(result.message_id);
     }
     // -------------------------------------------------------------------------
+    // Identity
+    // -------------------------------------------------------------------------
+    /**
+     * Which bot this token is, from one `getMe` (APRV-390).
+     *
+     * `getMe` is the only Bot API call that answers it, and it is the call
+     * `approval doctor` and `approval setup channel telegram` already make for
+     * the same reason: it mutates nothing, sends nothing, and acknowledges
+     * nothing. In particular it is NOT `getUpdates`, so asking who this bot is
+     * consumes no update and steals no pending tap from a listener that is
+     * already running — which matters here above all, because the answer is
+     * what decides whether this process is allowed to poll at all.
+     *
+     * Throws {@link TelegramApiError} like every other call; the caller decides
+     * whether an unreachable Bot API is a refusal or a shrug.
+     */
+    async identify() {
+        const result = await this.call("getMe", {});
+        const id = result["id"];
+        const username = result["username"];
+        return {
+            id: typeof id === "number" || typeof id === "string" ? String(id) : "",
+            username: typeof username === "string" ? `@${username}` : "the bot",
+        };
+    }
+    // -------------------------------------------------------------------------
     // Long polling
     // -------------------------------------------------------------------------
     /**
@@ -2275,8 +2573,19 @@ export class TelegramChannel {
      * decision", not "deliver once at startup, then wait forever".
      */
     async listen(options = {}) {
+        this.claimOrThrow("poll");
         this.stopped = false;
         let backoff = this.backoffMs;
+        /**
+         * APRV-390. The last failure reported, and how many identical ones have
+         * been swallowed since. A 409 does not recover: the other poller is not
+         * going to stop because this one asked again, so the pre-APRV-390 loop
+         * printed the same sentence every few seconds until somebody read the
+         * terminal. The retry itself stays — a listener that stops listening is
+         * the failure this loop rules out — and only the COMPLAINING is collapsed.
+         */
+        let lastComplaint = null;
+        let repeats = 0;
         while (!this.stopped) {
             try {
                 if (options.beforePoll !== undefined) {
@@ -2286,6 +2595,11 @@ export class TelegramChannel {
                 }
                 await this.pollOnce();
                 backoff = this.backoffMs;
+                if (repeats > 0) {
+                    this.complain(`approval: telegram getUpdates recovered after ${String(repeats)} further identical failure(s)`);
+                }
+                lastComplaint = null;
+                repeats = 0;
                 if (options.once === true)
                     return;
             }
@@ -2293,7 +2607,26 @@ export class TelegramChannel {
                 if (this.stopped)
                     return;
                 this.counters.pollErrors += 1;
-                this.complain(`approval: telegram getUpdates failed (${this.describe(cause)}); retrying in ${backoff}ms — the listener is still up`);
+                const conflict = isPollConflict(cause);
+                // The 409's own sentence, said once. It names the fact ("another
+                // process is polling this bot") rather than the HTTP status, because
+                // the status is what a reader was already staring at, and it carries
+                // whatever the caller knows about which two gates are involved.
+                const advice = conflict ? (options.conflictAdvice?.() ?? null) : null;
+                const message = conflict
+                    ? `approval: telegram getUpdates: another process is polling this bot${advice === null ? "" : ` — ${advice}`}; this listener keeps retrying and will not receive a tap until the other one stops`
+                    : `approval: telegram getUpdates failed (${this.describe(cause)}); retrying in ${backoff}ms — the listener is still up`;
+                if (message === lastComplaint) {
+                    repeats += 1;
+                }
+                else {
+                    if (repeats > 0) {
+                        this.complain(`approval: telegram getUpdates: the previous line repeated ${String(repeats)} more time(s)`);
+                    }
+                    this.complain(message);
+                    lastComplaint = message;
+                    repeats = 0;
+                }
                 await sleep(backoff);
                 backoff = Math.min(backoff * 2, this.maxBackoffMs);
             }
@@ -2309,6 +2642,7 @@ export class TelegramChannel {
      * what {@link listen} catches and retries.
      */
     async pollOnce() {
+        this.claimOrThrow("poll");
         // APRV-135. Before the long poll, not after: this is where the loop is
         // about to block for up to `pollTimeoutSeconds`, and a sweep that ran after
         // the block would be a sweep that never runs on a quiet chat. Rate-limited
@@ -2320,35 +2654,163 @@ export class TelegramChannel {
         const updates = await this.call("getUpdates", {
             offset: this.offset,
             timeout: this.pollTimeoutSeconds,
-            // APRV-216. `message` is asked for only while a command handler is
-            // registered: see {@link onCommand} for why a listener that reads
-            // messages nobody asked for would break `approval setup channel
-            // telegram`'s chat discovery.
-            // APRV-299 adds the second reason to read messages: a `loved` or
-            // `disliked` on a review card collects the human's words as a REPLY,
-            // because an inline keyboard has no text input.
-            allowed_updates: this.commandHandler === null && this.reviewHandler === null
-                ? ["callback_query"]
-                : ["callback_query", "message"],
+            allowed_updates: this.allowedUpdates(),
         }, this.requestTimeoutMs ?? (this.pollTimeoutSeconds + 10) * 1000);
-        const result = {
-            updates: 0,
-            outcomes: [],
-            ignored: [],
-            commands: [],
-            reviews: [],
-        };
-        for (const raw of updates) {
-            const update = (raw ?? {});
-            const id = update["update_id"];
-            if (typeof id === "number")
-                this.offset = Math.max(this.offset, id + 1);
-            this.counters.updates += 1;
-            result.updates += 1;
-            await this.handleUpdate(update, result);
-        }
+        const result = emptyPollResult();
+        for (const raw of updates)
+            await this.intake(raw, result);
         return result;
     }
+    /**
+     * Which update types this channel asks for, on either transport (APRV-424).
+     *
+     * APRV-216. `message` is asked for only while a command handler is
+     * registered: see {@link onCommand} for why a listener that reads messages
+     * nobody asked for would break `approval setup channel telegram`'s chat
+     * discovery. APRV-299 adds the second reason to read messages: a `loved` or
+     * `disliked` on a review card collects the human's words as a REPLY, because
+     * an inline keyboard has no text input.
+     *
+     * One function since APRV-424, because `setWebhook` takes the same list as
+     * `getUpdates` and two spellings of it would be two answers to "what does
+     * this listener read" — with the webhook's answer frozen at registration
+     * time, where nobody would look for it.
+     */
+    allowedUpdates() {
+        return this.commandHandler === null && this.reviewHandler === null
+            ? ["callback_query"]
+            : ["callback_query", "message"];
+    }
+    /**
+     * One update, from whichever transport carried it (APRV-424).
+     *
+     * The whole of what the webhook adds is the ARRIVAL. Everything a tap then
+     * passes through — the chat check, `senderOf`, the checkpoint and review
+     * parsers, the resolution ladder, the early ack, `this.handler` and the
+     * annotation written from the record the gate appended — is
+     * {@link handleUpdate}, called from here and from {@link pollOnce}, and
+     * there is no second copy of any of it. `tests/telegram-webhook.test.ts`
+     * drives one callback through both entry points and compares the records the
+     * log ends up holding.
+     *
+     * The sweep is `pollOnce`'s, for `pollOnce`'s reason: this is the moment the
+     * process is about to be idle, and a channel that only ever wakes for taps
+     * would otherwise never run one.
+     */
+    async deliverUpdate(update) {
+        this.claimOrThrow("webhook");
+        const nowMs = this.now();
+        if (nowMs - this.lastSweepMs >= TELEGRAM_SWEEP_INTERVAL_MS)
+            this.sweep(nowMs);
+        const result = emptyPollResult();
+        await this.intake(update, result);
+        return result;
+    }
+    /** The per-update bookkeeping both transports do, before `handleUpdate`. */
+    async intake(raw, result) {
+        const update = (raw ?? {});
+        const id = update["update_id"];
+        // Meaningless on the webhook, where Telegram acknowledges by the HTTP
+        // response, and harmless: the offset is read by `getUpdates` alone, and a
+        // channel that has claimed the webhook transport never issues one.
+        if (typeof id === "number")
+            this.offset = Math.max(this.offset, id + 1);
+        this.counters.updates += 1;
+        result.updates += 1;
+        await this.handleUpdate(update, result);
+    }
+    /**
+     * Bind this channel to one transport, or say which one already holds it
+     * (APRV-424).
+     *
+     * Idempotent for the transport already claimed, so a webhook server that
+     * claims at start-up and then delivers, or a driver calling `pollOnce` in a
+     * loop, pays nothing. Not released by {@link stop}: a process that stopped
+     * polling has not stopped being a poller, and re-pointing a live channel's
+     * delivery maps at a second arrival path is the state this exists to refuse.
+     */
+    claimTransport(transport) {
+        if (this.transport === null || this.transport === transport) {
+            this.transport = transport;
+            return { ok: true, transport };
+        }
+        return {
+            ok: false,
+            code: "transport-conflict",
+            message: `this channel is already receiving updates by ${this.transport}, so it cannot also receive them by ${transport}. Long polling and a webhook are alternatives per bot: the Bot API refuses getUpdates outright while a webhook is set, and a process running both would answer a tap from whichever half reached it first`,
+        };
+    }
+    /** {@link claimTransport}, for the paths where a refusal is a caller's bug. */
+    claimOrThrow(transport) {
+        const claim = this.claimTransport(transport);
+        if (!claim.ok)
+            throw new TelegramTransportError(claim.message);
+    }
+    // -------------------------------------------------------------------------
+    // Webhook registration (APRV-424)
+    // -------------------------------------------------------------------------
+    /**
+     * Point this bot's updates at `url`, and require `secret` on every post.
+     *
+     * Three properties, and each is a refusal to be clever:
+     *
+     * - **The secret is Telegram's own mechanism**, `secret_token`, echoed back
+     *   on every delivery in the `X-Telegram-Bot-Api-Secret-Token` header. The
+     *   receiver compares it and refuses anything else, so a URL that leaks (a
+     *   proxy log, a referrer, a screenshot) is a URL that still decides
+     *   nothing.
+     * - **It is redacted from this moment on.** The value is added to the
+     *   channel's secret list BEFORE the call, so a Bot API error that quotes
+     *   the request cannot print it.
+     * - **Pending updates are kept.** `drop_pending_updates` is left false:
+     *   taps that arrived while the process was down are the approver's answers,
+     *   and the gate is what decides whether they are still honourable.
+     */
+    async registerWebhook(url, secret) {
+        if (secret.length > 0 && !this.secrets.some((held) => held.value === secret)) {
+            this.secrets.push({ value: secret, label: "<webhook secret redacted>" });
+        }
+        await this.call("setWebhook", {
+            url,
+            secret_token: secret,
+            allowed_updates: this.allowedUpdates(),
+            drop_pending_updates: false,
+        });
+    }
+    /**
+     * Take this bot's webhook away, so `getUpdates` works again.
+     *
+     * Called on a clean stop of the webhook runner. Pending updates are kept for
+     * {@link registerWebhook}'s reason: the next process to start — a poller or
+     * another webhook — is entitled to the taps that arrived in between.
+     *
+     * `timeoutMs` is what the stop path passes, and it is shorter than this
+     * channel's ordinary request timeout on purpose (APRV-424, second review,
+     * note 6). A stop already waits for the receiver to drain, and an operator
+     * pressing Ctrl-C a second time is asking for the process to end: half a
+     * minute of an unreachable Bot API on top of that reads as a hang, and the
+     * webhook it failed to remove is reported rather than silently retried.
+     */
+    async deleteWebhook(timeoutMs) {
+        await this.call("deleteWebhook", { drop_pending_updates: false }, ...(timeoutMs === undefined ? [] : [timeoutMs]));
+    }
+    /**
+     * What the Bot API says is receiving this bot's updates right now.
+     *
+     * The one authority on the question, and the reason it is asked at start-up
+     * by both transports: the ownership registry knows about processes on THIS
+     * machine, and a webhook registered from a laptop in another timezone is
+     * still a webhook swallowing every tap this poller is waiting for.
+     */
+    async webhookInfo() {
+        const result = await this.call("getWebhookInfo", {});
+        const url = result["url"];
+        const pending = result["pending_update_count"];
+        return {
+            url: typeof url === "string" ? url : "",
+            pendingUpdateCount: typeof pending === "number" ? pending : 0,
+        };
+    }
     /**
      * Exactly one `answerCallbackQuery` per callback query, on every path
      * (APRV-196).
@@ -2478,17 +2940,37 @@ export class TelegramChannel {
         const chat = (message["chat"] ?? {});
         const chatId = chat["id"] === undefined ? "" : String(chat["id"]);
         // (a) Not our chat. Counted, answered, never decided, never logged.
+        //
+        // APRV-324 leaves this check exactly where it is, FIRST and ahead of the
+        // sender, on purpose: the mapping widens WHO may decide and never WHERE
+        // from. A callback carrying a perfectly mapped `from.id` but arriving in a
+        // chat this listener does not answer to is ignored here, before anything
+        // reads a sender, because a bot that accepted it would be one an operator
+        // could not scope by conversation.
         if (chatId !== this.chatId) {
             await this.ignore(result, callbackId, "foreign-chat", `callback from chat ${JSON.stringify(chatId)}, which is not the configured approver chat`, "This bot only accepts decisions from its configured approval chat.");
             return;
         }
+        // APRV-324. The one field on this update that identifies a PERSON rather
+        // than a conversation, read once, here, directly after the chat check and
+        // BEFORE every branch below. Its position is the fix for the follow-up
+        // review: read later, three callback families — checkpoint signatures,
+        // review cards and the decision ladder — would each have had their own
+        // chance to keep the pre-mapping behaviour, and two of them are privileged
+        // gestures. `callback_query.from` is the Bot API's own attribution of the
+        // tap to an account; nothing inside `message`, `data` or any text is
+        // consulted, because those are what the sender says about themselves. It is
+        // an observation and nothing more: this channel resolves no identity and
+        // chooses no actor, it reports what it saw and the runtime's handlers
+        // resolve it against the attested policy.
+        const sender = senderOf(query, this.name);
         // APRV-257, before the decision vocabulary and in a parser of its own. A
         // checkpoint button decides no request, so it must never reach the ladder
         // below — where an unresolved nonce falls back to an action reference, and
         // a signature gesture would start looking for something to approve.
         const checkpoint = parseCheckpointCallback(query["data"]);
         if (checkpoint !== null) {
-            await this.handleCheckpointTap(checkpoint, callbackId, result);
+            await this.handleCheckpointTap(checkpoint, callbackId, result, sender);
             return;
         }
         // APRV-299, before the decision vocabulary and in a parser of its own, for
@@ -2498,7 +2980,7 @@ export class TelegramChannel {
         // happened would start looking for something to approve.
         const review = parseReviewCallback(query["data"]);
         if (review !== null) {
-            await this.handleReviewTap(review, callbackId, result);
+            await this.handleReviewTap(review, callbackId, result, sender);
             return;
         }
         const parsed = parseCallbackData(query["data"]);
@@ -2510,7 +2992,7 @@ export class TelegramChannel {
         // decides is whatever is still open on that delivery right now, which this
         // process knows and the callback bytes deliberately do not say.
         if (parsed.scope === "all") {
-            await this.handleDigestAll(parsed.decision, parsed.nonce, callbackId, result);
+            await this.handleDigestAll(parsed.decision, parsed.nonce, callbackId, result, sender);
             return;
         }
         // The resolution ladder (APRV-196). A tap is answered by the nonce when
@@ -2518,7 +3000,12 @@ export class TelegramChannel {
         // the log when neither is holding the action open.
         let delivery = this.deliveries.get(parsed.nonce);
         let viaStaleCopy = false;
-        if (delivery === undefined && parsed.actionRef !== null) {
+        // APRV-442. A card a refused tap disarmed stays dead: its bytes take no
+        // fallback to the fresh card the listener sends for the same request, so
+        // a redelivered or replayed refused tap reaches neither the gate nor the
+        // new card, exactly as it did before that card existed.
+        const refusedCard = delivery === undefined && this.refusedNonces.has(parsed.nonce);
+        if (delivery === undefined && parsed.actionRef !== null && !refusedCard) {
             // The pre-restart copy. Its nonce died with the process that issued it,
             // but the request it names is one THIS process has since re-delivered, so
             // the tap decides that request — on the live copy's message, which is
@@ -2529,18 +3016,21 @@ export class TelegramChannel {
             viaStaleCopy = delivery !== undefined;
         }
         if (delivery === undefined) {
-            if (parsed.actionRef !== null) {
+            if (parsed.actionRef !== null && !refusedCard) {
                 // Nothing open here for that action. Say what the log says, which is
                 // the only thing that knows: decided, lapsed, withdrawn, or unknown.
                 const described = this.describeAction?.(parsed.actionRef) ?? null;
                 await this.ignore(result, callbackId, "stale-copy", `no open delivery for action ref ${JSON.stringify(parsed.actionRef)} (an earlier copy of a request this listener is not holding open)`, described ?? TELEGRAM_STALE_UNKNOWN);
                 return;
             }
-            await this.ignore(result, callbackId, "unknown-callback", `no delivery for nonce ${JSON.stringify(parsed.nonce)} (a restarted listener forgets its buttons; the pending queue is re-sent on start)`, 
-            // Two ways to get here, and the reply has to serve both: a button this
-            // process never issued (a restart forgot it), and a button on a message
-            // this process has already annotated (APRV-113 forgets the nonce with
-            // the edit). Either way the message text is the thing to read.
+            await this.ignore(result, callbackId, "unknown-callback", refusedCard
+                ? `nonce ${JSON.stringify(parsed.nonce)} is on a card a refused tap disarmed (APRV-442); the request, if still pending, is on a newer card`
+                : `no delivery for nonce ${JSON.stringify(parsed.nonce)} (a restarted listener forgets its buttons; the pending queue is re-sent on start)`, 
+            // Three ways to get here, and the reply has to serve all of them: a
+            // button this process never issued (a restart forgot it), a button on a
+            // message this process has already annotated (APRV-113 forgets the
+            // nonce with the edit), and a button on a card a refused tap disarmed
+            // (APRV-442). Either way the message text is the thing to read.
             "This button is no longer live — read the message for the outcome, or the newest message for the request.");
             return;
         }
@@ -2552,6 +3042,7 @@ export class TelegramChannel {
             action_key: delivery.actionKey,
             decision: parsed.decision,
             deliveryId: delivery.deliveryId,
+            ...(sender === undefined ? {} : { sender }),
             ...(delivery.batchDeliveryId === undefined
                 ? {}
                 : { batchDeliveryId: delivery.batchDeliveryId }),
@@ -2580,6 +3071,9 @@ export class TelegramChannel {
             outcome = this.handler(decision);
         }
         catch (cause) {
+            // APRV-442: the card is about to be disarmed and nothing settled the
+            // request. Marked BEFORE the annotation, which forgets the nonces.
+            this.release(delivery, parsed.nonce);
             await this.annotateQuietly(delivery.deliveryId, delivery.actionKey, TELEGRAM_NOT_RECORDED, [
                 TELEGRAM_HANDLER_FAILED,
             ]);
@@ -2604,6 +3098,18 @@ export class TelegramChannel {
             // message, which is right in both directions: a terminal request has no
             // decision left to collect, and a still-pending one is re-delivered as a
             // fresh prompt by the next dispatch cycle.
+            //
+            // APRV-442. That re-delivery used to be a promise nothing kept: the
+            // disarm forgets the card's nonces, but the listener's own bookkeeping
+            // went on saying the request was on the phone, so the cycle never sent
+            // it again and the original card's action-reference fallback found
+            // nothing live. A wrong account's tap made the prompt dead until a
+            // restart. Releasing names this CARD as gone and nothing else; the cycle
+            // re-derives from the verified log whether the request is still pending
+            // before it offers a new one. Marked BEFORE the annotation, which forgets
+            // the nonces it records. The refusal itself, its record and its wording
+            // are untouched.
+            this.release(delivery, parsed.nonce);
             await this.annotateQuietly(delivery.deliveryId, delivery.actionKey, TELEGRAM_NOT_RECORDED, [
                 this.answerFor(outcome),
             ]);
@@ -2643,7 +3149,11 @@ export class TelegramChannel {
      * the same message would show the approver their own decisions arriving one
      * at a time, and would spend N Bot API calls to end in the same place.
      */
-    async handleDigestAll(decision, nonce, callbackId, result) {
+    async handleDigestAll(decision, nonce, callbackId, result, 
+    // APRV-324: one gesture, one sender, on every member it decides. An "all"
+    // tap is N decisions by one person, so each of the N carries the account
+    // the one tap came from.
+    sender) {
         const deliveryId = this.allNonces.get(nonce);
         const digest = deliveryId === undefined ? undefined : this.digests.get(deliveryId);
         if (digest === undefined) {
@@ -2667,6 +3177,7 @@ export class TelegramChannel {
                 decision,
                 deliveryId: digest.deliveryId,
                 batchDeliveryId: digest.batchDeliveryId,
+                ...(sender === undefined ? {} : { sender }),
                 ...(decision === "reject"
                     ? { note: `${TELEGRAM_REJECT_NOTE} (callback ${callbackId}, all)` }
                     : {}),
@@ -2771,7 +3282,11 @@ export class TelegramChannel {
      * and appends to a log, and a spinner that lasted a decision long is what
      * that task removed.
      */
-    async handleCheckpointTap(tap, callbackId, result) {
+    async handleCheckpointTap(tap, callbackId, result, 
+    // APRV-324 follow-up. A checkpoint signature is a human-only act and says
+    // this log's head is what this person saw, so it carries the account the
+    // tap came from exactly as a decision does.
+    sender) {
         const held = this.checkpointNonces.get(tap.nonce);
         if (held === undefined) {
             await this.ignore(result, callbackId, "unknown-callback", `checkpoint nonce ${JSON.stringify(tap.nonce)} was not issued by this process`, "This checkpoint prompt is from an earlier run. A fresh one is offered when the next is due.");
@@ -2784,7 +3299,11 @@ export class TelegramChannel {
             return;
         }
         await this.safeAnswer(callbackId, tap.sign ? "Heard — signing. The message will say what the log recorded." : "Not now.");
-        const response = await handler({ sign: tap.sign, head: held.head });
+        const response = await handler({
+            sign: tap.sign,
+            head: held.head,
+            ...(sender === undefined ? {} : { sender }),
+        });
         // Edited here rather than through `annotate`, which renders an action key
         // under its headline. A checkpoint has none, and an empty `<code></code>`
         // where a request's key belongs would be this channel implying a request.
@@ -2817,7 +3336,7 @@ export class TelegramChannel {
      * re-implement the rule. The one thing this method owns is the ARMING, which
      * is process memory that appends nothing.
      */
-    async handleReviewTap(tap, callbackId, result) {
+    async handleReviewTap(tap, callbackId, result, sender) {
         const deliveryId = this.reviewNonces.get(tap.nonce);
         const state = deliveryId === undefined ? undefined : this.reviewCards.get(deliveryId);
         if (state === undefined || state.settled !== null) {
@@ -2845,7 +3364,11 @@ export class TelegramChannel {
             const chosen = tap.choice === "deny" ? "denied" : "ok";
             state.denyArmed = chosen === "denied";
             await this.safeAnswer(callbackId, TELEGRAM_REVIEW_ACK);
-            await this.recordReview(state, { sampleSeq: state.card.sampleSeq, verdict: chosen }, result);
+            await this.recordReview(state, {
+                sampleSeq: state.card.sampleSeq,
+                verdict: chosen,
+                ...(sender === undefined ? {} : { sender }),
+            }, result);
             return;
         }
         const reaction = tap.choice;
@@ -2858,11 +3381,16 @@ export class TelegramChannel {
         const conflicts = verdict === "denied" && (reaction === "liked" || reaction === "loved");
         if (!conflicts && (reaction === "loved" || reaction === "disliked")) {
             await this.safeAnswer(callbackId, TELEGRAM_REVIEW_NOTE_TOAST);
-            await this.askForNote(state, verdict, reaction);
+            await this.askForNote(state, verdict, reaction, sender);
             return;
         }
         await this.safeAnswer(callbackId, TELEGRAM_REVIEW_ACK);
-        await this.recordReview(state, { sampleSeq: state.card.sampleSeq, verdict, reaction }, result);
+        await this.recordReview(state, {
+            sampleSeq: state.card.sampleSeq,
+            verdict,
+            reaction,
+            ...(sender === undefined ? {} : { sender }),
+        }, result);
     }
     /**
      * Send the ForceReply prompt a `loved` or `disliked` needs, and remember what
@@ -2879,7 +3407,7 @@ export class TelegramChannel {
      * one card, and the older prompt stops resolving so a late reply to it lands
      * nowhere rather than recording a grade the human moved on from.
      */
-    async askForNote(state, verdict, reaction) {
+    async askForNote(state, verdict, reaction, sender) {
         if (state.awaitingNote !== null)
             this.reviewNotePrompts.delete(state.awaitingNote.promptId);
         const lines = reviewNotePromptLines(reaction, verdict, state.card.fields.action_key.value);
@@ -2893,7 +3421,7 @@ export class TelegramChannel {
             reply_markup: { force_reply: true },
         });
         const promptId = String(sent.message_id);
-        state.awaitingNote = { promptId, verdict, reaction };
+        state.awaitingNote = { promptId, verdict, reaction, ...(sender === undefined ? {} : { sender }) };
         this.reviewNotePrompts.set(promptId, state.deliveryId);
     }
     /**
@@ -2928,6 +3456,19 @@ export class TelegramChannel {
         }
         const state = this.reviewCards.get(deliveryId);
         const pending = state?.awaitingNote ?? null;
+        // APRV-324 follow-up, and checked BEFORE the prompt is forgotten, so a
+        // reply from the wrong account costs the right one nothing. A note prompt
+        // is a ForceReply addressed to the person who armed the grade, and its
+        // words are recorded as that person's; a different account replying to it
+        // is answering a question nobody asked them.
+        const sender = senderOf(message, this.name);
+        if (pending !== null &&
+            pending.promptId === promptId &&
+            pending.sender !== undefined &&
+            (sender === undefined || sender.id !== pending.sender.id)) {
+            this.complain("approval: telegram ignored a review note: it replied to a prompt issued for a different account, and the prompt is still open for the account that armed it");
+            return true;
+        }
         this.reviewNotePrompts.delete(promptId);
         if (state === undefined || pending === null || pending.promptId !== promptId)
             return true;
@@ -2937,6 +3478,7 @@ export class TelegramChannel {
             verdict: pending.verdict,
             reaction: pending.reaction,
             note: text,
+            ...(sender === undefined ? {} : { sender }),
         }, result);
         return true;
     }
@@ -3079,9 +3621,20 @@ export class TelegramChannel {
     // -------------------------------------------------------------------------
     // Transport
     // -------------------------------------------------------------------------
-    /** Replace the token with a placeholder anywhere it appears in `text`. */
+    /**
+     * Replace every secret this channel holds with a placeholder in `text`.
+     *
+     * The bot token always, and since APRV-424 the webhook `secret_token` too,
+     * from the moment {@link registerWebhook} is handed it. Both are values that
+     * only ever travel TO the Bot API, so anything coming back that quotes one
+     * is a diagnostic about to print a credential.
+     */
     redact(text) {
-        return this.token.length === 0 ? text : text.split(this.token).join("<token redacted>");
+        let redacted = text;
+        for (const secret of this.secrets) {
+            redacted = redacted.split(secret.value).join(secret.label);
+        }
+        return redacted;
     }
     describe(cause) {
         return this.redact(cause instanceof Error ? cause.message : String(cause));