approval-md 0.3.0 → 0.4.0

package/dist/src/cli/channel-telegram.js

@@ -110,6 +110,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { isAbsolute, resolve as resolvePathSegments } from "node:path";
 import { HUMAN_ACTOR_ENV, resolveHumanActor } from "../core/attest.js";
+import { isProposalTask } from "../core/gate.js";
 import { assembleBatch } from "../channels/batch.js";
 import { recordChannelDecision, refusedDecisionLine, } from "../channels/contract.js";
 import { ageText, buildPendingQueue, } from "../channels/tagging.js";
@@ -118,7 +119,8 @@ import { actionRefOf, decidedLine, groupForDigest, isMessageNotModified, isTeleg
 import { openReviewCards } from "./audit-card.js";
 import { reviewSample } from "../core/audit.js";
 import { abandonedAfterMs, HOOK_DEFAULT_WAIT_MS, HOOK_RETRY_GRACE_MS, } from "../core/harness-wait.js";
-import { telegramDeliveryFor } from "../core/telegram-config.js";
+import { normaliseWebhookUrl, redactWebhookUrl, telegramDeliveryFor, } from "../core/telegram-config.js";
+import { reclaimDetail, takeChannelLease, } from "../core/channel-lease.js";
 import { loadPolicy } from "../core/policy-load.js";
 import { valueFindings } from "../core/instance.js";
 import { defaultSourceRunner } from "../core/env-file.js";
@@ -216,38 +218,164 @@ function env(name) {
     return value === undefined || value.trim().length === 0 ? null : value.trim();
 }
 /**
- * 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.
+ * Claim this listener's bot before it polls (APRV-390, extended by APRV-424).
+ *
+ * Three questions, in order, and each one has its own authority:
+ *
+ * 1. **Does anything else in THIS gate already hold the Telegram transport?**
+ *    A lockfile in the gate's own `daemon/` directory (`core/channel-lease.ts`)
+ *    answers it, and the answer is per PROCESS. This is the check the review of
+ *    APRV-424 added, and the hole it closes is the one neither of the other two
+ *    could see: an `approval up` long-polling and an `approval channel telegram
+ *    webhook` started in the same project pass both of them — `getWebhookInfo`
+ *    is empty while the poller is the one running, and the ownership registry
+ *    compares instance ids, which are equal because it IS the same instance —
+ *    and then each runs its own dispatch cycle over its own state against one
+ *    log, so every request reaches the phone twice under two nonces and only
+ *    one copy can resolve a tap.
+ * 2. **What is the Bot API delivering this bot's updates to?** `getWebhookInfo`
+ *    answers it, and it is the only thing that can see a webhook registered
+ *    from another machine. A webhook beats a poller outright — `getUpdates` is
+ *    refused while one is set — so any registration refuses a poller.
+ * 3. **Does another INSTANCE on this machine hold this bot?** `getMe` plus the
+ *    per-machine registry answers it (APRV-390's incident: two gates, one
+ *    token, two names, a 409 on every poll).
+ *
+ * ## An unreachable Bot API: fail-soft for a poller, fail-closed for a webhook
+ *
+ * A `getMe` or a `getWebhookInfo` 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. For a POLLER, refusing 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, and the HTTP 409 the loop
+ * already reports is the backstop. So the poller says what happened and starts.
+ *
+ * For the WEBHOOK VERB there is no such backstop, and the review of APRV-424
+ * turned this direction around. Its next act is `setWebhook`, which overwrites
+ * whatever registration exists without asking, so proceeding on an unknown
+ * answer is proceeding to take another host's taps with no error anywhere. A
+ * probe it could not make is therefore a refusal (`webhook-probe-failed`), and
+ * the operator retries or passes `--reclaim` deliberately.
  */
-export async function claimListenerBot(setup, report) {
+export async function claimListenerBot(setup, report, options = {}) {
+    const mode = options.mode ?? (options.webhookUrl === undefined ? "poll" : "webhook");
+    // The local, deterministic question first: it needs no network, and a
+    // refusal here is one an operator can act on without waiting for a round
+    // trip. Released again below if a later check refuses, so a refused start
+    // never leaves a lease behind for the next one to reclaim.
+    const leased = takeChannelLease(setup.logPath, mode, {
+        note: (message) => report(`approval: ${message}`),
+    });
+    if (!leased.ok) {
+        return {
+            ok: false,
+            code: leased.code,
+            message: leased.message,
+        };
+    }
+    if (leased.reclaimed !== null && leased.reclaimedBecause !== null) {
+        report(`approval: ${reclaimDetail(leased.reclaimed, leased.reclaimedBecause)}`);
+    }
+    /**
+     * Did THIS gate's own webhook runner die without removing its registration?
+     *
+     * The evidence is the lease this take just reclaimed: a record in this
+     * gate's own lockfile, written by a webhook runner, whose process is no
+     * longer the one holding it. A SIGKILL leaves exactly that, plus a
+     * registration at the url the dead process had registered, and without this
+     * every restart would refuse `webhook-registered` until an operator baked
+     * `--reclaim` into the unit file — which would retire finding 6's protection
+     * for good, in exchange for a crash recovery.
+     *
+     * It is deliberately narrow. Same gate (it is the same lockfile), same
+     * transport (a dead poller proves nothing about a registration), the process
+     * demonstrably GONE, and the url still has to match after normalisation.
+     * Anything else keeps refusing.
+     *
+     * "Gone" is the only reclaim reason that counts (third review, finding 2).
+     * The other two are reclaims on a judgement about a NUMBER rather than a
+     * death: `foreign` means a pid this process cannot signal, and `recycled`
+     * means a pid whose process started after the lease was written. Both are
+     * the right call for the lease, which only has to stop being held; neither
+     * is evidence that the webhook runner that registered this url has stopped
+     * running, and on a shared machine a foreign pid is as likely to be the
+     * OTHER host's live runner. So they keep the refusal and the `--reclaim`
+     * demand.
+     */
+    const ownWebhookDied = leased.reclaimed !== null &&
+        leased.reclaimed.mode === "webhook" &&
+        leased.reclaimedBecause === "gone";
+    const release = () => leased.lease.release();
+    const refuse = (code, message) => {
+        release();
+        return { ok: false, code, message };
+    };
     let identity;
     try {
         identity = await setup.channel.identify();
     }
     catch (cause) {
-        report(`approval: telegram getMe could not be reached (${cause instanceof Error ? cause.message : String(cause)}), so which bot this token names is unknown and no ownership was recorded; starting anyway`);
-        return { ok: true };
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        if (mode === "webhook") {
+            // Fail closed: see the module note above. `setWebhook` would overwrite a
+            // registration this process could not see.
+            return refuse("webhook-probe-failed", `telegram getMe could not be reached (${detail}), so which bot this token names and what is already receiving its updates are both unknown. This verb registers a webhook, and setWebhook overwrites whatever is registered without reporting it, so it does not run on an unknown answer: fix the connection and start again, or pass --reclaim to take the bot deliberately`);
+        }
+        report(`approval: telegram getMe could not be reached (${detail}), so which bot this token names is unknown and no ownership was recorded; starting anyway`);
+        return { ok: true, lease: leased.lease };
     }
     if (identity.id.length === 0) {
+        if (mode === "webhook") {
+            return refuse("webhook-probe-failed", "telegram getMe answered without a bot id, so which bot this token names is unknown. This verb registers a webhook over whatever is already registered, and will not do that on an unknown answer");
+        }
         report("approval: telegram getMe answered without a bot id, so no ownership was recorded; starting anyway");
-        return { ok: true };
+        return { ok: true, lease: leased.lease };
+    }
+    // APRV-424, and before the ownership claim: the registry answers "which
+    // process on THIS machine holds this bot", and the Bot API answers "what is
+    // this bot's updates going to at all". A webhook beats both — `getUpdates`
+    // is refused while one is set — so a listener started here would receive
+    // nothing whoever else is or is not running locally.
+    const hooked = await webhookOwner(setup);
+    if (hooked.state === "unknown") {
+        if (mode === "webhook") {
+            return refuse("webhook-probe-failed", `telegram getWebhookInfo could not be reached (${hooked.detail}), so whether another host's webhook holds this bot is unknown. setWebhook would overwrite it without saying so, and the displaced receiver would simply stop being posted to, so this verb refuses rather than guessing: try again, or pass --reclaim to register over whatever is there`);
+        }
+        // The poller's documented fail-soft (see the module note): what a missed
+        // probe costs is the clear refusal, and the 409 path is still there.
+        report(`approval: telegram getWebhookInfo could not be reached (${hooked.detail}), so whether a webhook holds this bot is unknown; starting anyway`);
+    }
+    if (hooked.state === "registered") {
+        const queued = hooked.pendingUpdateCount === 0
+            ? ""
+            : ` (${String(hooked.pendingUpdateCount)} update(s) are queued for it)`;
+        // Origin plus a redacted path, never the url as the Bot API spelled it:
+        // this is somebody else's registration, its path may itself be a bearer
+        // value (review finding 10), and the origin is what tells hosts apart.
+        const shown = redactWebhookUrl(hooked.url);
+        if (options.webhookUrl === undefined) {
+            return refuse("webhook-registered", `telegram ${identity.username} delivers its updates to a webhook at ${shown}, and the Bot API refuses getUpdates while one is set, so this listener would receive no tap at all${queued}. Long polling and a webhook are alternatives per bot: stop the \`approval channel telegram webhook\` process, which removes the webhook as it exits, or give this instance its own bot with \`approval setup channel telegram\``);
+        }
+        const mine = normaliseWebhookUrl(options.webhookUrl);
+        const theirs = normaliseWebhookUrl(hooked.url);
+        const same = mine !== null && theirs !== null && mine === theirs;
+        if (same && ownWebhookDied) {
+            // The restart case, and the only one that needs no flag: this gate's own
+            // webhook runner was killed without the chance to call `deleteWebhook`,
+            // and what is registered is the url it left behind.
+            report(`approval: the webhook at ${shown} is the one this gate's own runner registered before it died (its lease was reclaimed from pid ${String(leased.reclaimed?.pid ?? 0)}); re-registering the same url, which needs no --reclaim`);
+        }
+        else if (options.reclaim !== true) {
+            return refuse("webhook-registered", `telegram ${identity.username} already delivers its updates to a webhook at ${shown}${queued}. ${same
+                ? "That is the url this process was asked to register, which looks like a restart and may not be one: two hosts running one configuration both read this as their own, the second overwrites the first's secret_token, and from then on every real tap reaches the first host as a forgery"
+                : "This process was asked to register a different url, and a bot has exactly one webhook: registering would silently take the taps away from whatever is serving that one"}. Telegram allows one webhook per bot and keeps the last registration. Stop the other process, or pass --reclaim to register over it deliberately`);
+        }
+        else {
+            report(same
+                ? `approval: --reclaim: re-registering ${shown}, which is the url already registered for ${identity.username}`
+                : `approval: --reclaim: registering over the webhook at ${shown}; whatever is serving it stops being posted to, because Telegram keeps only the last registration for ${identity.username}`);
+        }
     }
     const claim = claimBot(setup.logPath, {
         channel: "telegram",
@@ -257,16 +385,28 @@ export async function claimListenerBot(setup, report) {
     });
     if (!claim.ok) {
         if (!setup.allowCrossInstance) {
-            return { ok: false, code: "bot-owned-elsewhere", message: claim.message };
+            return refuse("bot-owned-elsewhere", claim.message);
         }
         // The deliberate case. It says what it is doing, and it does NOT record a
         // second claim: the registry answers "who owns this bot", and two owners
         // is the state it exists to report rather than a state to write down.
         report(`approval: --allow-cross-instance: starting anyway — ${claim.message}`);
-        return { ok: true };
+        return { ok: true, lease: leased.lease };
     }
     report(`approval: telegram ${identity.username} (bot id ${identity.id}) is this instance's own; no update was consumed by this check`);
-    return { ok: true };
+    return { ok: true, lease: leased.lease };
+}
+async function webhookOwner(setup) {
+    let info;
+    try {
+        info = await setup.channel.webhookInfo();
+    }
+    catch (cause) {
+        return { state: "unknown", detail: cause instanceof Error ? cause.message : String(cause) };
+    }
+    return info.url.length === 0
+        ? { state: "none" }
+        : { state: "registered", url: info.url, pendingUpdateCount: info.pendingUpdateCount };
 }
 /**
  * What to append to a runtime 409, naming the other instance if one is known.
@@ -343,6 +483,54 @@ export const LISTEN_REFUSAL_CODES = [
      * which two gates are involved instead of an HTTP 409 loop.
      */
     "bot-owned-elsewhere",
+    /**
+     * This bot's updates are being delivered to a webhook (APRV-424).
+     *
+     * The two transports are alternatives per bot: the Bot API refuses
+     * `getUpdates` outright while a webhook is set, so a listener that started
+     * here would print a 409 every few seconds and receive not one tap. Refused
+     * BEFORE the first poll, in the same preflight and for the same reason
+     * `bot-owned-elsewhere` is, so the operator reads which transport owns the
+     * bot instead of a status code.
+     *
+     * Since the review of APRV-424 it carries a second, local source: the
+     * transport lease in this gate's own `daemon/` directory, when the process
+     * holding it is a webhook runner. Same fact, same repair, so the same code.
+     */
+    "webhook-registered",
+    /**
+     * A long-poll listener in THIS gate already holds the Telegram transport
+     * (APRV-424 review finding 1).
+     *
+     * The counterpart to `webhook-registered`, from the same lease. It is what
+     * the webhook verb meets when an `approval up` or an `approval channel
+     * telegram listen` is already running in the same project — the case
+     * `getWebhookInfo` cannot see (nothing is registered yet) and the ownership
+     * registry cannot see either (it is the same instance). Two of them on one
+     * log put every prompt on the phone twice, under two nonces, and only one
+     * copy can resolve a tap.
+     */
+    "telegram-poller-running",
+    /**
+     * The transport lease could not be taken at all (APRV-424 review finding 1).
+     *
+     * A `daemon/` directory that cannot be created, a lockfile that cannot be
+     * written. Unlike the bot registry, whose absence is the status quo, this
+     * file is the only thing keeping one gate from running two transports, so a
+     * gate that cannot hold one does not start.
+     */
+    "telegram-lease-unavailable",
+    /**
+     * The webhook verb could not learn what already holds this bot (APRV-424
+     * review finding 8).
+     *
+     * `getMe` or `getWebhookInfo` failed, and the next act would have been a
+     * `setWebhook` that overwrites a registration nobody saw. A poller keeps its
+     * fail-soft on the same failure, because an unreachable Bot API is also a
+     * `getUpdates` that cannot conflict and the HTTP 409 loop is its backstop;
+     * this verb has no backstop, so it refuses.
+     */
+    "webhook-probe-failed",
 ];
 /**
  * Everything that can fail without touching the network, in order.
@@ -903,7 +1091,14 @@ function terminalDeliveries(setup, state, now) {
         // `granted`, a declined one `rejected`, a superseded one `withdrawn`
         // (a newer proposal is the live question now), and a lapsed one `expired`.
         if (isAttestationActionKey(actionKey)) {
-            const proposal = proposalRecords(read.records).find((entry) => entry.action_key === actionKey);
+            // The LATEST proposal under this key (APRV-455 refuter M2). Every
+            // proposal of one policy hash shares `policy.attest:<sha256>`, and since
+            // a relay may propose bytes already in force a second proposal of an
+            // attested hash is ordinary: settling the live one by the first one's
+            // answer would retire an open prompt as "granted" by somebody else.
+            const proposal = proposalRecords(read.records)
+                .filter((entry) => entry.action_key === actionKey)
+                .at(-1);
             const derived = proposal === undefined ? null : proposalState(read.records, proposal.seq, now);
             if (derived === null || derived.state === "open")
                 continue;
@@ -1000,11 +1195,17 @@ export async function dispatchPending(setup, streams, state, now) {
         digests: [],
         pruned: [],
     };
-    const queue = buildPendingQueue(setup.logPath, setup.tagOptions, now);
-    if (!queue.ok) {
-        result.queueError = { code: queue.code, message: queue.message };
+    const built = buildPendingQueue(setup.logPath, setup.tagOptions, now);
+    if (!built.ok) {
+        result.queueError = { code: built.code, message: built.message };
         return result;
     }
+    // APRV-425. One ordering, applied once, so every pass below reads the same
+    // sequence: the annotation sweep, the paced walkthrough's seeding, the
+    // collapse, and the digest grouping. `orderPending` drops nothing and decides
+    // nothing, so the SET this cycle works from is `buildPendingQueue`'s exactly;
+    // what changes is which request an approver meets first.
+    const queue = { ...built, requests: orderPending(built.requests, now) };
     // APRV-106 (withdrawal) generalized by APRV-113 (every terminal state),
     // before the sends. A request this process delivered and that the log now
     // says is settled — granted or rejected at any surface, revoked, expired by
@@ -1080,6 +1281,27 @@ export async function dispatchPending(setup, streams, state, now) {
         forget(state, actionKey);
         result.pruned.push({ action_key: actionKey, reason: "stale" });
     }
+    // APRV-442. A tap the gate refused (a wrong account's, `sender-unmapped`, is
+    // the case that found this) disarms its card, and the channel says which
+    // cards it disarmed that way. The card is gone; the REQUEST is not, unless
+    // the verified log says so. A released key the log still calls pending loses
+    // its delivery bookkeeping here, so the sends below offer it again as a
+    // fresh card in this same cycle. One the log has settled is left exactly
+    // where it is, for the terminal annotation pass above to finish on the next
+    // cycle as it always has. Nothing about the refusal changes: it was recorded
+    // by the gate before this ran, and the new card's buttons reach the same gate.
+    for (const actionKey of setup.channel.takeReleased()) {
+        if (!pendingNow.has(actionKey) || !state.delivered.has(actionKey))
+            continue;
+        forget(state, actionKey);
+        // Under `paced` the released card WAS the question in front of the
+        // approver, and a selection that still believed it was showing would
+        // decline to show anything. Clearing it lets the walkthrough re-offer the
+        // request, which is the first pending key in its order not on the phone.
+        if (state.paced.current?.includes(actionKey) === true)
+            state.paced.current = null;
+        result.pruned.push({ action_key: actionKey, reason: "released" });
+    }
     for (const skipped of queue.skipped) {
         const token = `${skipped.action_key}:${skipped.code}`;
         if (state.warned.has(token))
@@ -1405,6 +1627,119 @@ export const COLLAPSE_STALE_AFTER_MS = abandonedAfterMs(HOOK_DEFAULT_WAIT_MS, HO
  * save nobody a message. A flood starts at two.
  */
 const COLLAPSE_MIN = 2;
+/**
+ * Pending requests a NEWER pending request has superseded (APRV-425).
+ *
+ * Two requests naming the same payload bytes and the same class are two askings
+ * of one question, and only the newer one has an asker. The shape that produces
+ * them is APRV-287's own: a hook whose wait ran out leaves its request open for
+ * the retry grace, the grace runs out, the hook withdraws it on its NEXT
+ * invocation — and if that next invocation never comes while a later session
+ * asks the same thing, both sit in the queue. Dogfooding produced exactly this
+ * complaint (APRV-118): a live prompt buried behind dead ones, and an approver
+ * rejecting the one they wanted.
+ *
+ * Keyed by `(payload_hash, class)` and not by task, because the task id a
+ * harness adapter mints is fresh per tool call (SPEC.md §10.2), so two askings
+ * of one command never share one. The bytes and the class are what a decision
+ * binds to, which is what makes them the right identity here.
+ *
+ * Computed from the pending set alone, which is re-derived from the verified log
+ * every cycle, so this decides nothing and remembers nothing. A superseded
+ * request is COLLAPSED, never closed: it stays pending in the log, listable, and
+ * decidable from any copy already delivered. Only a human's decision or the
+ * requester's own withdrawal ends it.
+ */
+export function supersededPending(requests) {
+    const newest = new Map();
+    const superseded = new Set();
+    for (const request of requests) {
+        // An attestation prompt is never a duplicate of anything: its identity is
+        // the policy bytes it proposes, two proposals of the same bytes are refused
+        // upstream, and one that reached here is the live one.
+        if (request.policy_diff !== undefined)
+            continue;
+        // APRV-445 refutation (S2). A proposal is its own asking, held for days by
+        // design and keyed by the intention it names; another request over the
+        // same bytes is not a newer copy of it, and it is not a newer copy of one.
+        if (isProposalTask(request.task.value))
+            continue;
+        const identity = JSON.stringify([request.payload_hash.value, request.class.value]);
+        const key = request.action_key.value;
+        const at = Date.parse(request.requested_ts.value);
+        const previous = newest.get(identity);
+        if (previous === undefined) {
+            newest.set(identity, { key, at: Number.isNaN(at) ? 0 : at });
+            continue;
+        }
+        // Later wins, and an unreadable instant loses: a request whose age cannot be
+        // established is not the one to keep in front of an approver. Ties go to the
+        // one later in log order, which is the one the list already put second.
+        if (Number.isNaN(at) || at < previous.at) {
+            superseded.add(key);
+            continue;
+        }
+        superseded.add(previous.key);
+        newest.set(identity, { key, at });
+    }
+    return superseded;
+}
+/**
+ * The pending set in the order an approver should meet it (APRV-425).
+ *
+ * Three rules, in this order, and each is a complaint from running the gate:
+ *
+ * 1. **Attestation prompts last.** `buildPendingQueue` puts them there on
+ *    purpose: a policy amendment changes the rules every entry above it was
+ *    routed by, so an approver reading top to bottom answers the questions asked
+ *    under the current policy before changing what the current policy is. That
+ *    placement is not this function's to relitigate, so proposals are lifted
+ *    out, ordered among themselves by nothing at all (log order), and put back
+ *    at the end.
+ * 2. **Live requests first, newest first.** Live means younger than
+ *    {@link COLLAPSE_STALE_AFTER_MS}, the hook's wait plus its retry grace,
+ *    which is the same boundary the collapse uses — one number, one meaning of
+ *    "somebody may still be holding this". Newest first because the newest is
+ *    the one most likely to have a tool call blocked on it right now, and the
+ *    observed failure was a live prompt buried behind dead ones.
+ * 3. **Stale requests after them, oldest first.** They are what the collapse
+ *    takes on a first cycle, and where the collapse does not apply (fewer than
+ *    {@link COLLAPSE_MIN} of them) oldest-first is the order to work through a
+ *    backlog in.
+ *
+ * Stable inside each bucket, so log order breaks every tie and the result is
+ * deterministic for one log and one instant. It is an ORDER and nothing else:
+ * no request is dropped, none is decided, and the set that comes out is the set
+ * that went in.
+ */
+export function orderPending(requests, now) {
+    const nowMs = Date.parse(now);
+    if (Number.isNaN(nowMs))
+        return requests;
+    const proposals = [];
+    const live = [];
+    const stale = [];
+    requests.forEach((request, index) => {
+        if (request.policy_diff !== undefined) {
+            proposals.push(request);
+            return;
+        }
+        const parsed = Date.parse(request.requested_ts.value);
+        // An unreadable instant is treated as ancient, which sorts it with the
+        // requests nobody is waiting on. That is the strict side: a request whose
+        // age cannot be established must not displace one whose age is known.
+        const at = Number.isNaN(parsed) ? 0 : parsed;
+        // APRV-445 refutation (S2): a proposal waits on a human for as long as its
+        // TTL says (days), and its requester polls rather than blocks, so the
+        // hook's wait-plus-grace boundary says nothing about whether anyone is
+        // still holding it. It is always live.
+        const stalePosition = nowMs - at >= COLLAPSE_STALE_AFTER_MS && !isProposalTask(request.task.value);
+        (stalePosition ? stale : live).push({ request, at, index });
+    });
+    live.sort((a, b) => b.at - a.at || a.index - b.index);
+    stale.sort((a, b) => a.at - b.at || a.index - b.index);
+    return [...live.map((entry) => entry.request), ...stale.map((entry) => entry.request), ...proposals];
+}
 /**
  * A DURATION in words, which is not what {@link ageText} renders.
  *
@@ -1419,8 +1754,17 @@ function durationText(ms) {
     const minutes = Math.round(ms / 60_000);
     return `${String(minutes)}m`;
 }
-/** The computed lines a collapsed re-delivery leads with (APRV-287). */
-export function staleLines(requests, now) {
+/**
+ * The computed lines a collapsed re-delivery leads with (APRV-287).
+ *
+ * `superseded` is the subset a newer pending request replaced (APRV-425), and
+ * the first line states the split rather than claiming every member is old.
+ * Before this the line said "all older than the hook's wait plus its retry
+ * grace", which stopped being true the moment the collapse widened: a message
+ * that overstates what it collapsed is the stale-documentation failure in
+ * message form, and this one is read by the person deciding.
+ */
+export function staleLines(requests, now, superseded = new Set()) {
     const nowMs = Date.parse(now);
     const ages = requests
         .map((request) => nowMs - Date.parse(request.requested_ts.value))
@@ -1431,18 +1775,25 @@ export function staleLines(requests, now) {
         const cls = request.class.value;
         tally.set(cls, (tally.get(cls) ?? 0) + 1);
     }
+    const replaced = requests.filter((request) => superseded.has(request.action_key.value)).length;
+    const abandoned = requests.length - replaced;
+    const why = replaced === 0
+        ? `all older than the hook's ${durationText(HOOK_DEFAULT_WAIT_MS)} wait plus its ${durationText(HOOK_RETRY_GRACE_MS)} retry grace`
+        : abandoned === 0
+            ? "all superseded by a newer pending request for the same bytes and class"
+            : `${String(abandoned)} older than the hook's ${durationText(HOOK_DEFAULT_WAIT_MS)} wait plus its ${durationText(HOOK_RETRY_GRACE_MS)} retry grace, ${String(replaced)} superseded by a newer pending request for the same bytes and class`;
     return [
-        `${String(requests.length)} pending requests, all older than the hook's ${durationText(HOOK_DEFAULT_WAIT_MS)} wait plus its ${durationText(HOOK_RETRY_GRACE_MS)} retry grace`,
+        `${String(requests.length)} pending requests, ${why}`,
         `oldest: ${oldest === null ? "unknown age" : ageText(oldest)}`,
         `classes: ${[...tally.entries()]
             .map(([cls, count]) => (count === 1 ? cls : `${cls} ×${String(count)}`))
             .join(", ")}`,
-        "collapsed into this one message because the tool calls that asked have stopped waiting; a decision on any of them can still authorize an identical retry",
+        "collapsed into this one message because nothing is waiting on them; each one stays pending in the log, and a decision on any of them can still authorize an identical retry",
     ];
 }
 /**
  * Put the requests nobody is waiting on into ONE message, and hand back the
- * ones that still get a message each (APRV-287).
+ * ones that still get a message each (APRV-287, widened by APRV-425).
  *
  * Called on a process's first cycle only, which is exactly a daemon start or a
  * listener reconnect. Everything it does is bookkeeping in the sense SPEC.md
@@ -1450,7 +1801,50 @@ export function staleLines(requests, now) {
  * so a summary that fails to send, or a process that forgets it sent one,
  * degrades to showing those requests again, and never to a pending request
  * nobody is shown.
+ *
+ * ## Two ways in, one exit (APRV-425)
+ *
+ * A request is collapsed when it is older than the hook's wait plus its retry
+ * grace (nobody is holding it), or when a NEWER pending request names the same
+ * payload bytes and class ({@link supersededPending} — the newer one is the live
+ * asking, whatever the age of either). The second is what answers the observed
+ * complaint that a live prompt arrives buried behind dead ones.
+ *
+ * ## This is where the sent-record is rebuilt from the log (AC3)
+ *
+ * Every collapsed member is written into `state.delivered` and `state.sentAtMs`
+ * below, and the set it is written from is the pending set re-derived from the
+ * verified log. That is the whole of the rebuilding, and it is deliberately not
+ * a second mechanism: the log is the only place the question "what is pending"
+ * is answered.
+ *
+ * What it is NOT is evidence of delivery, and the difference is load-bearing.
+ * Nothing reads this record to conclude that an approver saw anything: a
+ * collapsed request stays pending in the log, is listed by `/queue`, and is
+ * decidable from any copy already delivered, because APRV-196 made
+ * `callback_data` carry a restart-stable action ref so a button on a
+ * pre-restart copy still decides the request. Lose the record and the next
+ * cycle shows the requests again, which is the degradation SPEC.md §10.3
+ * requires and the one this code takes.
+ */
+/**
+ * The members a first-cycle collapse would put into one message: stale or
+ * superseded, and never a proposal (APRV-445 refutation, S2). Proposals are
+ * long-lived by design, so after a six-minute outage every one of them would
+ * otherwise land in one digest whose only bulk answer is reject-all.
  */
+export function collapsibleStale(undecided, now, superseded = supersededPending([...undecided])) {
+    const nowMs = Date.parse(now);
+    if (Number.isNaN(nowMs))
+        return [];
+    return undecided.filter((request) => {
+        if (isProposalTask(request.task.value))
+            return false;
+        const at = Date.parse(request.requested_ts.value);
+        const age = Number.isNaN(at) ? 0 : nowMs - at;
+        return age >= COLLAPSE_STALE_AFTER_MS || superseded.has(request.action_key.value);
+    });
+}
 async function collapseStale(setup, streams, state, result, undecided, now) {
     const nowMs = Date.parse(now);
     if (Number.isNaN(nowMs))
@@ -1459,12 +1853,17 @@ async function collapseStale(setup, streams, state, result, undecided, now) {
         const at = Date.parse(request.requested_ts.value);
         return Number.isNaN(at) ? 0 : nowMs - at;
     };
-    const stale = undecided.filter((request) => age(request) >= COLLAPSE_STALE_AFTER_MS);
+    // Computed over the WHOLE pending set rather than over `undecided`, so a
+    // request this process has already delivered still supersedes an older twin.
+    const superseded = supersededPending(undecided);
+    const stale = collapsibleStale(undecided, now, superseded);
     if (stale.length < COLLAPSE_MIN)
         return undecided;
     let delivered = null;
     try {
-        delivered = await setup.channel.notifyStale(stale, { lines: staleLines(stale, now) });
+        delivered = await setup.channel.notifyStale(stale, {
+            lines: staleLines(stale, now, superseded),
+        });
     }
     catch (cause) {
         delivered = null;
@@ -1673,7 +2072,7 @@ function report(setup, streams, digestId, members) {
  * Report a steady-state cycle's problems on stderr. Startup reports its own,
  * as exit codes, in {@link runListener}.
  */
-function reportCycle(result, streams) {
+export function reportCycle(result, streams) {
     if (result.queueError !== undefined) {
         streams.err(`approval: telegram cannot read the pending queue (${result.queueError.code}): ${result.queueError.message} — retrying next cycle\n`);
     }
@@ -2060,7 +2459,9 @@ clock = () => new Date().toISOString()) {
             // and `/queue` is the verb that says what that is. Appended rather than
             // interleaved, because the two lists answer different questions: one is
             // what is waiting on the approver, the other what already happened.
-            const lines = queueLines(queue.requests, now, state.paced.current ?? []);
+            // APRV-425: the SAME ordering the dispatch cycle uses, because `/queue` is
+            // the approver asking what is waiting and two orders would be two answers.
+            const lines = queueLines(orderPending(queue.requests, now), now, state.paced.current ?? []);
             const built = openReviewCards(setup.logPath);
             if (built.ok && built.cards.length > 0)
                 lines.push(...reviewSummaryLines(built.cards, now));
@@ -2125,7 +2526,24 @@ clock = () => new Date().toISOString()) {
  * 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 function startListener(setup, streams) {
+/**
+ * Give the channel every handler the runtime answers a gesture with, and hand
+ * back the fresh dispatch bookkeeping (APRV-424).
+ *
+ * Extracted from {@link startListener} so the webhook runner wires the SAME
+ * four handlers rather than a second set that looks like them. This is the
+ * CLI-side half of the property APRV-424 is about: the transport decides where
+ * an update arrives, and nothing else. A tap that arrives by webhook is
+ * recorded by `handlerFor`'s `recordChannelDecision` — the same actor, the
+ * same sender resolution, the same gate — because it is the same function
+ * object, registered here.
+ *
+ * A FRESH {@link DispatchState} per call, which is the whole of the restart
+ * story: a supervisor that restarts a fallen runner re-derives the pending
+ * queue from the verified log and re-sends everything still pending. A
+ * duplicate on the phone, never a silence.
+ */
+export function wireListener(setup, streams) {
     const { channel } = setup;
     channel.onDecision(handlerFor(setup, streams));
     // APRV-257. Registered unconditionally, because whether a checkpoint is ever
@@ -2156,6 +2574,11 @@ export function startListener(setup, streams) {
     if (setup.delivery === "paced") {
         channel.onCommand(commandHandlerFor(setup, streams, state));
     }
+    return state;
+}
+export function startListener(setup, streams) {
+    const { channel } = setup;
+    const state = wireListener(setup, streams);
     let stopping = false;
     const stop = () => {
         stopping = true;
@@ -2218,6 +2641,11 @@ async function runListener(setup, streams) {
     finally {
         process.off("SIGINT", stop);
         process.off("SIGTERM", stop);
+        // The transport lease goes back on every exit, clean or not (APRV-424
+        // review finding 1). A listener that crashed leaves a lockfile whose pid
+        // is gone and the next taker reclaims it; a listener that stopped politely
+        // leaves nothing to reclaim.
+        claimed.lease.release();
     }
     switch (outcome.kind) {
         case "stopped":
@@ -2352,6 +2780,15 @@ export function commandTelegram(argv, streams, cwd) {
     switch (sub) {
         case "listen":
             return commandTelegramListen(rest, streams, cwd);
+        case "webhook":
+            // APRV-424, and a DYNAMIC import on purpose. The webhook runner reaches
+            // back into this module for `prepareListen`, `wireListener` and
+            // `dispatchPending` — it is the same listener with another arrival — so
+            // a static import here would close the dispatcher/dispatched circle.
+            // An ESM cycle is not a compile error; it is a binding that is
+            // `undefined` in one direction on the day initialisation order changes.
+            // `cli/serve.ts` and `cli/mcp.ts` state the same rule.
+            return import("./channel-telegram-webhook.js").then(({ commandTelegramWebhook }) => commandTelegramWebhook(rest, streams, cwd));
         case "health":
             return commandTelegramHealth(rest, streams, cwd);
         default: