approval-md 0.4.0 → 0.4.2

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

@@ -112,10 +112,10 @@ 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";
+import { recordChannelDecision, recordSurfaceRefusal, refusedDecisionLine, } from "../channels/contract.js";
+import { ageText, attestedPromptOf, 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_DEFAULT_API_BASE, TELEGRAM_TERMINAL_HEADLINES, utcClock, } from "../channels/telegram.js";
+import { actionRefOf, decidedLine, groupForDigest, isDeterministicSendRefusal, isMessageNotModified, isTelegramTerminalState, retryAfterMsOf, 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";
@@ -128,7 +128,7 @@ import { claimBot, describeOwners, otherOwnersOf, ownedBot, } from "../core/chan
 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 { promptLayoutFor, promptSayFor, promptStyleFor } from "../core/prompt-layout.js";
 import { passphraseEnvFor } from "../core/vault.js";
 import { isAttestationActionKey, proposalRecords, proposalState, } from "../core/policy-proposal.js";
 import { payloadOf, readVerifiedRecords, requestState } from "../core/state.js";
@@ -141,6 +141,7 @@ import { TELEGRAM_HEALTH_HELP, TELEGRAM_HELP, TELEGRAM_LISTEN_HELP, } from "./he
 import { DEFAULT_LOG_PATH, preflightLog, resolvePath } from "./paths.js";
 import { style, tokenPanel, TOKEN_NOTICE_TELEGRAM } from "./style.js";
 import { usageErrorText } from "./usage.js";
+import { reservedKindNote } from "../core/identity.js";
 const LISTEN_FLAGS = {
     "--log": "string",
     "--policy": "string",
@@ -148,6 +149,8 @@ const LISTEN_FLAGS = {
     "--as": "string",
     "--payloads": "string",
     "--api-base": "string",
+    /** APRV-456: refuse a tap on a button this process is not holding. */
+    "--no-stale-copy": "boolean",
     "--poll-timeout": "string",
     "--once": "boolean",
     /** APRV-390: start on a credential this instance did not configure. */
@@ -604,7 +607,7 @@ export function prepareListen(request) {
             code: "no-identity",
             message: request.as === null
                 ? `no human identity: set ${HUMAN_ACTOR_ENV}=human:<id> or pass --as human:<id>. Every decision this listener records is recorded against it, and nothing here authenticates it`
-                : `--as expects a human identity matching human:<id>, got ${JSON.stringify(request.as)}; approvals are human-only`,
+                : `--as expects a human identity matching human:<id>, got ${JSON.stringify(request.as)}${reservedKindNote(request.as)}; approvals are human-only`,
         };
     }
     const pollFlag = request.pollTimeout;
@@ -645,6 +648,22 @@ export function prepareListen(request) {
         // default, because a layout is not a permission and an unrelated typo in a
         // class rule must not silently redecorate a phone screen.
         layout: promptLayoutFor(policyLoad, "telegram"),
+        // APRV-489. The card style and the operator's plain-words declarations.
+        // Fix round 2 (S4, and the security follow-up on it): resolved for EACH
+        // delivery, and only from ATTESTED bytes: `attestedPromptOf` reads the
+        // policy file once, requires those bytes to hash to the latest attestation
+        // in the verified log, and parses style and `say` from the same buffer. A
+        // re-attested setting reaches the next card without a restart; an edited,
+        // unattested file draws the technical card. The two fixed values below are
+        // only what a channel without the resolver would use.
+        promptStyle: promptStyleFor(policyLoad, "telegram"),
+        say: promptSayFor(policyLoad, "telegram"),
+        promptFor: () => attestedPromptOf(request.logPath, { policy: request.policy }, "telegram"),
+        // APRV-456. From the launch flags alone: a relayed channel (an --api-base
+        // that is not the Bot API) or --no-stale-copy turns APRV-196's fallback
+        // off. The policy loaded above is deliberately not consulted, so nothing
+        // an agent can propose into a policy file can turn it back on.
+        staleCopy: staleCopyFor(request.apiBase, request.noStaleCopy === true),
     };
     return {
         ok: true,
@@ -776,6 +795,8 @@ function setUp(argv, streams, cwd) {
         as: stringFlag(flags, "--as"),
         payloads: payloadsFlag === null ? null : absolute(payloadsFlag, cwd),
         apiBase: stringFlag(flags, "--api-base"),
+        // APRV-456.
+        noStaleCopy: boolFlag(flags, "--no-stale-copy"),
         pollTimeout: stringFlag(flags, "--poll-timeout"),
         once: boolFlag(flags, "--once"),
         json,
@@ -852,15 +873,47 @@ export const DISPATCH_RETENTION_MS = 24 * 60 * 60 * 1000;
  * two apart, having deliberately kept nothing that would let it, and a first
  * start that claimed to be a restart would be this channel's own text lying
  * about the system's history.
+ *
+ * **With the stale-copy fallback off (APRV-456)** the second line says the
+ * opposite, because the earlier copies' buttons no longer decide anything: a
+ * relayed listener refuses a nonce it is not holding (`nonce-not-issued`), so
+ * the banner tells the approver to use the copies below it. A banner that kept
+ * promising working older copies would be this channel's own text sending the
+ * approver to a button that refuses them.
  */
-export function bannerLines(pending) {
+export function bannerLines(pending, staleCopy = true) {
     const plural = pending === 1 ? "request" : "requests";
+    const live = `The ${pending === 1 ? "message" : "messages"} below ${pending === 1 ? "is" : "are"} the live ${pending === 1 ? "copy" : "copies"}.`;
     return [
         `LISTENER STARTED — re-sending ${pending} pending ${plural}.`,
-        `The ${pending === 1 ? "message" : "messages"} below ${pending === 1 ? "is" : "are"} the live ${pending === 1 ? "copy" : "copies"}. If an earlier copy of the same request is further up this chat, its buttons still decide the same request; nothing is decided twice.`,
+        staleCopy
+            ? `${live} If an earlier copy of the same request is further up this chat, its buttons still decide the same request; nothing is decided twice.`
+            : `${live} Buttons on earlier copies further up this chat no longer decide anything on this listener; tap the ${pending === 1 ? "copy" : "copies"} below.`,
         "Which requests are pending is read from the log on every cycle, never from this chat.",
     ];
 }
+/**
+ * Whether APRV-196's stale-copy fallback is on for a listener launched with
+ * this `--api-base` and this `--no-stale-copy` (APRV-456).
+ *
+ * On only for the direct-bot shape: no `--api-base`, or one that names the
+ * Bot API itself, and no `--no-stale-copy`. Any other base is treated as a
+ * relay, because the fallback's safety rests on only the bot token being able
+ * to put a button in front of the approver, and a base this process does not
+ * recognise as Telegram's own is one where that cannot be assumed. A
+ * self-hosted Bot API server is therefore treated as a relay too: the strict
+ * reading, and the cost is only that earlier copies stop deciding.
+ *
+ * Launch configuration and nothing else. No policy key reads into it and
+ * nothing in an update can reach it.
+ */
+export function staleCopyFor(apiBase, noStaleCopy) {
+    if (noStaleCopy)
+        return false;
+    if (apiBase === null)
+        return true;
+    return apiBase.replace(/\/+$/u, "") === TELEGRAM_DEFAULT_API_BASE;
+}
 // ---------------------------------------------------------------------------
 // Paced delivery (APRV-216) — one question at a time
 // ---------------------------------------------------------------------------
@@ -1042,6 +1095,9 @@ export function newDispatchState() {
             order: [],
             current: null,
             delivered: new Map(),
+            terminalOnly: new Set(),
+            offerFailures: new Map(),
+            offersPausedUntilMs: null,
             summarySent: false,
             announced: 0,
             logSize: null,
@@ -1413,7 +1469,7 @@ export async function dispatchPending(setup, streams, state, now) {
     state.banner.sent = true;
     if (announcing) {
         try {
-            const deliveryId = await setup.channel.announce(bannerLines(undelivered.length));
+            const deliveryId = await setup.channel.announce(bannerLines(undelivered.length, setup.channel.staleCopyEnabled()));
             result.banner = { delivery_id: deliveryId, pending: undelivered.length };
         }
         catch (cause) {
@@ -1544,6 +1600,14 @@ async function dispatchReviews(setup, streams, state, result, now) {
         if (!openSeqs.has(seq))
             review.delivered.delete(seq);
     }
+    for (const seq of review.terminalOnly) {
+        if (!openSeqs.has(seq))
+            review.terminalOnly.delete(seq);
+    }
+    for (const seq of review.offerFailures.keys()) {
+        if (!openSeqs.has(seq))
+            review.offerFailures.delete(seq);
+    }
     if (review.current !== null && !openSeqs.has(review.current))
         review.current = null;
     // A count the approver was told that is now too high is the number they
@@ -1553,7 +1617,16 @@ async function dispatchReviews(setup, streams, state, result, now) {
         return;
     if (setup.delivery === "paced" && state.paced.current !== null)
         return;
-    const nextSeq = review.order.find((seq) => !review.delivered.has(seq));
+    // PR #614 recheck NF-2: a transient offer failure pauses the walkthrough for
+    // Telegram's `retry_after` or the backoff, whichever is longer. Nothing is
+    // offered, summary included, until it passes.
+    const nowMs = Date.parse(now);
+    if (review.offersPausedUntilMs !== null) {
+        if (Number.isFinite(nowMs) && nowMs < review.offersPausedUntilMs)
+            return;
+        review.offersPausedUntilMs = null;
+    }
+    const nextSeq = review.order.find((seq) => !review.delivered.has(seq) && !review.terminalOnly.has(seq));
     if (nextSeq === undefined)
         return;
     const card = open.find((entry) => entry.sampleSeq === nextSeq);
@@ -1577,6 +1650,7 @@ async function dispatchReviews(setup, streams, state, result, now) {
     try {
         const deliveryId = await setup.channel.offerReview(card);
         review.delivered.set(nextSeq, deliveryId);
+        review.offerFailures.delete(nextSeq);
         review.current = nextSeq;
         result.reviewCard = {
             delivery_id: deliveryId,
@@ -1596,10 +1670,55 @@ async function dispatchReviews(setup, streams, state, result, now) {
         }
     }
     catch (cause) {
-        // The sample stays open and undelivered, so the next cycle offers it again.
-        streams.err(`approval: telegram could not offer the review of sample seq ${String(nextSeq)} (${actionKey}): ${cause instanceof Error ? cause.message : String(cause)} — the sample stays open and the next cycle tries again\n`);
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        const attempts = (review.offerFailures.get(nextSeq) ?? 0) + 1;
+        const deterministic = isDeterministicSendRefusal(cause);
+        if (deterministic || attempts >= REVIEW_OFFER_ATTEMPTS) {
+            // PR #614 refutation F4, narrowed by recheck NF-2. The sample stays open,
+            // and this listener stops offering it: either Telegram refused the card
+            // itself, so the next cycle would build the same card from the same log
+            // and meet the same refusal, or the retry budget is spent. The queue
+            // behind it moves on, and the coded line names the repair.
+            review.offerFailures.delete(nextSeq);
+            review.terminalOnly.add(nextSeq);
+            streams.err(`approval: telegram review-offer-failed: could not offer the review of sample seq ${String(nextSeq)} (${actionKey}): ${reason} — ${deterministic
+                ? "Telegram refused the card itself, so every resend would meet the same refusal"
+                : `${String(attempts)} attempts failed`}; the sample stays open for a terminal review (approval audit review ${String(nextSeq)} --ok or --deny), and this listener offers the next sample instead\n`);
+            return;
+        }
+        // PR #614 recheck NF-2. Anything else (a 429, a timeout, a 5xx, a network
+        // error) can clear on its own, so the sample keeps its place and the
+        // walkthrough pauses: for Telegram's `retry_after` when it named one, and
+        // never less than the backoff for this sample's attempt count.
+        review.offerFailures.set(nextSeq, attempts);
+        // NF-5: capped, because `retry_after` is the network's number. A huge one
+        // would otherwise park reviews for years, or overflow the Date below and
+        // throw out of a dispatch cycle that is documented never to throw.
+        const waitMs = Math.min(Math.max(reviewOfferBackoffMs(attempts), retryAfterMsOf(cause) ?? 0), REVIEW_OFFER_MAX_WAIT_MS);
+        const base = Number.isFinite(nowMs) ? nowMs : Date.now();
+        review.offersPausedUntilMs = base + waitMs;
+        streams.err(`approval: telegram review-offer-retry: could not offer the review of sample seq ${String(nextSeq)} (${actionKey}), attempt ${String(attempts)} of ${String(REVIEW_OFFER_ATTEMPTS)}: ${reason} — review cards pause until ${new Date(base + waitMs).toISOString()} and then offer it again\n`);
     }
 }
+/**
+ * How many failed offers a sample gets before it is left for a terminal review
+ * (PR #614 recheck NF-2). With {@link reviewOfferBackoffMs} the budget spans
+ * about fifteen minutes of a dark or rate-limited chat (1 + 2 + 4 + 8 minutes
+ * between the five attempts), and a Bot API refusal of the card itself skips
+ * it.
+ */
+export const REVIEW_OFFER_ATTEMPTS = 5;
+/**
+ * The longest review cards ever pause after one failed offer, whatever
+ * `retry_after` said (PR #614 recheck NF-5): one hour.
+ */
+export const REVIEW_OFFER_MAX_WAIT_MS = 3_600_000;
+/** The first pause after a transient offer failure; it doubles per attempt. */
+export const REVIEW_OFFER_BACKOFF_MS = 60_000;
+/** The pause after the `attempts`-th failed offer of one sample, before `retry_after`. */
+export function reviewOfferBackoffMs(attempts) {
+    return REVIEW_OFFER_BACKOFF_MS * 2 ** Math.max(0, attempts - 1);
+}
 /**
  * How old a pending request must be, on a listener's first cycle, to be one
  * nobody is waiting on (APRV-287).
@@ -2084,6 +2203,32 @@ export function reportCycle(result, streams) {
         streams.err(`approval: telegram sendMessage failed for ${failure.action_key} (attempt ${failure.attempts}): ${failure.message} — still pending, retrying next cycle\n`);
     }
 }
+/**
+ * Where a tap the channel refused on its own is recorded (APRV-456).
+ *
+ * One `audit.decision_refused`, through `recordSurfaceRefusal`, which never
+ * calls the gate. The operator's terminal says what happened either way,
+ * because a card nobody here sent being tapped on a relayed gate is the line
+ * an operator most needs to see.
+ */
+function refusedDecisionHandlerFor(setup, streams) {
+    return ({ decision, refusal }) => {
+        recordSurfaceRefusal(setup.logPath, decision, refusal, { actor: setup.actor, channel: "telegram" }, setup.gateOptions);
+        if (setup.json) {
+            streams.out(`${JSON.stringify({
+                event: "decision",
+                action_key: decision.action_key,
+                decision: decision.decision,
+                ok: false,
+                code: refusal.code,
+                token_issued: false,
+            })}\n`);
+        }
+        else {
+            streams.err(`approval: telegram decision refused (${refusal.code}): ${refusal.message}\n`);
+        }
+    };
+}
 /** The decision handler: the only thing this process does with a button press. */
 function handlerFor(setup, streams) {
     return (decision) => {
@@ -2316,12 +2461,18 @@ export function reviewHandlerFor(setup, streams) {
                 headline: TELEGRAM_NOT_RECORDED,
                 detail: [refusedDecisionLine(resolved.code)],
                 toast: "Not recorded.",
+                code: resolved.code,
             };
         }
         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,
+            // APRV-482: passed only when the human gave one. A grade alone arrives
+            // with none and `reviewSample` refuses it `verdict-required`.
+            ...(tap.verdict === undefined ? {} : { verdict: tap.verdict }),
             ...(tap.reaction === undefined ? {} : { reaction: tap.reaction }),
+            // APRV-481: the card's own statement that it showed the bytes whole,
+            // which `reviewSample` checks against the log before recording it.
+            ...(tap.payloadHash === undefined ? {} : { renderedPayloadHash: tap.payloadHash }),
             ...(resolved.sender === undefined
                 ? {}
                 : {
@@ -2341,7 +2492,7 @@ export function reviewHandlerFor(setup, streams) {
                     event: "review",
                     ok: false,
                     sample_seq: tap.sampleSeq,
-                    verdict: tap.verdict,
+                    verdict: tap.verdict ?? null,
                     reaction: tap.reaction ?? null,
                     code: result.code,
                 })}\n`);
@@ -2351,6 +2502,7 @@ export function reviewHandlerFor(setup, streams) {
                 headline: TELEGRAM_NOT_RECORDED,
                 detail: [result.code, result.message],
                 toast: "Not recorded — the card says why.",
+                code: result.code,
             };
         }
         const obligation = result.obligation;
@@ -2361,7 +2513,7 @@ export function reviewHandlerFor(setup, streams) {
                 seq: result.record.seq,
                 sample_seq: result.subject.seq,
                 action_key: result.subject.actionKey,
-                verdict: tap.verdict,
+                verdict: tap.verdict ?? null,
                 reaction: tap.reaction ?? null,
                 obligation_seq: obligation === null ? null : obligation.seq,
             })}\n`);
@@ -2370,7 +2522,7 @@ export function reviewHandlerFor(setup, streams) {
             streams.out(`reviewed sample at seq ${String(result.subject.seq)} (action ${result.subject.actionKey ?? "-"}) at seq ${String(result.record.seq)} by ${setup.actor} via telegram${tap.verdict === "denied" ? " — DENIED" : ""}${tap.reaction === undefined ? "" : ` — reaction: ${tap.reaction} (guidance, not policy)`}\n`);
         }
         const detail = [
-            `recorded at seq ${String(result.record.seq)} by ${setup.actor} · verdict ${tap.verdict}`,
+            `recorded at seq ${String(result.record.seq)} by ${setup.actor} · verdict ${tap.verdict ?? "-"}`,
             ...(tap.reaction === undefined
                 ? []
                 : [`reaction: ${tap.reaction} — guidance, not policy; it changes no verdict and no budget`]),
@@ -2488,7 +2640,7 @@ clock = () => new Date().toISOString()) {
                         : `Review of sample ${String(card)} passed over — this listener sends no further card for it.`,
                     "Nothing was recorded. The sample is still open: it is listed by `approval audit list` and reviewable with `approval audit review " +
                         String(card) +
-                        "`, and the card already in this chat keeps its buttons.",
+                        " --ok` (or `--deny`), and the card already in this chat keeps its buttons.",
                 ]);
                 return;
             }
@@ -2546,6 +2698,10 @@ clock = () => new Date().toISOString()) {
 export function wireListener(setup, streams) {
     const { channel } = setup;
     channel.onDecision(handlerFor(setup, streams));
+    // APRV-456. Where a tap the channel refused on its own (`nonce-not-issued`)
+    // is recorded. A separate function from the decision handler because that
+    // one calls the gate and this one must not.
+    channel.onRefusedDecision(refusedDecisionHandlerFor(setup, streams));
     // APRV-257. Registered unconditionally, because whether a checkpoint is ever
     // OFFERED is the policy's answer and a handler that exists for a prompt
     // nobody sends costs nothing. Registering it here is also what makes the