approval-md 0.4.5 → 0.4.7

package/dist/src/channels/telegram.js

@@ -227,6 +227,7 @@ import { GLOSS_UNVERIFIED_SUFFIX, refusedDecisionLine } from "./contract.js";
 // §11.1 invariant 10's guard scans the modules that decide, which this is not.
 import { REACTIONS } from "../core/audit.js";
 import { DEFAULT_PROMPT_STYLE, TELEGRAM_PROMPT_LAYOUT, } from "../core/prompt-layout.js";
+import { isAttestationActionKey } from "../core/policy-proposal.js";
 import { commandPayloadView, payloadRegionText } from "./payload-view.js";
 import { MINIMAL_DENY_LABEL, renderTelegramMinimal } from "./telegram-minimal.js";
 // ---------------------------------------------------------------------------
@@ -310,27 +311,84 @@ export const TELEGRAM_STALE_UNKNOWN = "This request is not open here — it was
  */
 export const TELEGRAM_PROMPT_HEADING = "APPROVAL REQUIRED";
 /**
- * What the label over the payload chunks names (APRV-162).
+ * What the label over the payload chunks names (APRV-162), in a resident's
+ * words (P-9).
  *
  * The chunks carry the canonical rendering, which is a deterministic function
- * of the bytes and not the bytes themselves; calling it "the exact bytes" told
- * the reader that a diff view and a JSON file were the same object. The
- * rendering names its own `display_hash`, and the store path inside it is the
- * route back to the bytes.
+ * of the bytes and not the bytes themselves, and the rendering names its own
+ * `display_hash` and store path inside the block (SPEC.md §10.3, bound
+ * verbatim by `display_hash`). This label sits OUTSIDE that block, so it is
+ * free to say what the block is for the person reading it: what they are
+ * approving. Before P-9 it said "the canonical rendering this approval's
+ * display_hash names; raw bytes at the store path inside", which is the
+ * block's own first lines restated in the system's vocabulary.
  */
-export const PAYLOAD_CHUNK_LABEL_TAIL = "the canonical rendering this approval's display_hash names; raw bytes at the store path inside";
-export const PAYLOAD_CHUNK_LABEL = `PAYLOAD — ${PAYLOAD_CHUNK_LABEL_TAIL}`;
+export const PAYLOAD_CHUNK_LABEL_TAIL = "what you are approving";
+export const PAYLOAD_CHUNK_LABEL = `Exactly ${PAYLOAD_CHUNK_LABEL_TAIL}`;
+/**
+ * The plain-words label over lines the requesting agent wrote (P-9).
+ *
+ * The same words the minimal card uses for the agent's own summary: the reader
+ * learns that the agent said it and that nobody checked it, which is what the
+ * old "CLAIMED ... NOT verified by the runtime" said in the system's
+ * vocabulary. The author id stays after it, because which agent said a thing
+ * is part of what an approver weighs (APRV-144).
+ */
+export const TELEGRAM_CLAIMED_LABEL = "What your agent says (not checked)";
 /**
  * What the claimed block is headed, and what a second claimed message is headed
  * when a rationale overflows one (APRV-165).
  *
- * Both say CLAIMED and both say NOT verified, because a continuation is a
- * message a reader may see first, and a claimed line that arrives under no
- * heading at all reads as the runtime's own.
+ * Both say the lines are the agent's and not checked, because a continuation
+ * is a message a reader may see first, and a claimed line that arrives under
+ * no heading at all reads as the runtime's own.
+ */
+export const TELEGRAM_CLAIMED_HEADING_PREFIX = `${TELEGRAM_CLAIMED_LABEL} —`;
+export const TELEGRAM_CLAIMED_CONTINUED_HEADING = "What your agent says (continued, not checked)";
+/**
+ * The heading over the rows the runtime derived itself (P-9): the class, the
+ * wait, the budget. Before P-9 it read "COMPUTED — derived by the runtime from
+ * the log, the policy and the payload bytes". The rows keep their origin tags,
+ * which the village relay reads (its quiet hold matches the `ttl` row up to
+ * its `<i>(` tag).
+ */
+export const TELEGRAM_COMPUTED_HEADING = "Checked by approval.md";
+/** The most characters of an author id the claimed label shows (fold round 1, S3). */
+export const TELEGRAM_CLAIMED_AUTHOR_MAX = 80;
+/**
+ * {@link TELEGRAM_CLAIMED_LABEL} naming who wrote the lines under it.
+ *
+ * The author is the requester's actor id, which the actor rule
+ * (`^(human|agent):.+`) checks only at its start: a line break later in it
+ * passes. Escaping stops markup, but not a second line inside the bold heading
+ * that reads like the runtime's own "Checked by approval.md" (fold round 1,
+ * S3). So every run of whitespace, line breaks included, becomes one space,
+ * control and format characters are dropped, and the id is cut at
+ * {@link TELEGRAM_CLAIMED_AUTHOR_MAX} characters with an ellipsis. The label is
+ * always one line.
+ */
+export function claimedLabelFor(author) {
+    return `${TELEGRAM_CLAIMED_LABEL} — ${oneLineAuthor(author)}`;
+}
+/**
+ * An author id as one short line (fold round 1, S3): whitespace runs, line
+ * breaks included, become one space; control and format characters go; the id
+ * is cut at {@link TELEGRAM_CLAIMED_AUTHOR_MAX} characters with an ellipsis.
+ * Used by {@link claimedLabelFor} and by the `(author)` tag on each claimed
+ * row, which carries the same id. A computed row's origin is a fixed word, so
+ * this changes nothing there.
  */
