approval-md 0.2.0 → 0.4.0

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

@@ -14,12 +14,18 @@
  *    are read here and passed to the channel as values (SPEC.md §5.1: policy
  *    carries the env-var *names*, never the secrets). Nothing in `channels/`
  *    touches `process.env`.
- * 2. **It declares who is approving.** The decision is recorded against the
- *    human actor from `--as` / `APPROVAL_HUMAN`, never against anything the
- *    callback carried. SPEC.md §11: identity in v0.1 is config-declared, the
- *    trust boundary is the local machine, and everyone who can reach the
- *    configured chat can approve as that actor. This is stated in `--help`
- *    because an operator has to be able to see it without reading the source.
+ * 2. **It declares the identity the process itself acts under.** `--as` /
+ *    `APPROVAL_HUMAN` is what this listener is, and it is what a decision is
+ *    recorded as whenever the policy maps no sender for this channel: SPEC.md
+ *    §11's config-declared identity, where the trust boundary is the local
+ *    machine and everyone who can reach the configured chat can approve as that
+ *    actor. Since APRV-324 a policy MAY map Telegram account ids to approvers,
+ *    and then the decision is recorded against the person the operator attested
+ *    the tapping account to, and an unmapped account is refused rather than
+ *    recorded as this listener. Either way the choosing happens in
+ *    `channels/contract.ts` against the attested policy, never here and never
+ *    in the channel. Both settings are stated in `--help` because an operator
+ *    has to be able to see which one they are in without reading the source.
  * 3. **It holds the token.** A grant mints a single-use execution token;
  *    `recordChannelDecision` returns it to *this* handler, which prints it on
  *    **stdout** and never hands it back to the channel. It is never sent to
@@ -104,16 +110,24 @@
 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, } from "../channels/contract.js";
+import { recordChannelDecision, refusedDecisionLine, } from "../channels/contract.js";
 import { ageText, buildPendingQueue, } from "../channels/tagging.js";
 import { checkpointOfferFor, checkpointPromptLines, checkpointSignedLines, signCheckpointOffer, } from "./checkpoint-tap.js";
-import { actionRefOf, decidedLine, groupForDigest, isMessageNotModified, isTelegramTerminalState, TelegramChannel, telegramChatEnvFor, telegramTokenEnvFor, TELEGRAM_NOT_RECORDED, TELEGRAM_REVIEW_DENIED, TELEGRAM_REVIEW_RECORDED, TELEGRAM_TERMINAL_HEADLINES, utcClock, } from "../channels/telegram.js";
+import { actionRefOf, decidedLine, groupForDigest, isMessageNotModified, isTelegramTerminalState, TelegramChannel, telegramChatEnvFor, telegramTokenEnvFor, TELEGRAM_NOT_RECORDED, TELEGRAM_REVIEW_DENIED, TELEGRAM_REVIEW_RECORDED, TELEGRAM_DEFAULT_API_BASE, TELEGRAM_TERMINAL_HEADLINES, utcClock, } from "../channels/telegram.js";
 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";
+import { claimBot, describeOwners, otherOwnersOf, ownedBot, } from "../core/channel-owner.js";
+import { actorForSender, recordedSenderFor, senderKeyFrom, } from "../core/sender-identity.js";
+import { recordRefusedGesture, } from "../core/gesture-refusal.js";
+import { attestationRefusal, checkAttestation } from "../core/attest.js";
 import { promptLayoutFor } from "../core/prompt-layout.js";
 import { passphraseEnvFor } from "../core/vault.js";
 import { isAttestationActionKey, proposalRecords, proposalState, } from "../core/policy-proposal.js";
