approval-md 0.4.0 → 0.4.1

package/docs/cli-reference.md

@@ -311,6 +311,64 @@ that is due to a refusal of anything: it is a warning on `log verify`, a
 doctor`'s `checkpoint` row. A gate that held up an action for want of a tap is a
 gate whose operator turns the check off.
 
+## log unlock
+
+Takes over `events.jsonl.lock` from a writer that died holding it, when no
+writer could do that itself, and records it.
+
+```
+approval log unlock --pid <n|none> --as human:<id> [--log <path>] [--json]
+```
+
+**Why a person.** Every writer that finds the lock held waits out its whole
+lock timeout (two seconds) and then judges the holder once. It takes the lock
+back by itself only when it can prove the holder gone: the holder ran in this
+writer's own pid namespace and boot, and `kill(pid, 0)` answers ESRCH (on Linux
+also with `/proc/<pid>` absent or a zombie, or the pid now names a process that
+started later), or the lockfile names no holder, is ten minutes old, and sat
+unchanged through the writer's whole wait (a try-once caller never takes it). Any
+other holder (another container, another boot, a pid answering EPERM, a `/proc`
+it cannot read) is never taken automatically, because a wrong reclaim forks the
+chain. The writer's `lock-timeout` refusal then names the pid and this command.
+
+**What it does.** It reads the lockfile strictly, refuses a `--pid` that is not
+the one the record names (`none` for a lockfile with no holder record), refuses
+a holder it sees running (Linux: the same start time in this namespace;
+elsewhere: the pid on this host in this boot), and refuses beside a `log sync`
+snapshot. It then takes the lock exactly as a writer's reclaim does (an
+exclusive `link(2)` to `<lock>.stale.<pid>.<created ms>`, then a `rename(2)` of
+its own lockfile over the lock's path) and appends `audit.lock_reclaimed` as the
+first record under it, with your `human:` actor, reason `operator-cleared` (your
+word, which the log never presents as a writer's proof), the strictly parsed
+holder and the lock's age. A holder `created` the log cannot vouch for (more
+than a day before the log's last record, or more than five minutes ahead of
+this clock) is recorded as `null`, with no age. A stale name a dead reclaimer or
+anyone else left is cleared first, and a dead reclaimer's own
+`<lock>.take.<pid>.*` file with it. Anything at the lock's path that is not a
+lockfile (a FIFO, a link, a malformed file) is not taken: the refusal says to
+`rm -v` it.
+
+It also refuses, touching nothing:
+
+- while a reclaim is in flight: a writer writes its own
+  `<lock>.take.<pid>.<nonce>` before it claims, and a running one is named, so
+  a reclaimer that is stopped (SIGSTOP, a debugger) is never unlocked around;
+- when the record could not be appended: a daemon whose id the attested
+  policy refuses, or a torn tail (repair the tail first);
+- when the claim is refused EPERM or EACCES (Linux `fs.protected_hardlinks`:
+  the lockfile is another user's): the refusal names the owner's uid; run it as
+  that user or root, or `rm -v` the lockfile once no writer runs;
+- when a directory sits at the stale name: the refusal names `rm -r` for it.
+
+**Run it only when no writer is running.** The verb asserts, on your word, that
+the holder is gone. Human-only: the actor comes from `--as` or `APPROVAL_HUMAN`,
+the schema refuses an `agent:` actor on the record, and `core/command-class.ts`
+classifies `approval log unlock` (and `node <cli> log unlock`) `policy.core`, so the harness hook denies an agent
+that tries it that way. Other spellings (`npx approval log unlock`, `npm exec`,
+a wrapper script) classify as workspace writes, and `--as` is the caller's to
+set, so the classification is a speed bump rather than the boundary (APRV-491).
+Exit 0 when it unlocked or there was no lock; 4 when it refused.
+
 ## log follow
 
 `approval log follow --from <seq> --json` is the channel-independent decision
@@ -3538,20 +3596,113 @@ carries in the open.
 
 ## audit review
 
+**The reviewer must be on the class's roster (APRV-483).** Where the policy rule
+that resolves the sampled action's class names `approvers`, the reviewer must be
+one of them, compared exactly as a grant's approver is (`namesApprover` in
+`core/gate.ts`): a bare id on the roster matches `human:<id>`. Anyone else is
+refused `actor-not-approver` (exit 1) and nothing is appended. This binds every
+surface, because the check is in `reviewSample` itself: `--as human:<id>` at a
+terminal and a sender-mapped tap on a Telegram card are held to the same list.
+A rule that names no `approvers` restricts nobody, exactly as for grants. The
+class comes from the action's registration (a sample naming no class is refused
+`actor-not-approver`, never read as "no roster"), and the roster is read from
+the policy file a grant would read, only when its bytes are the latest
+attestation's: an unattested, edited, unreadable or `--policy`-substituted file
+is refused `policy-not-attested` (exit 1), because a roster read from a file
+nobody attested is one the reviewer could have chosen. Attested bytes that do not
+load (a schema-invalid rule, a YAML error) are refused `policy-invalid` (exit 1):
+`policy attest` hashes bytes without parsing them, and the fail-closed reading
+of a broken policy names no roster, which for a review would mean anyone. Nothing
+resolves from a broken file, so an on-roster reviewer is refused too; the repair
+is a corrected policy, attested.
+
+**The roster is the one in force when the action ran (PR #614 refutation F2,
+recheck NF-3).** Every `audit.sampled` the runtime writes pins the attested
+policy the sampled execution ran under, as `payload.policy_sha256`: the
+`sha256` named by the latest `policy.updated` attestation before the
+`execution.started` record, which is the policy the gate checked when it
+recorded the start (a harness start carries the same hash as its own
+`policy_sha256`). A policy attested between the run and the sweep therefore
+changes neither who may review the sample nor whether anyone can. Only an
+execution older than every attestation in the log pins the latest attestation
+at sampling instead. A review of that sample reads the
+roster only from policy bytes that hash to the pin, and only when an
+attestation before the sample names that hash. The bytes come from the payload
+store beside the log, where every attestation since APRV-356 keeps the text it
+attested (PR #614 fix round 3), so editing and re-attesting the policy, a
+settings save from the app included, leaves older open samples reviewable. The
+policy file on disk is the fallback, used only when its bytes hash to the pin
+(a chain last attested before APRV-356 stored none). Bytes in neither place are
+refused `policy-not-attested`, and the message names the hash it needs. A later
+re-attestation that renames or drops the class's rule therefore cannot leave
+the sample with no roster, and one that names a different roster cannot open
+it to a reviewer the action's policy did not name. A class that matches no rule in the pinned policy
+(it reached supervised through `defaults.autonomy`) is refused
+`actor-not-approver` with that reason, because the defaults carry no roster
+and for a review "no roster" would mean anyone. A sample written before samples
+pinned a policy has no `policy_sha256` and keeps the latest-attestation reading
+above.
+
+Exactly one of `--ok` and `--deny` is required (APRV-482). A bare review, or one
+carrying only `--reaction`, is refused `verdict-required` (exit 1) and writes
+nothing: under supervised-retro the review counts as the approval, and an
+approval is something the reviewer says, never a default. Both flags together
+is a usage error (exit 2). The verdict is judged after the roster (PR #614
+refutation N6): a reviewer off the roster is told `actor-not-approver` whether
+or not they gave a verdict, and a grade with no verdict is not judged for its
+note until the verdict comes.
+
 `--note` is optional — unlike `execution resolve`, this event records only that a
 person looked, and the runtime is not relying on the note for a fact it does not
 otherwise have. Human-only: a runtime that could mark its own samples reviewed
 would be a supervision backlog that empties itself.
 
-No attestation is required, for the reason `execution resolve` states: review
-records an observation, exercises no policy authority, authorizes nothing, and
-spends no budget. A review blocked because a policy file was edited afterwards
-would be a supervision backlog held open by an unrelated fact.
-
-What it appends is `audit.reviewed`, naming the sample's action key and task, with
-payload `{"subject_seq":<seq of the audit.sampled>,"reviewed":true,"note"?:"...",
-"reaction"?:"disliked"|"indifferent"|"liked"|"loved"}`.
-An action key with several open samples refuses `ambiguous-subject`.
+Since APRV-483 a review needs the attested policy, because its roster check
+reads the class's `approvers` from it (below). Before that no attestation was
+required, for the reason `execution resolve` states: review recorded an
+observation and exercised no policy authority. Under supervised-retro the
+review is the approval, and the trade is stated plainly: a policy edited and not
+yet re-attested now holds the review backlog open until a human re-attests.
+
+What it appends is `audit.reviewed`, naming the sample's action key and task; its
+payload is listed field by field under [the review record](#the-review-record),
+which is the one place those names are defined. An action key with several open
+samples refuses `ambiguous-subject`.
+
+### The review record
+
+The field names a follower reads (the data pipeline's follower and the dbt
+models built on it read reviews as approvals under supervised-retro). This
+table is the single definition; other docs link here rather than restating it.
+Every `audit.reviewed` written since APRV-481 carries the three required fields,
+and since PR #614's F5 fix a fourth, `verdict_source`; the write boundary refuses
+one that does not. The verdict alone cannot say whether the reviewer gave it:
+before APRV-482 the runtime wrote `ok` for a grade-only tap or a bare
+`audit review`, and such a record may carry all three APRV-481 fields, so
+`verdict_source` is the field that separates the two. A review written before then
+may lack them and still verifies (the read boundary is the schema's
+`audit_reviewed_record_historical`), so a follower treats their absence on an
+old record as "not recorded", never as a default.
+
+| Field | Where | Required | Meaning |
+| --- | --- | --- | --- |
+| `event` | record | yes | `audit.reviewed`. |
+| `seq`, `ts`, `hash` | record | yes | The review's own chain position and runtime-assigned time. |
+| `actor` | record | yes | `human:<id>`, the reviewer. Since APRV-483 a person on the class's `approvers` roster wherever the rule names one. |
+| `action_key`, `task` | record | when the sample named them | The reviewed action and its task. |
+| `channel` | record | no | The surface, when the writer recorded one. |
+| `payload.subject_seq` | payload | yes (APRV-481) | The `seq` of the `audit.sampled` record this review answers. Not the execution's seq. |
+| `payload.sampled_subject_hash` | payload | yes (APRV-481) | The `hash` of the `execution.started` record the sample named: the join key from a review to the execution it judged. |
+| `payload.verdict` | payload | yes (APRV-481) | `ok` or `denied`. The enforcement field. Explicit only on records that carry `verdict_source`. |
+| `payload.verdict_source` | payload | yes (PR #614 F5) | Always `explicit`: the reviewer said the verdict (`--ok`/`--deny`, a card's OK or second Deny). The discriminator for a follower: a review WITHOUT it predates APRV-482 or was written by an older build, and its `ok` may have been defaulted for a grade-only tap or a bare terminal review. Count only reviews carrying it as explicit approvals. |
+| `payload.payload_hash` | payload | no | The SHA-256/JCS binding of the bytes the execution ran, present ONLY when the surface showed those bytes whole before the verdict (a Telegram card's `bytes` view). Absent when the reviewer saw a hash, nothing, or a terminal. Checked against the execution's binding before it is written. |
+| `payload.reaction` | payload | no | `disliked`, `indifferent`, `liked` or `loved`. Guidance, never enforcement; absent is absent. |
+| `payload.note` | payload | with `loved`/`disliked` | The reviewer's words, verbatim. |
+| `payload.sender`, `payload.sender_source` | payload | no | The authenticated account the review arrived from, when a transport authenticated one. |
+| `payload.subject_event`, `payload.reviewed` | payload | no | Constants (`audit.sampled`, `true`) kept for older readers. |
+
+A denial is followed by a runtime-authored `reconciliation.required` whose
+`payload.review_seq` is the review's `seq`.
 
 **`--json`** (one object on stdout):
 
@@ -3920,6 +4071,224 @@ turn on was already on the `ChannelRequest`, and `--json`, `approval queue` and
 the web page carried it all along; rendering stays a pure function of
 (request, layout).
 
+### The minimal card: `channels.telegram.prompt.style` (APRV-489)
+
+The technical card is three messages written for an engineer. A resident
+approving on a phone needs to know what their agent wants to do, the exact
+words it will act on, how long they have, and where the buttons are.
+`style: minimal` sends that as ONE message, with the whole technical card
+collapsed inside it:
+
+```yaml
+channels:
+  telegram:
+    prompt:
+      always: [ttl_remaining_ms]
+      style: minimal            # technical (the default) | minimal
+      say:
+        digest.share:
+          does: "share a note about you with other people"
+          quote: { scope: "Shared with", expires_at: "Until", text: "Note", digest_id: "Reference" }
+          note: none
+```
+
+**For the approver, in plain words.** The bold first line says what your agent
+wants to do. The box under it holds the agent's own words, copied exactly from
+what will be posted, shared or run; approval.md writes nothing inside the box
+except the labels. If a line under the box starts with ⚠ or says "Not shown
+here", the box is not the whole story: open "Full details" before deciding. A
+line marked "not checked" is a description (by an AI model or by your agent)
+that nobody verified. The next line says how long you have; if you do nothing,
+nothing happens. Tap "Full details" to see everything the runtime checked,
+including the exact text this approval is bound to. Approve says yes; Deny says
+no. For anything that deletes, sends files or money, or talks to outside
+services, open "Full details" every time.
+
+**The exact layout** (HTML; `[ ]` are the inline buttons):
+
+```
+<b>Your agent wants to <phrase></b>
+<blockquote><b>Label:</b> quoted value        one payload value per line, verbatim
+…</blockquote>
+⚠ This runs at least 3 commands. Only the beginning is shown above: …   a command, only when cut
+⚠ There is more than fits here: open Full details before deciding.   when any other value was cut
+Not shown here: <key>, <key>. Open Full details before deciding.        when the say entry leaves a field off (~)
+<i>AI summary (not checked):</i> …            only when a model sentence is attached
+<i>Your agent says (not checked):</i> …       only when the class's say entry has note: summary
+<i>Your agent estimates the cost (not checked):</i> $0.00   only when the estimate is above zero
+Open for about 3 days. If you don't answer, your agent will not do this.
+<blockquote expandable><b>Full details (tap to open)</b>
+… the technical card's three messages, in order, character for character …</blockquote>
+[✅ Approve] [✋ Deny]
+```
+
+A tool call the agent is blocked in says "Your agent is waiting: about 4
+minutes left. If you don't answer, it will not do this." instead. The time is
+the gate's own window for the request (the policy's TTL, narrowed by a
+harness hook's cap), from the verified log, as it stood when the card was
+drawn; the line is not refreshed afterwards. A request with no time left says
+"Time is up: this request has closed, and an answer now will not count."
+
+**What is computed, what is quoted, what is described.**
+
+- *Computed by the runtime:* the first line, chosen by the exact class the LOG
+  records: core's own phrase for a class core emits (`network.call`,
+  `read.web`, `browser.exec`, `cron.manage`, `process.write`, `skill.manage`,
+  `agent.delegate`, `message.send`, `files.delete.scratch`); else, for a
+  payload the runtime reads itself, its structural kind ("run a command",
+  "change a file", "send an email", followed by `(type: <class>)`), whatever
+  the class's `say` entry says; else, for an opaque payload only, the attested
+  `say.<class>.does`. The notices under the box; the deadline line; everything
+  in "Full details"; the buttons.
+- *Quoted from the bound payload:* the box, and only payload values. Each line
+  is one payload value, verbatim (marked as below, and visibly cut when long),
+  under a label (the operator's attested label, or the runtime's fixed label
+  for a field of a shape it knows), or alone when it is the only quotation.
+  Nothing computed, abbreviated, joined or paraphrased is ever inside the box;
+  a list of addresses is one line per address. Each value sits inside the
+  runtime's own Unicode isolate (U+2068 … U+2069), so right-to-left letters in
+  it cannot reorder its label or the lines around it. The cut mark is drawn
+  inside the value's isolate, so a cut right-to-left value shows it at its left
+  edge, still visible; the notice under the box says the same thing outside
+  any isolate. The operator's `does` phrase in the headline is not isolated.
+  The bytes were hash-checked against the request's
+  `payload_hash` before the channel saw them, so they are what will be acted
+  on; their content was written by the agent. A command is shown up to 160
+  characters (under `Command:` when its `cwd` is quoted as `In folder:`); a
+  longer one is shown from its start and cut, and only then does a computed
+  line under the box say so ("⚠ This runs at least 3 commands. Only the
+  beginning is shown above", the classifier's count as a lower bound, since it
+  does not see commands started inside other commands such as a
+  here-document piped into `sh`, `$( … )`, `bash -c` or `eval`; "⚠ Only the
+  beginning of this command is shown above" when it counts one; "⚠ More than
+  one command may be here, and only the beginning is shown above" when it
+  cannot count). A command shown whole gets no line: the
+  card makes no claim about how many commands it is. The line never names or
+  paraphrases a command the box does not show; the
+  classifier's outline is in "Full details" only, because it leaves out flags
+  and their values, which is where a deletion target or an uploaded file
+  lives. A file change shows the file, the change and every other field under
+  its own key name (`tool:`, `replace_all: true`). An email shows From, To, Cc,
+  Bcc, Subject, Format and Message. An opaque payload shows the fields its
+  `say.<class>.quote` map labels.
+- *Never a clean-looking partial:* when a command is cut, its computed count
+  line says so; when any other value is cut, "⚠ There is more than fits here:
+  open Full details before deciding." follows the box; when the declaration leaves fields off (`~`),
+  "Not shown here: <their key names>. Open Full details before deciding." does.
+  Both are outside the box, so quoted text can neither produce nor suppress
+  them.
+- *Described, and labelled "not checked":* the AI summary and the agent's own
+  summary and estimate. They never stand alone and never come first: they sit
+  below the box.
+
+**Quoted text is hostile input.** Every quoted value is one line (a line break
+is drawn ` ⏎ `). Control, format, bidirectional and every default-ignorable
+character (variation selectors, joiners, tag characters, U+034F, the Khmer and
+Mongolian invisibles), the Hangul fillers and the braille blank, and combining
+marks beyond two on one character are drawn as `«U+202E»`; so are `«` and `⏎`
+in the value, which makes the marking injective. One exception keeps emoji
+readable: a grapheme cluster that is WHOLLY a recognised emoji sequence
+(Unicode's RGI set, `\p{RGI_Emoji}` with the regular-expression `v` flag: ❤️,
+👨‍👩‍👧, 1️⃣, 👍🏽) is drawn as itself. Every other presentation selector or joiner
+is marked, so a U+FE0F after a face that is already an emoji, or a U+200D
+between two pictographs that form no emoji, cannot carry hidden bits. On a
+runtime without that property nothing is exempt. Node 20, this package's
+floor, ships V8 11.3, which has it. A value longer than 280 characters is
+cut between grapheme clusters with `…(cut; see full details)`, and everything is
+HTML-escaped. A value cannot start a line of its own, close the box, open or
+close the collapsed block, or be bold.
+
+Injective is not "never looks the same". Look-alike letters from other scripts
+(a Cyrillic а for a Latin a), a lone emoji with and without its presentation
+selector, and runs of ordinary spaces are drawn as themselves, so two different
+values can still look alike. Telegram clients also turn URLs, `@names`,
+`#tags` and `/commands` in the box and in "Full details" into links; a link's
+text is always its own target (markup in a value is escaped, so a value cannot
+make link text say something else), but a look-alike domain stays look-alike.
+
+**When the technical card is sent instead.** The minimal card is never guessed
+at or drawn partially. These requests get today's technical card, the decision
+record says why (`payload.rendering.fallback`, below), and the listener says
+so on stderr:
+
+- an attestation prompt, a `policy.*` or `log.*` class, or a protected path;
+- a truncated payload, or none;
+- any abnormal health fact (a budget over its ceiling, a policy not attested,
+  an autonomy that is not `manual`), even when the row layout hides its row;
+- an opaque payload whose class has no `say` entry, carrying a key the entry's
+  `quote` map does not name, or that is not an object;
+- a request delivered as part of a batch: a digest, its members, the collapsed
+  stale-request summary, and a batch whose digest did not fit or has one member;
+- a card over 3800 characters (Telegram's limit is 4096, and a relay's
+  `Agent: <name>` line needs room): the canonical rendering is never cut to fit;
+- a policy file that does not match its attestation (`policy-unattested`);
+- a minimal card the Bot API or a relay refuses (any 4xx but 429): the
+  technical card is sent once instead (`send-refused`); a 429, a 5xx or a
+  network failure is retried by the next cycle as before.
+
+When the edit that settles a minimal card is refused (it replaces the only
+message holding the request), a short settle text with the outcome, the
+request's key and who decided when is sent instead, so a decided card never
+looks undecided.
+
+Review cards ("REVIEW — THIS ALREADY RAN"), their note prompt and checkpoint
+prompts are the same under both styles in this release.
+
+**`say`.** Keyed by EXACT class name: a pattern such as `files.*` is refused at
+load (`prompt-say-wildcard`), because one friendly phrase must never stand for
+several classes. For a class core phrases itself (the list above) core's phrase
+always wins: a `say` entry may set `quote` and `note` for it but not `does`
+(`prompt-say-builtin`). The same holds for a class the command classifier
+emits (`files.delete.out_of_scope`, `vcs.push.main`, `harness.launch.*`, …),
+whose payload is a command or a file change the runtime phrases itself
+(`prompt-say-kind`). For any other class `does` is a phrase for OPAQUE
+payloads only: when a request of that class carries a command, a file change
+or an email, the runtime's kind phrase is drawn instead and the record notes
+`say_does_ignored` (below). For those classes `does` is required and is a verb
+phrase of at most 120 characters that completes "Your agent wants to …": it
+starts with a letter and has no line break, `.` `!` `?` `…` `:` `;`, markup or
+`⚠` (`prompt-say-does`), so operator text cannot read as a second sentence or
+as one of the runtime's notices. `quote` maps every top-level key an opaque
+payload may carry to the label it is quoted under (letters, digits and spaces,
+at most 24; `""` only when it is the only key shown) or to `~` for a key
+deliberately left off, and must show at least one key (`prompt-say-label`,
+`prompt-say-shape`); `note` is `summary` (the default) or `none`. A `say` entry is read only under `style: minimal`. A class
+core phrases itself still needs a `say` entry with a `quote` map when its
+payload is opaque (a Hermes tool payload, `{tool, input}`, is). A `say` entry
+for a class no rule names loads: it applies if that class is ever requested.
+
+**Other channels.** `style` and `say` are validated wherever they appear and an
+unknown value fails the policy closed (`prompt-style-unknown`,
+`prompt-say-shape`, `prompt-say-wildcard` on an untyped channel; the schema's
+own `enum`, `pattern` and shape errors on `telegram`, `web` and `cli`). Only
+Telegram draws a minimal card; the CLI and web channels IGNORE the keys and keep
+their full prompt, which shows more than was asked for rather than less.
+
+**What the record says.** A decision taken on a card drawn under a minimal
+policy carries `payload.rendering` on its `approval.granted` or
+`approval.rejected`: `{"style": "minimal"}`, or `{"style": "technical",
+"fallback": "<reason>"}` when the technical card was sent instead. A minimal
+card whose class's `say` entry set a `does` phrase the runtime did not use
+(the payload was a command, a file change or an email, so the runtime drew its
+own phrase) records `{"style": "minimal", "say_does_ignored": true}`. Under a
+technical policy the key is absent and the record is unchanged. Nothing reads
+it back; it is a statement about the screen the approver answered on. It is an
+OPEN field: `schema/event.schema.json` does not constrain it in this release,
+so a reader with a closed schema for `approval.granted` must admit it.
+
+**Changing it.** It is a policy key, so changing it is an attestation, and a
+decision on a request routed under the old policy is refused `policy-drift`, as
+for any policy change. The Telegram listener resolves `style` and `say` for EACH
+card it draws, and only from attested bytes: it reads the policy file once,
+requires those bytes to hash to the latest attestation in the verified log
+(the digest the gate decides under), and takes the settings from the same
+bytes. A re-attested setting therefore reaches the next card without a
+restart, and an edit to the file that nobody attested changes nothing: the card
+is technical, and when the attested policy asks for minimal the record says
+`fallback: "policy-unattested"`. An older core refuses the keys at the schema, and the
+whole policy then fails closed to all-`manual`: roll the core out before the
+policy that uses them.
+
 ## channel cli
 
 **The rendering convention (SPEC.md §9).** Every displayed field carries a