-export const TELEGRAM_CLAIMED_HEADING_PREFIX = "WHAT THIS DOES — CLAIMED by";
-export const TELEGRAM_CLAIMED_HEADING_SUFFIX = "NOT verified by the runtime";
-export const TELEGRAM_CLAIMED_CONTINUED_HEADING = `WHAT THIS DOES (continued) — CLAIMED, ${TELEGRAM_CLAIMED_HEADING_SUFFIX}`;
+export function oneLineAuthor(author) {
+    const flat = author
+        .replace(/\s+/gu, " ")
+        .replace(/[\p{Cc}\p{Cf}]/gu, "")
+        .trim();
+    const chars = Array.from(flat);
+    const shown = chars.length > TELEGRAM_CLAIMED_AUTHOR_MAX
+        ? `${chars.slice(0, TELEGRAM_CLAIMED_AUTHOR_MAX - 1).join("")}…`
+        : flat;
+    return shown.length === 0 ? "unknown" : shown;
+}
 /**
  * The most members one digest may carry (APRV-115).
  *
@@ -361,6 +419,29 @@ export const TELEGRAM_TERMINAL_HEADLINES = {
     expired: "✗ EXPIRED — the approval window closed",
     withdrawn: "WITHDRAWN — no decision is needed",
 };
+/**
+ * The headline a "Looks wrong" tap settles its card on (amended SPEC.md §8,
+ * the study record). The record underneath is an ordinary `approval.rejected`;
+ * this says, in the resident's words, that the card was skipped because they
+ * flagged it. Emoji-free like every other headline here.
+ */
+export const TELEGRAM_LOOKS_WRONG_HEADLINE = "SKIPPED — you flagged this as looks wrong";
+/**
+ * The label of the study-mode button (amended SPEC.md §8, the study record).
+ * Drawn only while the listener was launched with `APPROVAL_STUDY_MODE=1`, on a
+ * row of its own under Approve and Reject. Its verb is `w`, a reject with the
+ * `looks_wrong` flag.
+ */
+export const TELEGRAM_LOOKS_WRONG_LABEL = "🚩 Looks wrong";
+/**
+ * The headline a card settles on when the study team withdrew its request
+ * (amended SPEC.md §8, the study record: an `approval.rejected` carrying
+ * `payload.study.reason` `study_withdrawn`). It replaces "✗ REJECTED" for that
+ * record only, so the resident reads that nobody they know said no and that
+ * nothing ran. The operator id in the record is never shown. Emoji-free like
+ * every other headline here.
+ */
+export const TELEGRAM_STUDY_WITHDRAWN_HEADLINE = "WITHDRAWN BY THE STUDY TEAM";
 /** Whether a derived request state is one an annotation can settle a message on. */
 export function isTelegramTerminalState(state) {
     return Object.prototype.hasOwnProperty.call(TELEGRAM_TERMINAL_HEADLINES, state);
@@ -736,16 +817,16 @@ export function renderTelegram(request, heading = TELEGRAM_PROMPT_HEADING, layou
             claimedLines.push(entry);
     }
     const author = request.summary.kind === "claimed" ? request.summary.author : "the requesting party";
-    const render = (entry) => `• <b>${escapeHtml(entry.label)}:</b> ${escapeHtml(entry.text)} <i>(${escapeHtml(entry.origin)})</i>`;
+    const render = (entry) => `• <b>${escapeHtml(entry.label)}:</b> ${escapeHtml(entry.text)} <i>(${escapeHtml(oneLineAuthor(entry.origin))})</i>`;
     const header = [
         `<b>${escapeHtml(heading)}</b>`,
         `<code>${escapeHtml(request.action_key.value)}</code>`,
         "",
-        "<b>COMPUTED — derived by the runtime from the log, the policy and the payload bytes</b>",
+        `<b>${TELEGRAM_COMPUTED_HEADING}</b>`,
         ...computedLines.map(render),
     ].join("\n");
     const claimedText = [
-        `<b>${TELEGRAM_CLAIMED_HEADING_PREFIX} ${escapeHtml(author)}, ${TELEGRAM_CLAIMED_HEADING_SUFFIX}</b>`,
+        `<b>${escapeHtml(claimedLabelFor(author))}</b>`,
         ...claimedLines.map(render),
     ].join("\n");
     return {
@@ -1048,44 +1129,33 @@ export function groupForDigest(requests, max = TELEGRAM_DIGEST_MAX_MEMBERS) {
     return groups;
 }
 /**
- * The computed facts a digest's members share, as the digest states them.
+ * The one computed line a digest states about its members (P-9).
+ *
+ * Read off the members themselves, which is sound precisely because the
+ * grouping key made them alike: a digest whose members disagreed about their
+ * class or their task is a digest the listener would not have built. What the
+ * line says is the thing an approver needs before the buttons: why these are
+ * one message, and that every request it decides is shown in full above it
+ * (SPEC.md §10.3).
  *
- * Every one is read off the first member, which is sound precisely because the
- * grouping key made them equal across the set: a digest whose members disagreed
- * about their class or their task is a digest the listener would not have
- * built. The last line is the one an approver needs most — it says how many
- * payloads are above and that each request has its own.
+ * Before P-9 this was five facts with origin tags: the class name, the
+ * autonomy, the task id, the grouping key (`keys:body,from,subject,to`) and the
+ * payload binding. Each is still on every member's own card above, where an
+ * operator who wants it finds it; the digest is where a resident answers, and
+ * there it was ids and vocabulary between them and the buttons.
  */
-export function digestFacts(members) {
+export function digestLine(members) {
     const first = members[0];
     if (first === undefined)
-        return [];
-    // APRV-287. A digest may now carry the several classes of ONE tool call, so
-    // the class line states the set rather than the first member's, and the
-    // grouping line says which of the two groupings put this set together. A
-    // digest whose members share one class reads exactly as it did.
-    const classes = [...new Set(members.map((member) => member.class.value))];
-    const shared = sharedPayload(members);
-    const autonomies = [...new Set(members.map((member) => member.autonomy.value))];
-    return [
-        { label: "class", text: classes.join(", "), origin: originOf(first.class) },
-        { label: "autonomy", text: autonomies.join(", "), origin: originOf(first.autonomy) },
-        { label: "task", text: first.task.value ?? "(none)", origin: originOf(first.task) },
-        {
-            label: "grouped by",
-            text: shared === null
-                ? `one class, one task, one payload shape (${payloadShapeKey(first.fullPayload.value?.value)})`
-                : `one tool call: one task, one payload, ${String(classes.length)} class(es) of the same command`,
-            origin: "grouping",
-        },
-        {
-            label: "payloads",
-            text: shared === null
-                ? `${members.length} full payloads, one per request, in the ${members.length} prompts above this message`
-                : `one payload, shared by all ${members.length} requests, in the prompt above this message`,
-            origin: originOf(first.fullPayload),
-        },
-    ];
+        return "";
+    const count = String(members.length);
+    if (sharedPayload(members) !== null) {
+        return `All ${count} are about one action, shown once in full above.`;
+    }
+    const task = first.task.value;
+    return task === null || task.length === 0
+        ? `All ${count} are the same kind of request. Each one is shown in full above.`
+        : `All ${count} come from the same task. Each one is shown in full above.`;
 }
 /**
  * The one payload every member is about, or `null` when they differ
@@ -1113,36 +1183,56 @@ function sharedPayload(members) {
 }
 /**
  * The collapsed re-delivery's own message: what is waiting, and one way to
- * clear it (APRV-287).
+ * clear it (APRV-287), in a resident's words (P-9).
+ *
+ * Everything above the claimed label is computed by the runtime from the
+ * verified log (the reminder's count, why nobody is waiting, each member's
+ * age), and the per-member lines carry the agent's own summaries under a label
+ * that says they are the agent's and were not checked, exactly as an ordinary
+ * digest does (SPEC.md §9: computed and claimed stay visibly separate). What it
+ * does NOT carry is any payload, and the footer says so in the same breath as
+ * it explains why the only button rejects: a decision is bound to the bytes the
+ * approver was shown, and nothing here shows them.
  *
- * Everything above the buttons is computed by the runtime from the verified log
- * — the count, the ages, the classes — and the per-member lines carry the
- * agent's own summaries under a heading that says so, exactly as an ordinary
- * digest does. What it does NOT carry is any payload, and the message says so
- * in the same breath as it explains why the only button rejects: a decision is
- * bound to the bytes the approver was shown, and nothing here shows them.
+ * Before P-9 each member line led with its action key, and the text explained
+ * the hook's wait, log events and `approval grant <action key>`. None of that
+ * helps the person holding the phone, so a member is now its summary and its
+ * age, and the footer says what they can do: use the earlier message if its
+ * buttons still work (`staleCopy`), or let the agent ask again.
  */
 function renderStaleSummary(digest, stale, open, total) {
+    // P-9: the restart's one reminder, while every member is still open. Its
+    // first line is the headline; any further line (what follows this message)
+    // goes after the computed lines, which say what this message lists.
+    const reminder = open === total ? (stale.reminder ?? []) : [];
+    const headline = reminder[0] ??
+        (open === 0
+            ? `All ${String(total)} older requests decided`
+            : open === total
+                ? `${String(open)} older request${open === 1 ? " is" : "s are"} still open`
+                : `${String(open)} of ${String(total)} older requests still open`);
     const lines = [
-        `<b>${escapeHtml(open === 0
-            ? `ALL ${total} STALE REQUESTS DECIDED`
-            : `${open} STALE REQUEST${open === 1 ? "" : "S"} — NOBODY IS WAITING ON ${open === 1 ? "IT" : "THEM"}`)}</b>`,
+        `<b>${escapeHtml(headline)}</b>`,
+        ...stale.lines.map((line) => escapeHtml(line)),
+        ...reminder.slice(1).map((line) => escapeHtml(line)),
         "",
-        "<b>COMPUTED — derived by the runtime from the log and the policy</b>",
-        ...stale.lines.map((line) => `• ${escapeHtml(line)}`),
-        ...digest.facts.map((fact) => `• <b>${escapeHtml(fact.label)}:</b> ${escapeHtml(fact.text)} <i>(${escapeHtml(fact.origin)})</i>`),
-        "",
-        `<b>CLAIMED — authored by ${escapeHtml(digest.author)}, NOT verified by the runtime</b>`,
+        `<b>${escapeHtml(claimedLabelFor(digest.author))}</b>`,
     ];
     for (const [index, member] of digest.members.entries()) {
-        lines.push(`${index + 1}. <code>${escapeHtml(member.actionKey)}</code> — ${escapeHtml(member.summary)}`);
+        const age = stale.ages?.[index];
+        lines.push(`${index + 1}. ${escapeHtml(member.summary)}${age === undefined ? "" : ` · ${escapeHtml(age)}`}`);
         if (member.settled !== null) {
             lines.push(`   <b>${escapeHtml(member.settled.headline)}</b>`);
             for (const detail of member.settled.detail)
                 lines.push(`   ${escapeHtml(detail)}`);
         }
     }
-    lines.push("", escapeHtml("These asked while a hook waited, and the wait is long over: no tool call is holding the answer. This message carries NO payload, so it offers no approve button — a decision is bound to the bytes you were shown, and nothing here shows them. Rejecting is one log event per request and authorizes nothing. To approve one instead, decide it on its own card or run `approval grant <action key>`; the requests stay listed by /queue either way."));
+    if (open > 0) {
+        const approve = stale.staleCopy === false
+            ? "To approve one, ask your agent to try again."
+            : "To approve one, use its earlier message if you still have it, or ask your agent to try again.";
+        lines.push("", escapeHtml(`This message does not show what they would send, so it has no approve button. ${approve} Reject all turns down only ${open === 1 ? "this one" : `these ${String(open)}`}.`));
+    }
     const rows = open === 0
         ? []
         : [
@@ -1161,10 +1251,10 @@ function renderStaleSummary(digest, stale, open, total) {
 /** The digest's headline, given how much of it is still open. */
 function digestHeadline(open, total) {
     if (open === 0)
-        return `ALL ${total} REQUESTS DECIDED`;
+        return `All ${total} requests decided`;
     if (open === total)
-        return `${total} REQUESTS AWAITING APPROVAL`;
-    return `${open} OF ${total} REQUESTS STILL AWAITING APPROVAL`;
+        return `${total} requests are waiting for you`;
+    return `${open} of ${total} requests still waiting for you`;
 }
 /**
  * The digest message: text plus the keyboard for whatever is still open.
@@ -1186,23 +1276,28 @@ export function renderDigest(digest) {
     const stale = digest.stale ?? null;
     if (stale !== null)
         return renderStaleSummary(digest, stale, open.length, total);
+    // P-9: a headline, one computed line, then the agent's own words under a
+    // label that says they are the agent's and unchecked. No action key: the
+    // members are told apart by number, and the numbers are on the buttons.
     const lines = [
         `<b>${escapeHtml(digestHeadline(open.length, total))}</b>`,
+        escapeHtml(digest.line),
         "",
-        "<b>COMPUTED — derived by the runtime from the log and the policy</b>",
-        ...digest.facts.map((fact) => `• <b>${escapeHtml(fact.label)}:</b> ${escapeHtml(fact.text)} <i>(${escapeHtml(fact.origin)})</i>`),
-        "",
-        `<b>CLAIMED — authored by ${escapeHtml(digest.author)}, NOT verified by the runtime</b>`,
+        `<b>${escapeHtml(claimedLabelFor(digest.author))}</b>`,
     ];
     for (const [index, member] of digest.members.entries()) {
-        lines.push(`${index + 1}. <code>${escapeHtml(member.actionKey)}</code> — ${escapeHtml(member.summary)} · ${escapeHtml(member.cost)}`);
+        lines.push(`${index + 1}. ${member.kind === undefined ? "" : `${escapeHtml(member.kind)} — `}${escapeHtml(member.summary)} · agent's estimate ${escapeHtml(member.cost)}`);
         if (member.settled !== null) {
             lines.push(`   <b>${escapeHtml(member.settled.headline)}</b>`);
             for (const detail of member.settled.detail)
                 lines.push(`   ${escapeHtml(detail)}`);
         }
     }
-    lines.push("", escapeHtml(`Each button decides ONE request, numbered as above. "all" is ${open.length} separate decisions, one log event each; the full payload of every request is in the messages above this one.`));
+    if (open.length > 0) {
+        lines.push("", escapeHtml(open.length > 1
+            ? `Each button answers one request, by number. "All" answers every request still open.`
+            : "Each button answers one request, by number."));
+    }
     const rows = [];
     for (const [index, member] of digest.members.entries()) {
         if (member.settled !== null)
@@ -1262,6 +1357,17 @@ export const ACTION_REF_HEX = 16;
 export function actionRefOf(actionKey) {
     return createHash("sha256").update(actionKey, "utf8").digest("hex").slice(0, ACTION_REF_HEX);
 }
+/** How many hex characters of the key's sha256 a study log line carries. */
+export const STUDY_LOG_REF_HEX = 12;
+/**
+ * The short reference a "Looks wrong" detection line names (amended SPEC.md
+ * §8): the first {@link STUDY_LOG_REF_HEX} hex of the key's sha256, a prefix of
+ * {@link actionRefOf}, so an operator holding the key can match the line and a
+ * reader holding the line cannot recover the key.
+ */
+export function studyLogRefOf(actionKey) {
+    return actionRefOf(actionKey).slice(0, STUDY_LOG_REF_HEX);
+}
 /**
  * `callback_data` for one button: `<g|r>:<nonce>:<action ref>`.
  *
@@ -1368,13 +1474,23 @@ const CALLBACK_VERBS = {
     G: { decision: "grant", scope: "all" },
     R: { decision: "reject", scope: "all" },
 };
-export function parseCallbackData(data) {
+/**
+ * The study-mode verb (amended SPEC.md §8), in a table of its own so that the
+ * base vocabulary above is untouched. Consulted only when the caller passes
+ * `study`, which a listener does only when it was launched with
+ * `APPROVAL_STUDY_MODE=1`; otherwise `w:` is no verb at all and the callback is
+ * malformed, exactly as before the verb existed.
+ */
+const STUDY_CALLBACK_VERB = { decision: "reject", scope: "one", flag: "looks_wrong" };
+export function parseCallbackData(data, study = false) {
     if (typeof data !== "string")
         return null;
     const first = data.indexOf(":");
     if (first === -1)
         return null;
-    const verb = CALLBACK_VERBS[data.slice(0, first)];
+    const head = data.slice(0, first);
+    const studyVerb = study && head === "w";
+    const verb = studyVerb ? STUDY_CALLBACK_VERB : CALLBACK_VERBS[head];
     if (verb === undefined)
         return null;
     const rest = data.slice(first + 1);
@@ -1387,6 +1503,7 @@ export function parseCallbackData(data) {
         scope: verb.scope,
         nonce,
         actionRef: second === -1 ? null : rest.slice(second + 1),
+        ...(studyVerb ? { flag: STUDY_CALLBACK_VERB.flag } : {}),
     };
 }
 // ---------------------------------------------------------------------------
@@ -2082,6 +2199,11 @@ export class TelegramChannel {
      * carries can change it.
      */
     staleCopy;
+    /**
+     * Study mode (amended SPEC.md §8). Fixed at construction from
+     * {@link TelegramConfig.study}; nothing an update carries can change it.
+     */
+    study;
     /**
      * Where a `nonce-not-issued` refusal is recorded (APRV-456). The runtime's,
      * like every other handler here; absent, the refusal still happens and only
@@ -2240,6 +2362,8 @@ export class TelegramChannel {
         // APRV-456. Only an explicit `true` or an absent key leaves the fallback on;
         // anything else a caller passes turns it off, the stricter direction.
         this.staleCopy = config.staleCopy === undefined || config.staleCopy === true;
+        // Only an explicit `true` turns study mode on; anything else is off.
+        this.study = config.study === true;
         this.makeNonce =
             config.nonce ??
                 (() => {
@@ -2277,6 +2401,10 @@ export class TelegramChannel {
     staleCopyEnabled() {
         return this.staleCopy;
     }
+    /** Whether study mode is on (amended SPEC.md §8): fixed at construction. */
+    studyModeEnabled() {
+        return this.study;
+    }
     /**
      * Register what to do with a checkpoint tap (APRV-257).
      *
@@ -2498,7 +2626,10 @@ export class TelegramChannel {
     async notifyStale(members, stale) {
         if (members.length === 0)
             return null;
-        return this.deliverDigest(members, `tg-batch-${this.makeNonce()}`, stale);
+        return this.deliverDigest(members, `tg-batch-${this.makeNonce()}`, {
+            ...stale,
+            staleCopy: stale.staleCopy ?? this.staleCopy,
+        });
     }
     /**
      * The digest itself: every member's prompt and payload, then the one message
@@ -2520,6 +2651,7 @@ export class TelegramChannel {
         const windowMs = windows.includes(null)
             ? null
             : Math.max(...windows.filter((window) => window !== null));
+        const mixedClasses = new Set(members.map((member) => member.class.value)).size > 1;
         const state = {
             deliveredAtMs,
             windowMs,
@@ -2528,13 +2660,14 @@ export class TelegramChannel {
             batchDeliveryId,
             allNonce,
             stale,
-            facts: stale === null ? digestFacts(members) : [],
+            line: stale === null ? digestLine(members) : "",
             author: originOf(members[0].summary),
             members: members.map((member) => ({
                 actionKey: member.action_key.value,
                 nonce: this.makeNonce(),
                 summary: member.summary.value ?? "(none given)",
                 cost: `$${member.est_cost_usd.value.toFixed(2)}`,
+                ...(mixedClasses ? { kind: member.class.value } : {}),
                 settled: null,
             })),
         };
@@ -2557,12 +2690,12 @@ export class TelegramChannel {
         }
         else if (shared === null) {
             for (const [index, member] of members.entries()) {
-                const one = await this.sendPrompt(member, `REQUEST ${index + 1} OF ${members.length} — decide it on the digest below`, null);
+                const one = await this.sendPrompt(member, `Request ${index + 1} of ${members.length} — answer it on the summary below`, null);
                 rendered.push({ ...one.rendered, batchDeliveryId });
             }
         }
         else {
-            const one = await this.sendPrompt(shared, `THE COMMAND ALL ${members.length} REQUESTS ARE ABOUT — decide it on the digest below`, null);
+            const one = await this.sendPrompt(shared, `What all ${members.length} requests are about — answer them on the summary below`, null);
             for (const member of members) {
                 rendered.push({
                     ...one.rendered,
@@ -2631,7 +2764,7 @@ export class TelegramChannel {
             for (const [index, chunk] of chunks.entries()) {
                 const label = chunks.length === 1
                     ? `<b>${PAYLOAD_CHUNK_LABEL}</b>`
-                    : `<b>PAYLOAD ${index + 1}/${chunks.length} — ${PAYLOAD_CHUNK_LABEL_TAIL}</b>`;
+                    : `<b>${PAYLOAD_CHUNK_LABEL} (part ${index + 1} of ${chunks.length})</b>`;
                 segments.push(`${label}\n<pre>${escapeHtml(chunk)}</pre>`);
             }
         }
@@ -2665,6 +2798,27 @@ export class TelegramChannel {
             },
         };
     }
+    /**
+     * The study-mode row under a per-request card (amended SPEC.md §8): one
+     * "Looks wrong" button on a row of its own, so the Approve/Reject row keeps
+     * its bytes and layout. Empty when study mode is off, which leaves the
+     * keyboard exactly as it was before study mode existed.
+     *
+     * Empty on a policy attestation prompt too (APRV-528). Such a prompt is
+     * answered by attesting or declining, and `channels/contract.ts` routes its
+     * gesture to the attestation path, which records no study reason: a flag
+     * drawn there would be counted by the detection line yet held by no log
+     * record. The prompt is known by its `policy_diff` and, as the contract
+     * routes it, by its `policy.attest:` key.
+     */
+    studyRows(nonce, request) {
+        if (!this.study)
+            return [];
+        const actionKey = request.action_key.value;
+        if (request.policy_diff !== undefined || isAttestationActionKey(actionKey))
+            return [];
+        return [[{ text: TELEGRAM_LOOKS_WRONG_LABEL, callback_data: callbackData("w", nonce, actionKey) }]];
+    }
     async deliverOne(request, batchDeliveryId) {
         const actionKey = request.action_key.value;
         const nonce = this.makeNonce();
@@ -2674,6 +2828,7 @@ export class TelegramChannel {
                     { text: "✅ Approve", callback_data: callbackData("g", nonce, actionKey) },
                     { text: "🛑 Reject", callback_data: callbackData("r", nonce, actionKey) },
                 ],
+                ...this.studyRows(nonce, request),
             ],
         };
         // APRV-489. The minimal card is tried only when the policy asked for it,
@@ -2762,6 +2917,7 @@ export class TelegramChannel {
                             { text: "✅ Approve", callback_data: callbackData("g", nonce, actionKey) },
                             { text: MINIMAL_DENY_LABEL, callback_data: callbackData("r", nonce, actionKey) },
                         ],
+                        ...this.studyRows(nonce, request),
                     ],
                 },
             });
@@ -3605,7 +3761,9 @@ export class TelegramChannel {
             await this.handleReviewTap(review, callbackId, result, sender);
             return;
         }
-        const parsed = parseCallbackData(query["data"]);
+        // The study verb `w` parses only when this listener was launched in study
+        // mode; otherwise it is malformed below, exactly as before it existed.
+        const parsed = parseCallbackData(query["data"], this.study);
         if (parsed === null) {
             await this.ignore(result, callbackId, "malformed-callback", `callback_data ${JSON.stringify(query["data"])} is not a decision this channel issued`, "Unrecognized button.");
             return;
@@ -3683,6 +3841,9 @@ export class TelegramChannel {
             ...(parsed.decision === "reject"
                 ? { note: `${TELEGRAM_REJECT_NOTE} (callback ${callbackId})` }
                 : {}),
+            // Amended SPEC.md §8. A "Looks wrong" tap is this same reject with the
+            // flag recorded; every check above and below is a Deny's.
+            ...(parsed.flag === "looks_wrong" ? { study: { reason: "looks_wrong" } } : {}),
         };
         if (this.handler === null) {
             await this.ignore(result, callbackId, "unknown-callback", "a callback arrived before the runtime registered a decision handler", "The runtime is not ready to record decisions.");
@@ -3750,9 +3911,17 @@ export class TelegramChannel {
             return;
         }
         const record = outcome.record;
-        const headline = outcome.decision === "grant"
-            ? TELEGRAM_TERMINAL_HEADLINES.granted
-            : TELEGRAM_TERMINAL_HEADLINES.rejected;
+        const lookedWrong = parsed.flag === "looks_wrong" && outcome.decision === "reject";
+        if (lookedWrong) {
+            // The detection line: the 12-hex reference and nothing else. Never the
+            // key text, a chat id, a sender id or any card text.
+            this.complain(`approval: telegram looks_wrong ref=${studyLogRefOf(delivery.actionKey)}`);
+        }
+        const headline = lookedWrong
+            ? TELEGRAM_LOOKS_WRONG_HEADLINE
+            : outcome.decision === "grant"
+                ? TELEGRAM_TERMINAL_HEADLINES.granted
+                : TELEGRAM_TERMINAL_HEADLINES.rejected;
         try {
             await this.annotate(delivery.deliveryId, headline, [decidedLine(record.actor, record.ts, record.seq)], delivery.actionKey);
         }