approval-md 0.3.0 → 0.4.0

package/dist/src/channels/telegram.js

@@ -34,6 +34,24 @@
  * 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
@@ -389,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
 // ---------------------------------------------------------------------------
@@ -1572,6 +1597,37 @@ export function isPollConflict(cause) {
         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;
@@ -1647,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,
@@ -1671,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;
@@ -1933,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,
@@ -1994,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);
@@ -2092,6 +2207,7 @@ export class TelegramChannel {
             actionRef: actionRefOf(actionKey),
             deliveryId: sent.deliveryId,
             deliveredAtMs: this.now(),
+            windowMs: this.retentionWindowMs(request),
             ...(batchDeliveryId === undefined ? {} : { batchDeliveryId }),
         });
         return {
@@ -2132,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).
@@ -2166,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;
@@ -2188,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;
         }
@@ -2201,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);
@@ -2311,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).
      *
@@ -2379,6 +2573,7 @@ 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;
         /**
@@ -2447,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
@@ -2458,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).
@@ -2676,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
@@ -2687,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;
         }
@@ -2739,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,
             ]);
@@ -2763,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),
             ]);
@@ -3274,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));