@@ -136,6 +150,8 @@ const LISTEN_FLAGS = {
     "--api-base": "string",
     "--poll-timeout": "string",
     "--once": "boolean",
+    /** APRV-390: start on a credential this instance did not configure. */
+    "--allow-cross-instance": "boolean",
     "--gloss": "boolean",
     "--no-gloss": "boolean",
     "--gloss-provider": "string",
@@ -201,6 +217,215 @@ function env(name) {
     const value = process.env[name];
     return value === undefined || value.trim().length === 0 ? null : value.trim();
 }
+/**
+ * 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, 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) {
+        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, 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",
+        botId: identity.id,
+        username: identity.username,
+        apiBase: setup.apiBase,
+    });
+    if (!claim.ok) {
+        if (!setup.allowCrossInstance) {
+            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, 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, 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.
+ *
+ * Read at the moment of the conflict rather than captured at start-up, because
+ * the other gate may have claimed the bot in between: the registry is the only
+ * thing that knows, and it is cheap to re-read.
+ */
+export function conflictAdviceFor(setup) {
+    return () => {
+        const mine = ownedBot(setup.logPath, "telegram");
+        if (mine === null)
+            return null;
+        const others = otherOwnersOf(setup.logPath, mine.botId, mine.apiBase);
+        return others.length === 0
+            ? `this instance is ${mine.instanceHome} (instance ${mine.instanceId}) on ${mine.username}, and nothing else on this machine has claimed it — the other poller is on another machine, or was started outside this runtime`
+            : `${mine.instanceHome} (instance ${mine.instanceId}) and ${describeOwners(others)} have both claimed ${mine.username}; stop one of them`;
+    };
+}
 function payloadSource(resolved) {
     if (resolved === null)
         return { ok: true, source: undefined };
@@ -243,6 +468,69 @@ export const LISTEN_REFUSAL_CODES = [
     "log-unreadable",
     /** `--payloads` did not hold a JSON object of action key -> payload. */
     "payloads-unreadable",
+    /**
+     * A credential variable holds a value this instance did not configure
+     * (APRV-390): it was exported before the process started and is not this
+     * instance's own `approval env` export, or `.approval/env` names another
+     * instance's keystore item. Refused rather than warned since APRV-390 — the
+     * warning is what let a demo gate spend an evening on the production bot.
+     * `--allow-cross-instance` is the deliberate case.
+     */
+    "cross-instance-credential",
+    /**
+     * `getMe` named a bot another instance on this machine has already claimed
+     * (APRV-390). Refused BEFORE the first `getUpdates`, so the operator reads
+     * which two gates are involved instead of an HTTP 409 loop.
+     */
+    "bot-owned-elsewhere",
+    /**
+     * 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.
@@ -280,6 +568,35 @@ export function prepareListen(request) {
             message: `telegram is not configured: ${missing.join(" and ")} ${missing.length === 1 ? "is" : "are"} unset or empty (both ${tokenEnv} and ${chatEnv} are required; APPROVAL.md carries only their names)`,
         };
     }
+    // APRV-390. WHOSE credentials are these? `instanceFindings` answers from
+    // names alone — no value is read, compared or printed — and until this task
+    // its answer was a warning `approval up` printed on the way past. It is a
+    // refusal now. The incident it is named after is a demo gate that started on
+    // the primary's exported token and long-polled the primary's bot: the
+    // warning was on the operator's terminal the whole time, above a process
+    // that had already started. An override exists because feeding a daemon from
+    // a shell profile is a deliberate, supported thing to do; what was missing
+    // is that it now has to be said out loud.
+    //
+    // `valueFindings` and not `instanceFindings`: this is the one caller that is
+    // about to USE the values, so it is allowed to resolve the file and compare
+    // (APRV-390, second round). Comparing is what tells a stale export — the
+    // shell holding a token the keychain has since replaced, which `approval env`
+    // will never override — from an honest one, and what stops the correct `eval
+    // "$(approval env)"` ritual being reported as a finding. `approval doctor`
+    // keeps the name-only rule, because a diagnostic may not block on an unlock
+    // dialog. No value is printed here or anywhere below.
+    const crossInstance = valueFindings(request.logPath, policyLoad, defaultSourceRunner);
+    if (crossInstance.length > 0 && request.allowCrossInstance !== true) {
+        const stale = crossInstance.some((finding) => finding.kind === "stale-export");
+        return {
+            ok: false,
+            code: "cross-instance-credential",
+            message: `${crossInstance.map((finding) => finding.detail).join("; ")}. ${stale
+                ? "A stale export is why a token re-stored in the keystore can still answer 401: `approval env` never overrides a variable this shell has already exported."
+                : "Two gates on one bot token both long-poll it, their getUpdates offsets acknowledge each other's updates, and an approval tap is answered by whichever listener asked first."} Fix it with one of: \`unset ${crossInstance.map((finding) => finding.variable).join(" ")}\` and then \`eval "$(approval env)"\` in this shell; a fresh shell that has never exported it; or \`approval setup channel telegram\` to give this instance its own bot. Pass --allow-cross-instance to start anyway`,
+        };
+    }
     const actor = resolveHumanActor(request.as === null ? {} : { actor: request.as });
     if (actor === null) {
         return {
@@ -342,6 +659,10 @@ export function prepareListen(request) {
             // asks of the policy file, and a policy that failed to load leaves the
             // default (paced) in force rather than a mode nobody chose.
             delivery: telegramDeliveryFor(policyLoad),
+            // APRV-390. Empty unless --allow-cross-instance let a finding through.
+            crossInstance,
+            allowCrossInstance: request.allowCrossInstance === true,
+            apiBase: request.apiBase ?? TELEGRAM_DEFAULT_API_BASE,
             gateOptions: { policy: request.policy },
             tagOptions: {
                 policy: request.policy,
@@ -458,6 +779,8 @@ function setUp(argv, streams, cwd) {
         pollTimeout: stringFlag(flags, "--poll-timeout"),
         once: boolFlag(flags, "--once"),
         json,
+        // APRV-390.
+        allowCrossInstance: boolFlag(flags, "--allow-cross-instance"),
         log: (message) => streams.err(`${message}\n`),
         // APRV-144, on by default, `--no-gloss` to turn it off (APRV-197).
         //
@@ -768,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;
@@ -865,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
@@ -945,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))
@@ -1270,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.
  *
@@ -1284,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))
@@ -1296,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
@@ -1315,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))
@@ -1324,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;
@@ -1538,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`);
     }
@@ -1569,7 +2103,10 @@ function handlerFor(setup, streams) {
             })}\n`);
         }
         else if (result.outcome.ok) {
-            streams.out(`${decision.decision === "grant" ? "granted" : "rejected"} ${decision.action_key} (seq ${result.outcome.record.seq}) by ${setup.actor} via telegram\n`);
+            // APRV-324: the actor off the RECORD, not the one this process was
+            // launched with. Under a sender mapping they differ, and the line a human
+            // reads on the operator's terminal has to say who the log says decided.
+            streams.out(`${decision.decision === "grant" ? "granted" : "rejected"} ${decision.action_key} (seq ${result.outcome.record.seq}) by ${result.outcome.record.actor} via telegram\n`);
         }
         else {
             streams.err(`approval: telegram decision refused (${result.outcome.code}): ${result.outcome.message}\n`);
@@ -1606,8 +2143,101 @@ function handlerFor(setup, streams) {
  * request here to reject, and a checkpoint that is owed is a warning at every
  * layer and a refusal at none.
  */
+/**
+ * Where this listener's policy lives, as `loadPolicy` wants it (APRV-324
+ * follow-up).
+ *
+ * The same location every gate operation this process performs resolves,
+ * because the handlers below ask the policy who a sender is and the gate asks
+ * it what a class resolves to, and two different files answering those two
+ * questions would be a listener enforcing one policy and attributing under
+ * another.
+ */
+function policyLoadOptions(setup) {
+    const policy = setup.gateOptions.policy;
+    if (policy?.file !== undefined)
+        return { file: policy.file };
+    if (policy?.dir !== undefined)
+        return { dir: policy.dir };
+    return {};
+}
+function senderIdentityFor(setup, sender) {
+    const load = loadPolicy(policyLoadOptions(setup));
+    if (sender === undefined)
+        return { ok: true, actor: setup.actor };
+    // APRV-370. The operator's sender key, and with it the form the two refusals
+    // below record the account in. Those two never reach the in-force mapping,
+    // so they take `recordedSenderFor`'s rule: the form follows the FILE, the
+    // mapping follows the ATTESTATION.
+    const key = senderKeyFrom();
+    if (load.ok) {
+        const read = readVerifiedRecords(setup.logPath);
+        if (!read.ok) {
+            return {
+                ok: false,
+                code: "policy-not-attested",
+                sender: recordedSenderFor(load, sender, key),
+                message: `the log could not be read to check whether ${load.source.filename} is attested (${read.code}): ${read.message}. Nothing was recorded; a decision made at a terminal carries no sender and is unaffected.`,
+            };
+        }
+        // `core/attest.ts`'s own check and its own wording, rather than a second
+        // comparison written here that could come to a different conclusion about
+        // the same file than the one the gate's refusal is built on.
+        const refusal = attestationRefusal(checkAttestation(read.records, load.source.path));
+        if (refusal !== null) {
+            return {
+                ok: false,
+                code: refusal.code,
+                sender: recordedSenderFor(load, sender, key),
+                message: `${refusal.message}. The sender mapping it declares is therefore not in force, so the account this gesture came from cannot be resolved against it and nothing was recorded. Re-attest the policy, or do this from a terminal, which authenticates no sender and is unaffected by the mapping.`,
+            };
+        }
+    }
+    return actorForSender(load, setup.actor, sender, key);
+}
+/**
+ * Record that a gesture this listener refused was made (APRV-355).
+ *
+ * Best-effort, and after the refusal is already decided: the card the person
+ * sees does not depend on this write landing. A failure is reported on stderr
+ * beside the refusal it was about, because a record that silently did not land
+ * is exactly the gap this task exists to close, and one that fails quietly is
+ * the same gap wearing a fix.
+ *
+ * The runtime cannot name a person on `sender-unmapped` or `sender-ambiguous`,
+ * which is the whole point of those refusals, so `actor` is the listener's
+ * configured identity ONLY where the resolution produced one. The observed
+ * account goes in either way; it is the only thing known about who tapped.
+ */
+function recordGestureRefusal(setup, streams, gesture, refused) {
+    const recorded = recordRefusedGesture(setup.logPath, {
+        gesture,
+        actor: null,
+        channel: "telegram",
+        sender: refused.sender,
+    }, { code: refused.code, message: refused.message }, setup.gateOptions);
+    if (!recorded.ok) {
+        streams.err(`approval: telegram ${gesture} refusal could not be recorded (${recorded.code}): ${recorded.message}\n`);
+    }
+}
 export function checkpointHandlerFor(setup, streams) {
     return (tap) => {
+        // APRV-324 follow-up, and FIRST, before the decline branch is even
+        // considered: a signature says this log's head is what this person saw, so
+        // an account the ATTESTED policy does not name may not produce one. Under
+        // no mapping this resolves to the configured identity and the whole branch
+        // is today's behaviour.
+        const resolved = senderIdentityFor(setup, tap.sender);
+        if (!resolved.ok) {
+            streams.err(`approval: telegram checkpoint refused (${resolved.code}): ${resolved.message}\n`);
+            recordGestureRefusal(setup, streams, "checkpoint-signature", resolved);
+            return {
+                ok: false,
+                headline: TELEGRAM_NOT_RECORDED,
+                detail: [refusedDecisionLine(resolved.code)],
+                toast: "Not signed.",
+            };
+        }
         if (!tap.sign) {
             return {
                 ok: true,
@@ -1619,7 +2249,7 @@ export function checkpointHandlerFor(setup, streams) {
                 toast: "Not now.",
             };
         }
-        const result = signCheckpointOffer(setup.checkpoint, tap.head, setup.actor, "telegram", process.cwd());
+        const result = signCheckpointOffer(setup.checkpoint, tap.head, resolved.actor, "telegram", process.cwd());
         const lines = checkpointSignedLines(result);
         const [headline, ...detail] = lines;
         if (setup.json) {
@@ -1632,7 +2262,7 @@ export function checkpointHandlerFor(setup, streams) {
             })}\n`);
         }
         else if (result.ok) {
-            streams.out(`checkpoint ${String(result.seq)}: signed head seq ${String(result.signed.seq)} ${result.signed.hash} by ${setup.actor} via telegram\n`);
+            streams.out(`checkpoint ${String(result.seq)}: signed head seq ${String(result.signed.seq)} ${result.signed.hash} by ${resolved.actor} via telegram\n`);
         }
         else {
             streams.err(`approval: telegram checkpoint refused (${result.code}): ${result.message}\n`);
@@ -1668,10 +2298,36 @@ export function checkpointHandlerFor(setup, streams) {
  */
 export function reviewHandlerFor(setup, streams) {
     return (tap) => {
-        const result = reviewSample(setup.logPath, { kind: "seq", seq: tap.sampleSeq }, setup.actor, tap.note ?? null, {
+        // APRV-324 follow-up. A review confers no authority and is still a HUMAN's
+        // observation: `approval feedback` hands it to agents as human-authored
+        // guidance, so a review attributed to the wrong person is guidance in
+        // somebody else's name. Resolved against the ATTESTED policy exactly as a
+        // signature is, and under no mapping this is the configured identity and
+        // today's behaviour.
+        const resolved = senderIdentityFor(setup, tap.sender);
+        if (!resolved.ok) {
+            streams.err(`approval: telegram review refused (${resolved.code}): ${resolved.message}\n`);
+            // `review-note` when the tap carried words: a note is attention spent
+            // writing rather than attention spent tapping, and an operator reading
+            // this record wants to know which they lost (APRV-355).
+            recordGestureRefusal(setup, streams, tap.note === undefined || tap.note.trim().length === 0 ? "review" : "review-note", resolved);
+            return {
+                ok: false,
+                headline: TELEGRAM_NOT_RECORDED,
+                detail: [refusedDecisionLine(resolved.code)],
+                toast: "Not recorded.",
+            };
+        }
+        const result = reviewSample(setup.logPath, { kind: "seq", seq: tap.sampleSeq }, resolved.actor, tap.note ?? null, {
             ...(setup.gateOptions.policy === undefined ? {} : { policy: setup.gateOptions.policy }),
             verdict: tap.verdict,
             ...(tap.reaction === undefined ? {} : { reaction: tap.reaction }),
+            ...(resolved.sender === undefined
+                ? {}
+                : {
+                    sender: resolved.sender,
+                    ...(resolved.source === undefined ? {} : { senderSource: resolved.source }),
+                }),
         });
         if (!result.ok) {
             // SPEC.md §11.1 invariant 6: the code is machine-readable and distinct,
@@ -1803,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));
@@ -1868,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
@@ -1899,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;
@@ -1927,7 +2607,11 @@ export function startListener(setup, streams) {
         const beforePoll = async () => {
             reportCycle(await dispatchPending(setup, streams, state, new Date().toISOString()), streams);
         };
-        await channel.listen(setup.once ? { once: true, beforePoll } : { beforePoll });
+        // APRV-390. The 409's report reads the ownership registry at the moment
+        // the conflict happens; the channel prints what this returns and knows
+        // nothing about instances or files.
+        const conflictAdvice = conflictAdviceFor(setup);
+        await channel.listen(setup.once ? { once: true, beforePoll, conflictAdvice } : { beforePoll, conflictAdvice });
         if (setup.json) {
             streams.out(`${JSON.stringify({ event: "stopped", ...channel.stats() })}\n`);
         }
@@ -1936,6 +2620,16 @@ export function startListener(setup, streams) {
     return { done, stop };
 }
 async function runListener(setup, streams) {
+    // APRV-390. Before anything is delivered and before the first poll: whose
+    // bot is this? An override that got this far still owes the operator the
+    // sentence, because the whole point of `--allow-cross-instance` is that the
+    // deliberate case is deliberate out loud.
+    for (const finding of setup.crossInstance) {
+        streams.err(`approval: --allow-cross-instance: starting anyway — ${finding.detail}\n`);
+    }
+    const claimed = await claimListenerBot(setup, (message) => streams.err(`${message}\n`));
+    if (!claimed.ok)
+        return integrityError(streams, setup.json, claimed.message);
     const running = startListener(setup, streams);
     const stop = () => running.stop();
     process.on("SIGINT", stop);
@@ -1947,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":
@@ -1989,6 +2688,10 @@ export function commandTelegramHealth(argv, streams, cwd) {
     const parsed = parseFlags(argv, {
         "--policy": "string",
         "--dir": "string",
+        // APRV-390. Which instance's ownership record to read. Accepted here for
+        // the same reason `listen` accepts it: a gate may be configured with its
+        // log somewhere other than beside the policy.
+        "--log": "string",
         "--json": "boolean",
         "--help": "boolean",
         "-h": "boolean",
@@ -2013,6 +2716,19 @@ export function commandTelegramHealth(argv, streams, cwd) {
     const token = env(tokenEnv);
     const chatId = env(chatEnv);
     const ok = token !== null && chatId !== null;
+    // APRV-390. Which bot, and whose. Read from the two ownership records and
+    // never from the network: this verb makes no Bot API call on any path, and
+    // the last `getMe` a listener or a setup run made is already written down.
+    // An instance that has never started a listener has no record, which is a
+    // state and not a fault — the row says so rather than guessing.
+    const logPath = resolvePath(stringFlag(parsed.flags, "--log"), DEFAULT_LOG_PATH, dirFlag === null ? cwd : absolute(dirFlag, cwd));
+    const mine = ownedBot(logPath, "telegram");
+    const others = mine === null ? [] : otherOwnersOf(logPath, mine.botId, mine.apiBase);
+    const ownership = mine === null
+        ? "no bot recorded for this instance yet: it is written by the first `approval up` or `approval channel telegram listen` that reaches getMe"
+        : others.length === 0
+            ? `bot ${mine.username} (id ${mine.botId}) is owned by this instance, ${mine.instanceHome} (instance ${mine.instanceId}), recorded ${mine.claimedAt}`
+            : `bot ${mine.username} (id ${mine.botId}) is claimed by this instance AND by ${describeOwners(others)}; one of them must be given its own bot`;
     if (json) {
         streams.out(`${JSON.stringify({
             ok,
@@ -2022,10 +2738,20 @@ export function commandTelegramHealth(argv, streams, cwd) {
             token_set: token !== null,
             chat_env: chatEnv,
             chat_id: chatId,
+            // APRV-390. Names and ids, never a value.
+            bot_username: mine?.username ?? null,
+            bot_id: mine?.botId ?? null,
+            owner_instance: mine?.instanceId ?? null,
+            owner_home: mine?.instanceHome ?? null,
+            other_owners: others.map((claim) => ({
+                instance_id: claim.instanceId,
+                instance_home: claim.instanceHome,
+            })),
         })}\n`);
     }
     else if (ok) {
         streams.out(`telegram: configured (${tokenEnv} set, chat ${String(chatId)})\n`);
+        streams.out(`  ${ownership}\n`);
     }
     else {
         streams.err(`approval: telegram is not configured: ${[
@@ -2054,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: