approval-md 0.4.5 → 0.4.7

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

@@ -115,7 +115,7 @@ import { assembleBatch } from "../channels/batch.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, 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 { actionRefOf, decidedLine, groupForDigest, isDeterministicSendRefusal, isMessageNotModified, isTelegramTerminalState, retryAfterMsOf, TelegramChannel, telegramChatEnvFor, telegramTokenEnvFor, TELEGRAM_NOT_RECORDED, TELEGRAM_REVIEW_DENIED, TELEGRAM_REVIEW_RECORDED, TELEGRAM_CLAIMED_LABEL, TELEGRAM_DEFAULT_API_BASE, TELEGRAM_STUDY_WITHDRAWN_HEADLINE, 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";
@@ -664,6 +664,11 @@ export function prepareListen(request) {
         // 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),
+        // Amended SPEC.md §8 (the study record). Read from this process's launch
+        // environment ONCE, here, and never from the policy: nothing an agent can
+        // propose into a policy file may switch it. Off leaves the key out, so the
+        // channel is configured exactly as it was before study mode existed.
+        ...(studyModeFor(process.env) ? { study: true } : {}),
     };
     return {
         ok: true,
@@ -853,7 +858,8 @@ export const DISPATCH_LOUD_ATTEMPTS = 3;
  */
 export const DISPATCH_RETENTION_MS = 24 * 60 * 60 * 1000;
 /**
- * The line that introduces the first batch a listener process sends (APRV-196).
+ * The one message that introduces the first batch a listener process sends
+ * (APRV-196). Two lines, sent together by `announce`, the first in bold.
  *
  * **Why a banner and not an edit of the earlier copies.** The incident was a
  * restart re-sending five pending requests with no warning, on top of five
@@ -869,27 +875,59 @@ export const DISPATCH_RETENTION_MS = 24 * 60 * 60 * 1000;
  * (`actionRefOf` in `channels/telegram.ts`), so a human who taps the copy they
  * can see decides the request they meant.
  *
- * It says "started" rather than "restarted" because a listener cannot tell the
- * 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.
+ * **The words are a resident's, not the system's.** The reader is whoever
+ * holds the phone, so the banner is one short message in plain words: how many
+ * requests are still waiting, and whether the buttons on the older messages
+ * above still work. It names no process, no log and no cycle, and it says
+ * neither "started" nor "restarted": a listener cannot tell the two apart,
+ * having deliberately kept nothing that would let it, so the text claims only
+ * what is true either way (these requests are still waiting). The old third
+ * line, about where the pending set is read from, is gone; it described the
+ * runtime to someone who only needs to know which button to press.
  *
  * **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
+ * opposite, because the earlier copies' buttons no longer work: a relayed
+ * listener refuses a nonce it is not holding (`nonce-not-issued`), so the
+ * banner tells the approver to use the buttons 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, 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"}.`;
+    const one = pending === 1;
     return [
-        `LISTENER STARTED — re-sending ${pending} pending ${plural}.`,
+        `Reminder: ${pending} ${one ? "request is" : "requests are"} still waiting for you.`,
         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.",
+            ? `${one ? "It is" : "They are"} repeated below; buttons on older messages above still work, and nothing is answered twice.`
+            : "Use the buttons below; buttons on older messages above no longer work.",
+    ];
+}
+/**
+ * The reminder a collapsed re-delivery opens with, in place of the banner
+ * (P-9).
+ *
+ * Before this, a restart with two stale requests and one live one sent the
+ * stale summary first and the {@link bannerLines} banner second, and the banner
+ * counted only the cards after it: "1 request is still waiting" with three
+ * pending and the summary of the other two directly above. Two reminders, the
+ * more verbose one first, and a count that read as wrong. Now the summary IS the
+ * reminder: its first line counts everything this cycle re-sends (`pending`,
+ * collapsed and carded together), and the banner is skipped.
+ *
+ * `following` is how many requests get their own card after the summary. When
+ * there are any, the second line says so and says whether the buttons on older
+ * messages still work, which is what the banner it replaces said (APRV-456).
+ * When there are none, the summary is the whole restart and nothing follows.
+ */
+export function staleReminderLines(pending, following, staleCopy = true) {
+    const head = `Reminder: ${String(pending)} ${pending === 1 ? "request is" : "requests are"} still waiting for you.`;
+    if (following <= 0)
+        return [head];
+    const below = following === 1 ? "The other one is repeated below" : `The other ${String(following)} are repeated below`;
+    return [
+        head,
+        staleCopy
+            ? `${below}; buttons on older messages above still work.`
+            : `${below}; use ${following === 1 ? "its buttons" : "their buttons"}, as buttons on older messages above no longer work.`,
     ];
 }
 /**
@@ -914,79 +952,145 @@ export function staleCopyFor(apiBase, noStaleCopy) {
         return true;
     return apiBase.replace(/\/+$/u, "") === TELEGRAM_DEFAULT_API_BASE;
 }
+/**
+ * The launch variable that turns study mode on (amended SPEC.md §8, the study
+ * record). Generic on purpose: the core is a public spec and names no study.
+ * A hosted deployment writes it into the listener's environment for the
+ * tenants a study covers; nothing else sets it.
+ */
+export const STUDY_MODE_ENV = "APPROVAL_STUDY_MODE";
+/**
+ * Whether `env` turns study mode on: the value is exactly `1`, and anything
+ * else (unset, blank, `true`, ` 1`, `0`) is off. Called once, by
+ * {@link prepareListen}; the channel keeps the answer for its lifetime, so a
+ * change takes effect only when the listener restarts.
+ */
+export function studyModeFor(env) {
+    return env[STUDY_MODE_ENV] === "1";
+}
 // ---------------------------------------------------------------------------
 // Paced delivery (APRV-216) — one question at a time
 // ---------------------------------------------------------------------------
 /**
- * The summary line that precedes a paced send, and the body of `/queue`.
- *
- * One message, and everything in it is arithmetic on the verified log at the
- * instant it is written: how many requests are pending, how long the oldest has
- * waited, and which classes they are. Nothing is remembered between calls, so
- * two summaries a minute apart can disagree only because the log moved.
- *
- * The class tally is the part worth the space. The count alone says how much
- * work is waiting; the classes say what KIND of work, which is what tells an
- * approver whether the queue is six identical `network.call`s they can walk
- * through or one `policy.edit` they should read carefully.
+ * The count line a paced cycle sends when the pending set has grown, and the
+ * header of `/queue` (APRV-216), in a resident's words (P-9).
+ *
+ * One line, and everything in it is arithmetic on the verified log at the
+ * instant it is written: how many requests are waiting and how long the oldest
+ * has waited. Nothing is remembered between calls, so two summaries a minute
+ * apart can disagree only because the log moved.
+ *
+ * Before P-9 it also carried a class tally ("communicate.email.external ×3").
+ * The tally told an operator what kind of work was queued, and told a resident
+ * nothing they could read; the kind of each request is on its own card, and
+ * `/queue` now lists each by the agent's own summary ({@link queueLines}).
+ *
+ * The oldest is the one asked longest ago, whatever order `requests` is in:
+ * `/queue` passes the set in presentation order ({@link orderPending}, live
+ * newest first), where the first entry is the NEWEST, and a header that read
+ * the first entry's age called the newest one the oldest.
  */
 export function summaryLines(requests, now) {
     if (requests.length === 0)
-        return ["Nothing pending — the queue is empty."];
-    const nowMs = Date.parse(now);
-    const oldest = requests[0];
-    const oldestMs = Date.parse(oldest.requested_ts.value);
-    const age = Number.isNaN(nowMs) || Number.isNaN(oldestMs) ? "unknown age" : ageText(nowMs - oldestMs);
-    const tally = new Map();
-    for (const request of requests) {
-        const cls = request.class.value;
-        tally.set(cls, (tally.get(cls) ?? 0) + 1);
-    }
-    const classes = [...tally.entries()]
-        .map(([cls, count]) => (count === 1 ? cls : `${cls} ×${String(count)}`))
-        .join(", ");
+        return ["Nothing is waiting for you right now."];
+    const one = requests.length === 1;
     return [
-        `${String(requests.length)} pending — oldest ${age} — ${classes}`,
+        `${String(requests.length)} ${one ? "request is" : "requests are"} waiting for you (${one ? "asked" : "oldest"} ${oldestAge(requests, now)}).`,
     ];
 }
+/** How long ago the longest-waiting request was asked, in words. */
+function oldestAge(requests, now) {
+    const nowMs = Date.parse(now);
+    const instants = requests
+        .map((request) => Date.parse(request.requested_ts.value))
+        .filter((at) => !Number.isNaN(at));
+    if (Number.isNaN(nowMs) || instants.length === 0)
+        return "at an unknown time";
+    return ageText(nowMs - Math.min(...instants));
+}
+/**
+ * The reminder a paced listener's first cycle opens with (P-9).
+ *
+ * Paced is the product default (APRV-216), and a restart there used to open
+ * with the bare count line and then one card. Nothing in it said this was a
+ * reminder, or whether the buttons on older messages above still worked, which
+ * matters most behind a relay, where they do not (APRV-456). So the first
+ * cycle's line is a reminder in the burst banner's words ({@link bannerLines}):
+ * how many are waiting, how many are below, and what the older buttons do.
+ *
+ * `shown` is how many requests this cycle puts below it: one, or a digest
+ * group. With the stale-copy fallback on, older buttons decide only while their
+ * request is the one being shown, so when fewer are shown than are pending the
+ * line says only the ones below work right now (fold round 1, S1). Later cycles that find the set has grown send {@link summaryLines}
+ * instead, which is a count and not a reminder.
+ */
+export function pacedReminderLines(pending, shown, staleCopy = true) {
+    const head = `Reminder: ${String(pending)} ${pending === 1 ? "request is" : "requests are"} waiting for you.`;
+    const below = shown >= pending
+        ? pending === 1
+            ? "It is below."
+            : "They are below."
+        : shown === 1
+            ? "One is below; the next comes after you answer it."
+            : `${String(shown)} are below; the next come after you answer them.`;
+    if (staleCopy && shown < pending) {
+        // Fold round 1, S1: under paced only the unit below has a live delivery.
+        // An older copy of any OTHER pending request is answered "Still pending —
+        // this copy's buttons are not live here", so "older buttons still work"
+        // would be this channel's own text sending the approver to a refusal.
+        return [
+            head,
+            shown === 1
+                ? "One is below. Only its buttons work right now; the others come next, with new buttons, after you answer it."
+                : `${String(shown)} are below. Only their buttons work right now; the others come next, with new buttons, after you answer them.`,
+        ];
+    }
+    const older = staleCopy
+        ? "Buttons on older messages above still work."
+        : `Buttons on older messages above no longer work; use ${shown === 1 ? "the one" : "the ones"} below.`;
+    return [head, `${below} ${older}`];
+}
 /**
- * The marker `/queue` puts on the request this listener has selected (APRV-256).
- *
- * It says two things and claims no third. "Selected" is this process's memory of
- * which request it is holding; "card sent earlier" is the delivery bookkeeping
- * recording that a send once succeeded. Neither is evidence that the card is
- * still in the chat: Telegram reports a successful send, never a message's
- * continued existence, and a card can be deleted, buried under a thousand later
- * messages, or lost with the chat history on a reinstall. The old marker,
- * "shown now", asserted present visibility from a past delivery, which is the
- * bug this constant exists to keep fixed.
+ * The marker `/queue` puts on the request this listener has selected (APRV-256),
+ * in a resident's words (P-9).
+ *
+ * It says one thing and claims no second: a message for this request was sent
+ * earlier, which is the delivery bookkeeping recording that a send once
+ * succeeded. That is not evidence the message is still in the chat: Telegram
+ * reports a successful send, never a message's continued existence, and a card
+ * can be deleted, buried under a thousand later messages, or lost with the chat
+ * history on a reinstall. The marker before APRV-256, "shown now", asserted
+ * present visibility from a past delivery, which is the bug this constant
+ * exists to keep fixed, and why it does not say "on screen" either.
  */
-const SELECTED_MARKER = " — selected — card sent earlier";
+const SELECTED_MARKER = " · sent to you earlier";
 /**
  * What `/queue` says about itself, immediately under the summary (APRV-256).
  *
  * `/queue` is a summary reply and carries no buttons, so an approver reading it
  * on a phone must not be left hunting this message for controls that were never
- * on it. Where the controls DO live is stated without a direction: a card is
+ * on it. Where the controls DO live is stated without a direction: a message is
  * somewhere in the chat's history, and "above" was only ever true for the
  * approver who asked while looking straight at it.
  */
-const QUEUE_IS_A_LIST = "This is a list of what the log is holding. It has no decision buttons: a request is decided on its own approval card, wherever that card sits in this chat.";
+const QUEUE_IS_A_LIST = "This list has no buttons. Each request is answered on its own message, wherever it is in this chat.";
 /**
  * `/queue`'s reply: the summary, then one numbered line per pending request.
  *
  * Derived, like the summary, from the verified log at reply time and not from
  * anything this process is holding: the numbering is positional and names no
  * button, so a stale copy of this list cannot be used to decide anything. The
- * marker says which one this listener has selected and once delivered, because
- * the question `/queue` is usually asked to answer is "what else is there
- * besides the one I am looking at" — and, since APRV-256, its unhappy twin,
- * "where is the one I am supposed to be looking at".
- *
- * The footer answers that second question the only honest way available to a
- * process whose knowledge of the chat ends at "a send returned success": it
- * says what was sent, says it cannot tell whether the card survived, and then
- * spends its remaining words on recovery rather than reassurance.
+ * marker says which one was sent earlier, because the question `/queue` is
+ * usually asked to answer is "what else is there besides the one I am looking
+ * at" and, since APRV-256, its unhappy twin, "where is the one I am supposed to
+ * be looking at".
+ *
+ * P-9: each line is the agent's own summary and its age, under the label that
+ * says the summary is the agent's and unchecked. Before P-9 each line was the
+ * action key, the task id, the class and the age, and in real use the first
+ * two are `hook:<session uuid>:<tool_use_id>…`, two long raw ids per line. The
+ * three recovery paragraphs are two short lines: what /skip and /next do, and
+ * that neither answers anything.
  */
 export function queueLines(requests, now, shown) {
     const lines = summaryLines(requests, now);
@@ -995,36 +1099,35 @@ export function queueLines(requests, now, shown) {
     const nowMs = Date.parse(now);
     const current = new Set(shown);
     let selected = 0;
-    lines.push(QUEUE_IS_A_LIST);
+    lines.push(QUEUE_IS_A_LIST, `${TELEGRAM_CLAIMED_LABEL}:`);
     requests.forEach((request, index) => {
-        const key = request.action_key.value;
         const requestedMs = Date.parse(request.requested_ts.value);
         const age = Number.isNaN(nowMs) || Number.isNaN(requestedMs)
             ? "unknown age"
             : ageText(nowMs - requestedMs);
-        const task = request.task.value ?? "no task";
-        const isSelected = current.has(key);
+        const isSelected = current.has(request.action_key.value);
         if (isSelected)
             selected += 1;
-        lines.push(`${String(index + 1)}. ${key} — ${task} — ${request.class.value} — ${age}${isSelected ? SELECTED_MARKER : ""}`);
+        lines.push(`${String(index + 1)}. ${request.summary.value ?? "(none given)"} · ${age}${isSelected ? SELECTED_MARKER : ""}`);
     });
     if (selected === 0) {
         // Nothing selected is an ordinary state, not a fault: a decided or passed
         // over request leaves the listener holding nothing until the next cycle
         // picks the next one up. Saying so is what stops the reader searching the
-        // chat for a card this process never claimed to have sent.
-        lines.push("Nothing is selected right now, so no approval card has been sent for any of these. The next one goes out with its buttons on an upcoming listener cycle.");
+        // chat for a message this process never claimed to have sent.
+        lines.push("None of these has been sent to you yet. The next one arrives with its buttons shortly.");
         return lines;
     }
     // More than one key is marked when the selection is a digest group, which
-    // Telegram receives as ONE card covering the set. Hence "a single approval
-    // card" in the plural branch and no positional word in either: the reply may
+    // Telegram receives as ONE summary message covering the set, so the plural
+    // branch speaks of one message. No positional word in either: the reply may
     // be chunked across several messages, so "above" is not this function's to
     // promise even about its own lines.
-    const holding = selected === 1
-        ? "The request marked selected is the one this listener is holding, and an approval card for it was sent to this chat earlier. The buttons on that card decide it."
-        : `The ${String(selected)} requests marked selected are what this listener is holding as one digest, and a single approval card for them was sent to this chat earlier. The buttons on that card decide them.`;
-    lines.push(`${holding} This listener cannot tell whether that card is still here.`, "If you cannot find the card, /skip is the recovery: it puts the request at the back of the order and lets the next one through. Nothing is decided by typing it, the request stays pending in the log, and a fresh card is sent on a later listener cycle once the requests ahead of it have had their turn (a cycle can run a little long while a gloss is being written).", "/next gives up your place instead: this listener moves past the request and stops offering it, and no new card is sent for it. It is not a way to ask for the card again.");
+    lines.push(selected === 1
+        ? "Can't find its message? /skip sends the next one instead; this one comes back later."
+        : "Can't find their message? /skip sends the next ones instead; these come back later.", selected === 1
+        ? "/next stops showing you this one and does not send it again. Neither command answers anything."
+        : "/next stops showing you these and does not send them again. Neither command answers anything.");
     return lines;
 }
 /**
@@ -1104,6 +1207,13 @@ export function newDispatchState() {
         },
     };
 }
+/** Whether a settling record is the study team's withdrawal (amended SPEC.md §8). */
+function isStudyWithdrawal(payload) {
+    const study = payload["study"];
+    return (typeof study === "object" &&
+        study !== null &&
+        study["reason"] === "study_withdrawn");
+}
 /** The event that records each terminal state, for finding the settling record. */
 const TERMINAL_EVENT = {
     granted: "approval.granted",
@@ -1220,6 +1330,20 @@ function terminalDeliveries(setup, state, now) {
             });
             continue;
         }
+        // Amended SPEC.md §8, the study record: the study team withdrew a pending
+        // request. Its own headline and line, so the resident never reads it as a
+        // person's REJECTED and does read that nothing ran. The operator id the
+        // record carries is not shown.
+        if (outcome === "rejected" && record !== undefined && isStudyWithdrawal(payload)) {
+            settled.push({
+                actionKey,
+                deliveryId,
+                outcome,
+                headline: TELEGRAM_STUDY_WITHDRAWN_HEADLINE,
+                detail: [`withdrawn by the study team at ${utcClock(record.ts)} · nothing ran`],
+            });
+            continue;
+        }
         // granted / rejected / revoked: a human answered, somewhere. The actor is
         // the log's, never this listener's configured identity — the answer may
         // have come from another surface entirely.
@@ -1278,7 +1402,7 @@ export async function dispatchPending(setup, streams, state, now) {
             // The action key is what makes this per member on a digest (APRV-115):
             // one delivery id can carry several requests, and settling one of them
             // must leave the others armed.
-            await setup.channel.annotate(settled.deliveryId, TELEGRAM_TERMINAL_HEADLINES[settled.outcome], settled.detail, settled.actionKey);
+            await setup.channel.annotate(settled.deliveryId, settled.headline ?? TELEGRAM_TERMINAL_HEADLINES[settled.outcome], settled.detail, settled.actionKey);
             result.annotated.push({
                 action_key: settled.actionKey,
                 delivery_id: settled.deliveryId,
@@ -1443,10 +1567,16 @@ export async function dispatchPending(setup, streams, state, now) {
     if (setup.delivery === "paced" && undelivered.length > 0) {
         const pending = queue.requests.length;
         if (!state.paced.summarySent || pending > state.paced.announced) {
+            const opening = !state.paced.summarySent;
             state.paced.summarySent = true;
             state.paced.announced = pending;
+            // P-9: the first one is a reminder that says what the older buttons do;
+            // a later one, for a set that grew, is the count line.
+            const lines = opening
+                ? pacedReminderLines(pending, undelivered.length, setup.channel.staleCopyEnabled())
+                : summaryLines(queue.requests, now);
             try {
-                const deliveryId = await setup.channel.announce(summaryLines(queue.requests, now));
+                const deliveryId = await setup.channel.announce(lines);
                 result.summary = { delivery_id: deliveryId, pending };
             }
             catch (cause) {
@@ -1465,7 +1595,15 @@ export async function dispatchPending(setup, streams, state, now) {
     // started against an empty queue has no re-delivery to announce, ever. See
     // {@link bannerLines} for why this is a banner rather than an edit of the
     // copies that came before.
-    const announcing = setup.delivery === "burst" && !state.banner.sent && undelivered.length > 0;
+    //
+    // P-9: a cycle whose stale summary went out has had its reminder already. The
+    // summary opens with the count of everything this cycle re-sends and says
+    // whether older buttons still work ({@link staleReminderLines}), so a banner
+    // here would be the second reminder of one restart.
+    const announcing = setup.delivery === "burst" &&
+        !state.banner.sent &&
+        undelivered.length > 0 &&
+        result.collapsed === undefined;
     state.banner.sent = true;
     if (announcing) {
         try {
@@ -1860,55 +1998,51 @@ export function orderPending(requests, now) {
     return [...live.map((entry) => entry.request), ...stale.map((entry) => entry.request), ...proposals];
 }
 /**
- * A DURATION in words, which is not what {@link ageText} renders.
+ * The computed lines a collapsed re-delivery leads with (APRV-287), in a
+ * resident's words (P-9).
  *
- * `ageText` says how long ago something happened ("5 min ago"), and these two
- * numbers are lengths of time rather than instants: writing "older than the
- * hook's 5 min ago retry grace" would be a sentence about the wrong kind of
- * thing.
+ * `superseded` is the subset a newer pending request replaced (APRV-425), and
+ * the line states the split rather than claiming every member is old. Before
+ * APRV-425 it said every member was past the hook's wait, 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.
+ *
+ * Before P-9 these lines also spelled out the hook's wait and retry grace in
+ * seconds and minutes, a tally of class names, and a sentence about log events
+ * and identical retries. The reader is whoever holds the phone, so what is left
+ * is the one thing they need: how many are listed, and why nobody needs an
+ * answer to them now. The age of each one moves onto its own line
+ * ({@link staleAges}).
  */
-function durationText(ms) {
-    if (ms < 60_000)
-        return `${String(Math.round(ms / 1000))}s`;
-    const minutes = Math.round(ms / 60_000);
-    return `${String(minutes)}m`;
+export function staleLines(requests, _now, superseded = new Set()) {
+    const count = requests.length;
+    const listed = `${String(count)} older ${count === 1 ? "one is" : "ones are"} listed here`;
+    const replaced = requests.filter((request) => superseded.has(request.action_key.value)).length;
+    const abandoned = count - replaced;
+    if (replaced === 0) {
+        return [`${listed}; nobody is waiting on ${count === 1 ? "it" : "them"} any more.`];
+    }
+    if (abandoned === 0) {
+        return [`${listed}; your agent has asked the same thing again since, so answer the newer one instead.`];
+    }
+    return [
+        `${listed}. Nobody is waiting on ${String(abandoned)} of them, and your agent has asked the same thing again since for the other ${String(replaced)}.`,
+    ];
 }
 /**
- * The computed lines a collapsed re-delivery leads with (APRV-287).
+ * How long ago each collapsed request was asked, in the order given (P-9).
  *
- * `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.
+ * Computed from the verified log's own `requested_ts`, like the rest of the
+ * summary, and rendered beside each member's claimed summary line so the
+ * resident can tell the requests apart without an action key.
  */
-export function staleLines(requests, now, superseded = new Set()) {
+export function staleAges(requests, now) {
     const nowMs = Date.parse(now);
-    const ages = requests
-        .map((request) => nowMs - Date.parse(request.requested_ts.value))
-        .filter((age) => !Number.isNaN(age));
-    const oldest = ages.length === 0 ? null : Math.max(...ages);
-    const tally = new Map();
-    for (const request of requests) {
-        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, ${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 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",
-    ];
+    return requests.map((request) => {
+        const at = Date.parse(request.requested_ts.value);
+        return Number.isNaN(nowMs) || Number.isNaN(at) ? "unknown age" : ageText(nowMs - at);
+    });
 }
 /**
  * Put the requests nobody is waiting on into ONE message, and hand back the
@@ -1980,8 +2114,13 @@ async function collapseStale(setup, streams, state, result, undecided, now) {
         return undecided;
     let delivered = null;
     try {
+        // P-9: the summary carries this cycle's reminder, counting everything it
+        // re-sends (the collapsed members plus the cards that follow), and the
+        // banner is then skipped. `undecided` is exactly that set on a first cycle.
         delivered = await setup.channel.notifyStale(stale, {
+            reminder: staleReminderLines(undecided.length, undecided.length - stale.length, setup.channel.staleCopyEnabled()),
             lines: staleLines(stale, now, superseded),
+            ages: staleAges(stale, now),
         });
     }
     catch (cause) {