@@ -4236,6 +4605,34 @@ place in the walkthrough and a duplicate message, never a pending request nobody
 is shown; an approval that depended on a channel's memory would not be an
 acceptable trade.
 
+**Earlier copies, and `--no-stale-copy`** (APRV-196, APRV-456). Every single-request decision
+button carries `<verb>:<nonce>:<action ref>` (a digest's "all" buttons carry no reference and never had a fallback), where the nonce is issued by this
+process and the reference is the first 16 hex of the action key's SHA-256. On
+the direct-bot shape (no `--api-base`, or one naming `https://api.telegram.org`)
+a tap whose nonce this process is not holding, such as a button on a copy sent
+before a restart, falls back to its reference: when this process holds that
+action open on a newer card, the tap decides it there, and the gate judges it
+exactly as it judges any other tap. That fallback is safe because only the bot
+token can put a button in front of the approver.
+
+The fallback is **off** when `--api-base` names anything other than the Bot API
+(a relay, or a self-hosted Bot API server, which this rule treats as a relay)
+and when `--no-stale-copy` is passed. Then a decision tap whose nonce this
+process is not holding is refused `nonce-not-issued` (a member of the channel
+decision refusal union, beside `sender-unmapped`): it never reaches the gate,
+the approver's toast says this listener did not send that button, and the live
+card stays armed. When the tap's reference names a request this process holds
+open, one `audit.decision_refused` records the attempt under that request's key,
+naming the sender the policy resolves; a reference that names nothing open here,
+or a replay of the same button within this process, records nothing (the memory of refused buttons is per process and bounded, so a redelivery after a restart can record once more). The restart banner says that
+earlier copies no longer decide. The reason is the relay: anyone holding its
+token can send the approver a card with forged text and a real pending action's
+reference, and on the fallback the approver's genuine tap would pass the chat
+check and the sender mapping. The flag is launch configuration only: no policy
+key and nothing in an update can set it or clear it. `approval up` and
+[`channel telegram webhook`](#channel-telegram-webhook) take the same flag and
+apply the same rule.
+
 **The execution token is printed on this terminal's stdout and is never sent to
 Telegram.** A chat transcript is stored on someone else's servers, backed up to
 phones, and readable by anyone later added to the chat — it is not a credential
@@ -4279,16 +4676,61 @@ Each `audit.sampled` with no later `audit.reviewed` now arrives as a **review
 card**.
 
 A card is not a prompt and says so. Its headline is `REVIEW — THIS ALREADY RAN`,
-it carries no payload region and no approve button, and it accepts no token: the
-action has happened, and a card offering an approve would present a settled fact
-as a live authorization. What it carries is the same rows a prompt would show
-for the same action — class, the command breakdown, task, the agent's claimed
-summary, the model gloss where one is attached — plus two the card adds: `ran
-at` (the `execution.started` the sample named) and `verdict` (that the runtime
-allowed this without asking, which autonomy said so, the rate it was drawn at,
-and how the log says it ended). Everything computed is derived from the verified
-log, the payload store and the classifier; the claimed rows sit under the same
-"NOT verified by the runtime" heading a prompt gives them.
+it carries no approve button, and it accepts no token: the action has happened,
+and a card offering an approve would present a settled fact as a live
+authorization. What it carries is the same rows a prompt would show for the same
+action — class, the command breakdown, task, the agent's claimed summary, the
+model gloss where one is attached — plus two the card adds: `ran at` (the
+`execution.started` the sample named) and `verdict` (that the runtime allowed
+this without asking, which autonomy said so, the rate it was drawn at, and how
+the log says it ended). Everything computed is derived from the verified log,
+the payload store and the classifier; the claimed rows sit under the same "NOT
+verified by the runtime" heading a prompt gives them.
+
+**The card shows the payload that ran (APRV-480).** Under supervised-retro the
+review is the individual approval nobody gave before the action executed, so the
+reviewer reads the published bytes rather than a key and the agent's own summary
+of what it did. Between the computed and the claimed rows the card carries one
+of three payload regions, and its heading says which:
+
+| Heading | What the reviewer sees | When |
+| --- | --- | --- |
+| `PAYLOAD — the bytes that ran, shown whole; this review covers them` | the canonical rendering of the bytes, whole, in a `<pre>` block | the runtime holds bytes that hash to the execution's binding and they fit one card |
+| `PAYLOAD — NOT SHOWN, hash only; this review does not cover the bytes` | the binding's `sha256`, and why the bytes are absent | nobody holds the bytes, the bytes held do not hash to the binding, or they are longer than this card's payload budget (at most 2000 escaped characters, less when the card's rows leave less room) |
+| `PAYLOAD — none recorded; the execution bound to no payload hash` | nothing to show and nothing to name | the execution and its registration recorded no `payload_hash` |
+
+The bytes are shown whole or not at all: a card is one message edited in place,
+so it cannot spill a payload over several messages the way a request prompt
+does, and a review over half the bytes would claim more than the reviewer read.
+Only the first case lets the review record carry a `payload_hash` (see
+[the review record](#the-review-record)). A terminal review (`approval audit
+review`) shows no payload and so never records one.
+
+**The whole card fits one message (PR #614 refutation F4).** The agent's summary
+is cut at 400 characters and every other row at 300, each with a marker saying
+how many characters are not shown (the registration record keeps the text
+whole); a card whose rows are pathologically long cuts them further, in steps,
+until it fits. A notice shows at most 600 characters, the rest on the
+listener's stderr. The payload budget is what the card's own rows leave under
+Telegram's 4096-character limit after the longest heading and the largest
+notice a tap can add, capped at 2000, and it is computed from the card alone,
+so the card a reviewer saw and the view a tap records cannot disagree.
+
+**A card that fails to send (PR #614 recheck NF-2).** When Telegram refuses the
+card itself (HTTP 400 `message is too long`, `can't parse entities`,
+`message text is empty` or `text must be non-empty`, `reply markup is too long`,
+`BUTTON_DATA_INVALID`, `ENTITIES_TOO_LONG`), resending it can only fail again:
+the listener prints a coded `approval: telegram review-offer-failed:` line
+naming `approval audit review <seq> --ok` (or `--deny`), leaves that sample for
+a terminal review, and offers the next one. Every other failure (a 429, a
+timeout, a 5xx, a network error) prints `approval: telegram review-offer-retry:`
+and pauses review cards for Telegram's `retry_after` or the backoff, whichever
+is longer (one minute, doubling per attempt; never more than an hour, whatever
+`retry_after` says), then offers the same sample again.
+After five failed attempts the sample is left for a terminal review with the
+`review-offer-failed` line. Either way the sample stays open in
+`approval audit list` and QUEUE.md, the queue behind it no longer waits, and a
+restarted listener offers it afresh.
 
 Six buttons, bare emoji and no words (APRV-302), in two rows: the verdict on the
 first (✅ OK, 🛑 Deny) and the grade on the second, worst to best (👎 disliked,
@@ -4296,12 +4738,39 @@ first (✅ OK, 🛑 Deny) and the grade on the second, worst to best (👎 disli
 
 | Tap | What is recorded |
 | --- | --- |
-| ✅ | `audit.reviewed` with verdict `ok` and no reaction. |
-| a reaction | verdict `ok` and that grade — a reaction alone implies OK. |
-| 🛑 once | **Nothing.** It arms the card, which says `DENY ARMED` on itself. |
-| 🛑 twice | verdict `denied`, and the reconciliation obligation it opens is named on the reply. |
+| ✅ | `audit.reviewed` with verdict `ok`, and the held grade if there is one. |
+| a reaction, nothing armed | **Nothing.** Refused `verdict-required` (APRV-482): a grade is not a verdict. The card holds the grade and says `GRADE … HELD` in its heading. |
+| ✅ after a reaction | verdict `ok` with the held grade (a `loved` or `disliked` asks for words first). |
+| 🛑 once | **Nothing.** The tap reaches the runtime with no verdict, and the card arms (it says `DENY ARMED` on itself) only when the answer is `verdict-required`, which the runtime gives only to a mapped sender on the class's roster. Any other refusal is shown on the card and arms nothing. |
+| 🛑 twice | verdict `denied` with the held grade if any, and the reconciliation obligation it opens is named on the reply. |
 | a reaction with deny armed | verdict `denied` with that grade. |
 
+**A held grade and an armed Deny belong to the account that tapped them (PR #614
+refutation F3).** The card remembers the transport's sender id with each. A tap
+that would finish another account's half-finished review records nothing and is
+refused on the card with one line: any ✅ or 🛑 while another account holds the
+grade or armed Deny, and any reaction while another account armed Deny. A
+reaction tapped with nothing armed only replaces the held grade, and its tapper
+then holds it. A record therefore never carries a grade or a denial its reviewer
+did not tap. Only an account that may review can leave either behind (PR #614
+recheck NF-1): a grade is held, and a Deny arms, only after the runtime has
+passed the sender and the roster and answered `verdict-required`, so an
+unmapped or off-roster account in the approver chat cannot block the
+approvers' taps.
+
+**A verdict is an explicit act (APRV-482).** Under supervised-retro a review
+counts as the individual approval nobody gave before the action ran, so nothing
+records `ok` on a reviewer's behalf. The explicit forms per surface:
+
+| Surface | `ok` | `denied` | Refused `verdict-required` |
+| --- | --- | --- | --- |
+| Telegram card | ✅ (alone, or after a grade) | 🛑 twice, or 🛑 then a grade | a grade tapped with nothing armed |
+| `approval audit review` | `--ok` | `--deny` | neither flag, with or without `--reaction`; both flags is a usage error (exit 2) |
+
+The refusal on the card is the runtime's own: the tap reaches `reviewSample`
+with no verdict, and the code and its message come back exactly as a terminal
+sees them.
+
 The card does not print this table under itself. It used to, and the paragraph
 of rules pushed the rows a review is actually about off the first screen for a
 reader who had read them on the card before. The two things a tap could get
@@ -4334,7 +4803,10 @@ reviewer has to be able to say which half they meant.
 
 Every append goes through the same `reviewSample` that `approval audit review`
 calls, recorded against the human identity this listener was configured with
-(`--as` / `APPROVAL_HUMAN`), never anything the callback carried. So `approval
+(`--as` / `APPROVAL_HUMAN`), never anything the callback carried. That identity,
+or the person a sender mapping resolves a tap to, must be on the class's
+`approvers` roster where the rule names one, or the card shows
+`actor-not-approver` and keeps its buttons (APRV-483). So `approval
 feedback` shows a reaction given on a card exactly as one given at a terminal:
 same record, same `human:<id>`, same everything.
 
@@ -4459,7 +4931,10 @@ a gate.
 
 **Only the arrival changes, and that is the whole claim.** The pending queue is
 re-derived from the verified log every cycle by the same `dispatchPending`. The
-handlers are the same four function objects `listen` registers. A tap becomes a
+handlers are the same function objects `listen` registers (since APRV-456 that
+includes the recorder for a `nonce-not-issued` refusal, and `--no-stale-copy`
+or a relayed `--api-base` turns the earlier-copy fallback off here exactly as it
+does there). A tap becomes a
 decision through the same `handleUpdate`, the same `callback_query.from.id`
 reading, the same `approvers.<id>.senders` resolution, the same
 `recordChannelDecision` and the same annotate-after-decision edit. There is no
@@ -6163,6 +6638,13 @@ A 409 that still happens at runtime — another machine, or a poller started
 outside this runtime — is reported once, with the instances the registry knows
 about, and its repeats are counted rather than reprinted.
 
+**A relayed Telegram channel refuses buttons it is not holding** (APRV-456). An
+`--api-base` that is not `https://api.telegram.org`, or `--no-stale-copy`, turns
+off the earlier-copy fallback, and a decision tap whose nonce this process is
+not holding is refused `nonce-not-issued` instead of reaching the gate. The rule
+and its reason are under [`channel telegram listen`](#channel-telegram-listen)
+("Earlier copies, and `--no-stale-copy`").
+
 **The ambient runtime: the daemon loop and every configured channel in one
 supervised foreground process.** `approval daemon run --with-channels` is the
 same verb spelled from the other side, and it reaches the same function before

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "approval-md",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Human approval for agent actions. CLI runtime for the approval.md convention (pre-release).",
   "type": "module",
   "bin": {
@@ -59,5 +59,5 @@
     "better-sqlite3": "12.11.1",
     "yaml": "2.9.0"
   },
-  "gitHead": "fb0cf987985c2b9884ebe46b7b3b4419147d057e"
+  "gitHead": "5f9b9c3da2b0b220b344590d6d5319d27edf3b61"
 }