approval-md 0.3.0 → 0.4.1

package/docs/cli-reference.md

@@ -65,11 +65,20 @@ tampering.
 ```
 clean      {"status":"clean","records":3,"head":{"seq":3,"hash":"<64 hex>"}}
 torn-tail  {"status":"torn-tail","records":3,"head":null,
-            "intactThroughSeq":3,"message":"..."}
+            "intactThroughSeq":3,"tear":"nul-filled","tornBytes":456,
+            "intactBytes":2817,"message":"..."}
 corrupt    {"status":"corrupt","records":null,"head":null,
             "firstBadSeq":2,"reason":"hash-mismatch","message":"..."}
 ```
 
+On a torn tail, `tear` says which crash left it (APRV-440). `nul-filled` means
+every byte of the unterminated tail is NUL: the crash-before-writeback
+signature, where the file grew but its data never reached the disk, so nothing
+was tampered and no record was half-written. `partial-line` is a writer that
+died mid-line. `intactBytes` is where the verified records end, which is the
+length to truncate the file to; `tornBytes` is what that removes. Nothing is
+truncated by this verb.
+
 `head` is null for an empty log. `reason` is one of `malformed-line`,
 `schema-invalid`, `bad-alg`, `hash-mismatch`, `prev-mismatch`, `seq-gap`,
 `seq-duplicate`, `not-genesis`, `head-mismatch`. `anomalies` is ADDITIVE and
@@ -302,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
@@ -498,6 +565,11 @@ advance is the one that may carry `log.advance.daemon` instead, and only from
 inside the daemon process: see the `--advance` paragraph under `daemon run`
 (APRV-382).
 
+An advance publishes the WHOLE log, so while its branch is open on origin it is
+the log's publisher and `policy amend` stands aside: an amendment opened in that
+window carries only the policy bytes and cannot conflict with the records. See
+"Who publishes the log" under `policy amend` (APRV-420).
+
 `--co-author "Name <email>"` adds one validated `Co-authored-by` trailer to the
 generated records commit and to the pull request body. When the day's pull
 request already exists, the verb preserves its body and adds the trailer once.
@@ -669,9 +741,18 @@ channel; policy-authorized execution is never represented as a human grant.
                 "autonomy":"autonomous","winner":true,
                 "tieBreak":"specificity"|"strictest-autonomy"|
                            "lexicographic"|"tied-specificity"}],
+ "agentRequest":{"allowed":false,"explicit":true,"pattern":null},
  "decisionPath":["...","..."]}
 ```
 
+`agentRequest` (APRV-445) answers whether `approval propose` would admit this
+class: `explicit` is whether the class is an exact key of `classes`, `pattern`
+is the key whose `agent_may_request` decided (the exact key, or the most
+specific declared `<prefix>.*` family that states one), and `allowed` is both.
+It is read without the resolution above, because a wildcard match never makes a
+class proposable. A `decisionPath` line appears only when some key states the
+flag for this class.
+
 `specificity` is [literalSegments, wildcardSegments, totalSegments] (SPEC §5.2).
 `overridden.pattern` is null when the floor overrode `defaults.autonomy` rather
 than a rule.
@@ -741,6 +822,62 @@ existed still validate and verify; a reader treats the absent field as the
 pre-amendment state, where the in-force bytes are unrecoverable and the
 fail-closed fallback applies.
 
+**No terminal is needed.** The identity is declared, so the verb runs the same
+from a provisioning script with stdin at `/dev/null` as from a shell. The
+`attest-requires-terminal` refusal belongs to the channel path (a tap cannot
+attest a policy that maps no sender for that channel), never to this verb.
+
+### `--bootstrap`: a store's first policy, safe to re-run (APRV-449)
+
+The plain verb is an unconditional assertion: it reads no log and appends a
+`policy.updated` every time it runs. That is right for a human at a terminal and
+wrong for a provisioning step that runs again on every update and recreate of a
+hosted tenant, where a re-run would add an attestation per redeploy and, once
+the tenant has attested or amended their own policy, would put the operator back
+on record as its attester. `--bootstrap` reads the VERIFIED log first:
+
+```
+approval policy attest --bootstrap --as human:<operator> [--json]
+```
+
+| the log carries | answer | exit |
+|---|---|---|
+| no attestation | attests, exactly as the plain verb | 0 |
+| an attestation of these exact bytes | `policy-already-attested`, nothing appended | 1 |
+| an attestation of other bytes | `policy-amendment-required`, nothing appended | 1 |
+
+Both refusals add `seq` and `attested_by` (the attestation in force and who made
+it) to the error object:
+
+```
+refusal  {"ok":false,"error":{"code":"policy-already-attested","message":"...",
+          "seq":1,"attested_by":"human:carter"}}  on stderr
+```
+
+`policy-already-attested` is the expected answer on a re-run, so a provisioning
+step branches on `error.code` and treats that one code as done.
+`policy-amendment-required` means the bytes on disk moved after the store was
+attested. The operator does not attest that change: a change to an attested
+policy is an amendment, and an amendment is the approver's act through a channel
+(SPEC.md §10.3). The append is compare-and-append against the head the decision
+was read from, and binds the digest it checked, so an attestation landing in
+between, or a file rewritten in between, refuses (`head-moved`, or `io` naming
+the changed bytes) rather than stacking an operator attestation on top. A torn
+log is exit 3 and a log that does not verify is `log-corrupt` at exit 1.
+
+With `--bootstrap` the log is the store's: it resolves under `--dir`
+(`<dir>/.approval/log/events.jsonl`) unless `--log` names one, so `approval
+policy attest --bootstrap --dir "$STORE"` attests the store's own log from any
+working directory. The plain verb keeps its working-directory default. A
+refused append can leave one unbound copy of the policy text in the payload
+store, because the text is stored before the append (APRV-356). It is not
+removed: the record that moved the head may be another attestation of the same
+bytes, which binds that very file. An unbound file is inert, and `approval
+status` counts it under `payload_store.orphans`.
+
+`--bootstrap` beside `--organ` or `--path` is a usage error. The whole
+provisioning sequence is [docs/hosted-provisioning.md](hosted-provisioning.md).
+
 ### `--organ <path>`: the gate's organs (APRV-272)
 
 The ORGANS are the harness files that install the hook: `.claude/settings*`,
@@ -1035,6 +1172,69 @@ base carries it, and a pins edit somebody else landed is not reverted by this
 ceremony. The pin deltas print in the semantic diff beside the class deltas, ride
 in the commit subject, and appear in `--json` as `pins`.
 
+**Who publishes the log (APRV-420).** The log is in that file set only when this
+amendment is the thing publishing it. On 2026-09-21 it always was, and PR 530
+paid for it: two records advances merged first carrying the same records (the
+attestation at seq 65736 and its payload reached main through PR 531), and git
+does not care that one side's appended lines are a prefix of the other's, so the
+amendment went DIRTY, lost its arm, and the repair was a hand merge of
+`events.jsonl` in a throwaway worktree.
+
+The cause was two publishers carrying the same bytes, so the ceremony now leaves
+one of them holding it. It asks two questions of the base it is about to commit
+on, in this order:
+
+1. does the base's log already carry every record this attestation added? Then
+   the log is published and the amendment has nothing to add to it.
+2. is a records advance live, meaning origin carries a `records-log-*` branch?
+   That advance publishes the log, so the amendment has nothing to add to it
+   either. Whether the branch already carries THIS attestation is checked
+   rather than assumed: the ceremony fetches the branch and compares chains.
+   An advance pushed before the human signed does not carry it, which is the
+   ordinary order; the ceremony then says so, the next advance publishes the
+   record, and the pull request's protected-path guard holds the policy
+   change until a records branch or main carries it.
+
+Either way the commit is the policy bytes, the attested text and the pins, and a
+commit that does not touch `events.jsonl` cannot conflict on `events.jsonl`,
+whichever side lands first. Otherwise the amendment is the only publisher and
+carries the log, exactly as it always has. The ceremony prints which of the three
+happened, so the pull request's file list is never a surprise.
+
+The question is asked with `git ls-remote`, not `gh`, so it answers the same on a
+box with no GitHub CLI and no token. And it fails toward CARRYING: anything the
+check cannot establish leaves the amendment holding the log. A dirty pull request
+is a nuisance; an attestation that reaches `main` in nobody's commit is a policy
+in force that the committed log does not record.
+
+**A re-run repairs the pull request it finds (APRV-420).** A second run used to
+stop at `nothing to amend`, which is true and useless: the live policy does match
+its attestation, and the pull request carrying that attestation is open,
+unmergeable and unarmed. So when `--commit` or `--pr` is asked for and origin
+already carries the amendment branch, the re-run fetches the default branch and
+computes what it still LACKS — the policy bytes, the attested text, the pins, and
+the log under the rule above — and then:
+
+- nothing lacking: the amendment landed in full. It says so and prints `gh pr
+  close <branch> --delete-branch`.
+- something lacking: it rebuilds that commit on the CURRENT default branch and
+  force-updates the branch, then re-arms `gh pr merge <branch> --merge --auto`.
+  The trunk's log is a superset of the amendment's by construction, so rebuilding
+  on it is the re-merge without a merge.
+
+The rebuild is `commitOnBase`'s scratch index like every other commit this verb
+makes, so nothing is checked out and no live appender has the log moved
+underneath it. The force-push is the one in this codebase, and it is bounded: the
+remote branch must be a single commit on top of a commit the base already
+contains, which is the shape this ceremony creates and nothing else. A branch
+carrying anything more is reported with `git log --oneline <base>..<tip>` and
+left alone. `--dry-run` and `--no-publish` compute the repair, print the
+commands and run none of it. `--json` carries a `repair` object (`branch`,
+`state` of `landed`/`repaired`/`owed`/`failed`, `base`, `carried`, `commit`,
+`pushed`, `autoMerge`, `commands`, `message`), additively and always present:
+`null` on every run that had an amendment to make and on every no-op that found
+no branch standing. Only `failed` is a nonzero exit.
+
 It refuses outside a git repository (`commit-preconditions`), and refuses
 `staged-unrelated` when the index holds staged changes to anything beyond those
 three: a commit that swept in an unrelated staged edit would make "this commit is
@@ -1524,6 +1724,24 @@ hash must equal the declared `payload_hash` and it is filed in
 bytes from. Supply it here once and no channel needs `--payload-dir` or
 `--payloads` at all.
 
+For an action `approval run` will execute, produce those bytes with `approval
+payload run -- <cmd…>` rather than by hand. Since APRV-401 the payload carries
+the size and digest of the script the argv names, and a hand-written
+`{"argv":…,"cwd":…}` for a command that names a script is a declaration the
+execution will refuse `payload-mismatch`, correctly, because it describes bytes
+nobody bound:
+
+```
+approval payload run --hash -- bash scripts/install.sh   # the declaration
+approval payload run       -- bash scripts/install.sh \
+  | approval request <task> --action <key> --as agent:<id> --payload -
+```
+
+Material supplied here is checked against the declared hash and never against
+the filesystem: this verb does not know where the run will happen, and the
+guarantee is that `approval run` recomputes the same value from the tree it is
+about to spawn into and refuses on any difference.
+
 When the policy permits an unattended action, supplied material is still checked
 against the registered action's task, class and payload hash and retained before
 `proceed:true` is returned. This creates no approval event and does not require
@@ -1545,6 +1763,129 @@ refusal     {"ok":false,"error":{"code":"...","message":"...",
 The refusal goes to stderr, and `seq` is the `budget.exceeded` record that WAS
 appended.
 
+## propose
+
+`approval propose --class <c> --key <k> --summary <s> --payload-json <json>`
+registers one action and requests it in one call (APRV-445, amended SPEC.md
+§10.1). It exists for a requester that holds its payload in memory and has no
+file on the gate's machine: an agent in a sandbox reaching `approval serve`
+with the agent credential, which refuses every path flag. `--payload-json` is
+the payload as the flag's VALUE, a JSON object of at most 262144 bytes of UTF-8
+as sent; an array, string, number or `null` is a usage error, and a larger
+payload is refused `payload-too-large` at exit 2 before it is parsed.
+
+**Why this verb may name its class.** `request` never does, so that an agent
+cannot call a `financial.spend` a `read.web`. Here the agent is also the
+registrant, so the bound is the operator's: the class must be an EXACT key of
+the policy's `classes` (a wildcard rule that happens to match does not count),
+and that key or a declared `<prefix>.*` family of it must set
+`agent_may_request: true` (SPEC.md §5.2). Anything else refuses
+`class-not-agent-requestable` and registers nothing. A `human-only` member
+under an open family refuses `class-human-only`, also before anything is
+registered. The check runs again inside the request's own read-check-append
+cycle, so a re-attestation in between cannot slip a closed class through. What
+the agent picks AMONG the opened classes is still its own statement: an
+operator who opens a manual class and an autonomous one under the same family
+is trusting the agent to pick the right one, and the record names the class it
+picked.
+
+```yaml approval-policy
+classes:
+  intent.publish.*: { autonomy: manual, agent_may_request: true }
+  intent.publish.inferred.index: { autonomy: manual }
+  intent.publish.stated.index: { autonomy: autonomous }
+```
+
+**The key** must begin with `<class>:` and an id of printable characters with
+no whitespace or control characters (refused
+`key-class-mismatch`, exit 2): `intent.publish.inferred.index:<intention id>`.
+It is recorded verbatim as `action_key`, and a consumer reads the class from the
+record rather than parsing it back out of the key. The key is at most 1024 bytes
+and `--summary` at most 4096; a lone UTF-16 surrogate in either or anywhere in
+the payload, and a number JSON parses to Infinity (`1e400`), are usage errors. An
+integer beyond 2^53 is hashed as the double it parses to, so send large ids as
+strings.
+
+**Do not open a `supervised-live` class to agents.** The live draw would decide,
+per proposal, whether a human is asked at all, which the requester can neither
+predict nor explain to the person whose words it is proposing.
+
+**The task id** is `propose:` and the first 32 hex digits of the SHA-256 over
+the RFC 8785 canonical JSON of `[actor, class, key]`. The actor is the tenant
+half: one `approval serve` process is one store and one fixed `agent:<id>`. Two
+actors proposing one key derive two tasks, and the second registration is
+refused `task-already-registered` because the key is already declared under the
+first.
+
+**Records.** One `task.registered` (actor = the caller, envelope `origin.app:
+approval-propose`, one action: the class, the summary, `idempotency_key` = the
+key, `payload_hash`) and one `approval.requested` exactly as `request` writes it,
+with `action_key` = the key verbatim, `summary`, `payload_hash`, `display_hash`,
+`policy_sha256` and `execution: "harness"` (a grant mints no token; the
+requester proceeds on the grant and records it with `start`). The summary is in
+the log in cleartext, twice; the payload is never in the log, only in the
+payload store (`.approval/payloads/<hash>.json`, mode 0600 in a 0700 directory),
+which the tenant credential's `GET /export` includes and the agent credential
+can never read back. Set `payload_retention` so the daemon prunes bytes whose
+action has finished.
+
+**Idempotency.** The same class, key and bytes append nothing and answer the
+request's standing with `idempotent: true` while it still means something:
+pending, granted and spendable, rejected, revoked, or executed (`state:
+"executed"`, after `start`). The same call ASKS AGAIN, under the same
+registration, when the request can no longer be answered usefully: withdrawn,
+expired, a grant whose request window lapsed (a grant has no window of its own,
+so a tap at hour 71 of 72 authorizes nothing at hour 73), or a grant or pending
+request pinned to a policy that has since been re-attested (a pending one is
+first withdrawn, reason `superseded`). Two identical calls racing to register
+are one proposal. The same key with different bytes refuses
+`duplicate-request` while a request is live and `payload-mismatch` otherwise: a
+key is bound to the bytes it was first proposed with. A plain `approval request`
+on a `propose:` task is refused `task-is-proposal`.
+
+**Off the manual path.** A class that resolves `autonomous` or `supervised` is
+registered and answered at once with `decision: "autonomous"` (or
+`"supervised"`) and no approval record. Act, then record it with `start`.
+
+**`--json`** (one object on stdout):
+
+```
+manual      {"ok":true,"task":"propose:<32 hex>","action_key":"<k>","class":"<c>",
+             "payload_hash":"<64 hex>","decision":"requested","state":"requested",
+             "seq":7,"idempotent":false}
+retry       {...,"state":"granted","seq":9,"idempotent":true}
+autonomous  {...,"decision":"autonomous","state":null,"seq":null,"idempotent":false}
+```
+
+Poll a `requested` proposal with `approval wait <task> --timeout 0`.
+
+## start
+
+`approval start <task> --action <key> --payload-json <json>` appends the one
+`execution.started` for an action its requester is about to carry out itself,
+outside any harness hook (APRV-445). Proposals only: any other task is refused
+`task-not-proposal`. REQUESTER-ONLY: the caller must be the actor
+that registered the task (`not-requester`). The bytes presented must hash to the
+registered `payload_hash` (`payload-mismatch`), so what is done is what was
+proposed.
+
+It writes through the two existing harness spenders and nothing else. A key
+whose request is pending or granted and unspent spends its harness grant: refused `not-granted` while
+pending or after a rejection, `expired` after the window, `policy-drift` under
+a re-attested policy. A key with no such request (none, or one withdrawn,
+expired, rejected or revoked, which binds nothing) is recorded as authorized by
+the policy itself: refused `not-granted` for a manual class and `class-human-only`
+for a human-only one, and charged against the budgets. A second start of one key
+is `already-executed`. The record carries `execution: "harness"`, which is why no
+`execution.completed` ever follows it.
+
+**`--json`**:
+
+```
+{"ok":true,"task":"propose:<32 hex>","action_key":"<k>","class":"<c>",
+ "authorization":"grant"|"policy","seq":12}
+```
+
 ## grant
 
 Legal only on a request that is awaiting a decision. A second decision is
@@ -1719,8 +2060,8 @@ refusal  {"ok":false,"error":{"code":"...","message":"...","state"?:"..."}}
 
 ## gate refusal codes
 
-The vocabulary every gate verb (register, request, grant, reject, revoke,
-withdraw, expire) returns in `error.code` with `--json`. Frozen public API: an agent branches on it
+The vocabulary every gate verb (register, request, propose, start, grant,
+reject, revoke, withdraw, expire) returns in `error.code` with `--json`. Frozen public API: an agent branches on it
 to decide whether to fix itself, stop retrying, or ask a human.
 
 - `policy-not-attested` — policy unattested or its bytes changed since
@@ -1784,7 +2125,8 @@ to decide whether to fix itself, stop retrying, or ask a human.
   it, or is withdrawing one it already withdrew. Distinct from `already-decided`:
   nobody answered, and nobody can now. Request the action again.
 - `not-requester` — a withdrawal was attempted by an actor other than the one
-  that opened the request. Only the party that asked may take the question back;
+  that opened the request, or a `start` by an actor other than the one that
+  registered the task. Only the party that asked may take the question back;
   anyone else who wants it gone rejects it.
 - `expired` — the TTL lapsed, judged from the request's own `ts`.
 - `not-expired` — expire was called before the TTL lapsed, or the policy declares
@@ -1822,6 +2164,20 @@ to decide whether to fix itself, stop retrying, or ask a human.
   at the verb (exit 2) rather than a member of this union.
 - `log-unreadable` (exit 4) / `log-torn-tail` (exit 3) / `log-corrupt` (exit 1):
   nothing is authorized from a log that does not verify.
+- `class-not-agent-requestable` — `propose` named a class the policy has not
+  opened to agents: not an exact key of `classes`, or neither that key nor a
+  declared `<prefix>.*` family sets `agent_may_request: true`. Nothing is
+  registered or appended; the repair is a policy edit and a human attestation.
+- `payload-too-large` (exit 2) — a `propose` or `start` payload over 262144
+  bytes of UTF-8. Refused before it is parsed; nothing is stored.
+- `task-is-proposal` — a plain `request` on a task `propose` registered, or a
+  task file claiming an id in the `propose:` namespace. Nothing is appended.
+- `task-not-proposal` — `start` on a task `propose` did not register.
+- `key-class-mismatch` (exit 2) — a `propose` key that does not begin with
+  `<class>:` and an identifier.
+- `contended` — `propose` restarted its bounded number of times on a log that
+  kept moving under it and stopped; nothing more was appended. Read the
+  standing with `wait --timeout 0`, or call again.
 - `append-failed` — the append itself failed; the exit code follows the cause.
   `head-moved` means the log grew between this command's read and its write, so
   nothing was written. Since APRV-236 you see it only after the command has
@@ -1953,9 +2309,23 @@ measurement.
 Content binding (amended SPEC.md §6.2, §10.4): run computes the hash of the argv
 and cwd it is about to spawn, always, and presents that. The command IS the
 action here, and an executor that had to be told what it was running could be
-told wrong. `--payload-hash` is consequently a CHECK and never a substitute
+told wrong.
+
+Since APRV-401 that computation includes THE SCRIPT THE ARGV NAMES. A known
+interpreter followed by a path operand, or a path at `argv[0]`, carries that
+file's size and SHA-256 inside the hashed payload, so a grant over `bash
+install.sh` binds the script's bytes rather than its path: a script edited
+between the declaration and the run hashes differently and is refused
+`payload-mismatch`, with nothing appended and the grant still live for the
+approved bytes. An argv naming no script hashes exactly as it always did.
+`approval payload run` prints the same value, which is how a requester obtains
+the declaration in the first place; `docs/run-payload-binding.md` states the
+rule and the six things it does not reach.
+
+`--payload-hash` is consequently a CHECK and never a substitute
 (APRV-140): a value differing from the recomputed one is refused
-`payload-mismatch` before the child exists and before anything is appended. An
+`payload-mismatch` before the child exists and before anything is appended, and
+the refusal names the script it bound so the repair is visible. An
 action whose payload is content rather than an argv (an email body, a record
 write, a message and its recipients) is executed through the adapter contract of
 §10.4, `approval adapter email`, which hashes those bytes itself; a token for
@@ -2154,6 +2524,33 @@ costs, and the carve-outs.
 
 ## wait
 
+`--timeout 0` (also `0s`, `0ms`) reads the current state once and never sleeps
+(APRV-445): an undecided request answers `timeout`, exit 6, at once, and a
+decided one answers as it always would. Use it to poll through `approval serve`,
+which runs every verb call whole under the store lock that hook calls take for
+their appends (APRV-427), so a wait that sleeps there holds the tenant's hook
+traffic for as long as it sleeps (APRV-441). The
+duration grammar has no zero anywhere else. `--withdraw-on-timeout` is refused
+beside it (exit 2): a status read that withdrew would retract every question it
+looked at.
+
+**What a waiter is told is what the request still authorizes** (APRV-445). A
+grant whose request window has lapsed reads `expired` (exit 3), not `granted`. A
+pending request pinned to a policy hash that is no longer the attested one (any
+task), a HARNESS grant so pinned (`execution: "harness"`, every proposal
+included: its spend refuses `policy-drift`), or a request the runtime withdrew
+for `policy-drift`, reads `void`, **exit 7**: the answer can never be used, and
+the repair is to ask again (for a proposal, the same `propose` call re-files). A
+token grant is NOT void after a re-attest: `approval run` spends it without
+comparing policy hashes, so `wait && run` keeps working and `wait` reads
+`granted`. Precedence: rejected > withdrawn >
+void > expired > granted > executed > nothing-to-wait-for. An action that ran
+on the policy's own authority after its request ended (a `start` after a
+withdrawal and a re-tiering) reads `executed`, status `executed`, exit 0. A
+registered task with no requests answers `nothing-to-wait-for` at exit 0, and an
+unknown task id is refused `not-registered` at exit 1 (APRV-428), so poll the
+task id `propose` returned.
+
 Polls the log and writes nothing — not even the `approval.expired` event it may
 derive: expiry is judged lazily from the request's own timestamp, and
 materialising it is `approval expire`'s job, not a reader's. The one exception is
@@ -2162,9 +2559,27 @@ materialising it is `approval expire`'s job, not a reader's. The one exception i
 For `approval wait` the exit code IS the decision (SPEC.md §10.1). The
 overloading of 1 (integrity / rejected) and 3 (torn tail / expired) is
 deliberate: wait appends nothing and cannot fail a chain verification of its
-own, and `--json` names the outcome exactly (`granted | rejected | withdrawn |
-expired | timeout`) for callers that need more than a number. Flagged for human
-review.
+own, and `--json` names the outcome exactly (`granted | executed | rejected |
+withdrawn | void | expired | nothing-to-wait-for | timeout`) for callers that need more than a
+number. Flagged for human review.
+
+**Nothing to wait for, and nothing registered** (APRV-428). Exit 0 has always
+answered at once for a task with no requests, because only the manual path
+produces requests and the supervised path tells an agent its `proceed: true`
+needs no wait. Its `status` is `nothing-to-wait-for`, never `granted`: a
+registered task with no `approval.requested` at all (no action declared, none
+reached the manual path, or none requested yet), or one whose every granted
+action has already started executing, so every grant is spent. `granted` means
+at least one granted action has not executed yet, and only that. The per-action
+rows are unchanged; an executed grant still reads `granted` there.
+
+A task with no `task.registered` record is refused before anything is derived:
+`not-registered`, the gate union's code for exactly that condition (SPEC.md
+§11.2), at exit 1, the code `approval request` exits for the same refusal.
+Before APRV-428 such a wait answered `{"ok":true,"status":"granted","actions":[]}`,
+so a typo read as a grant. Through `approval serve` the verb's refusal passes
+through unchanged: the body's `stderr` carries the same object and `exit_code`
+is 1.
 
 `withdrawn` (APRV-106) reuses exit **1** rather than claiming a new number. The
 exit table in `src/cli/exit-codes.ts` is frozen public API and agents already
@@ -2192,10 +2607,11 @@ itself fails is reported on stderr and leaves the request live; the exit code is
 
 ```
 decided  {"ok":true,"task":"task-042",
-          "status":"granted"|"rejected"|"withdrawn"|"expired",
+          "status":"granted"|"rejected"|"withdrawn"|"expired"|"nothing-to-wait-for",
           "actions":[{"action_key":"...","state":"granted","seq":4}]}
 timeout  {"ok":false,"task":"task-042","status":"timeout",
           "actions":[{"action_key":"...","state":"requested","seq":3}]}
+refused  {"ok":false,"error":{"code":"not-registered","message":"..."}}   (stderr, exit 1)
 ```
 
 **Sealed token delivery** (APRV-105). Under policy `defaults.token_delivery:
@@ -2227,8 +2643,8 @@ so the paste path is preserved rather than replaced.
 passed, listing the keys actually retracted; the default shape is unchanged.
 
 `state` is the per-action derived state; `status` is the whole task's outcome,
-with rejected/revoked outranking withdrawn, withdrawn outranking expired, and
-expired outranking granted. `--timeout` and `--interval` take the SPEC.md §5.2
+with rejected/revoked outranking withdrawn, withdrawn outranking expired,
+expired outranking granted, and granted outranking nothing-to-wait-for. `--timeout` and `--interval` take the SPEC.md §5.2
 duration grammar, `<positive integer><ms|s|m|h|d|w>`.
 
 ## queue
@@ -2252,11 +2668,16 @@ requested, and how much of the TTL is left.
 {"ok":true,"pending":[{"action_key":"task-042:chaser","task":"task-042",
  "class":"communicate.email.external","est_cost_usd":"0.02",
  "requested_ts":"2026-08-06T10:00:00.000Z","seq":3,
- "ttl_remaining_ms":3599000}]}
+ "ttl_remaining_ms":3599000,"ttl_ms":3600000}]}
 ```
 
-`pending` is `[]` for an empty inbox. `ttl_remaining_ms` is null when the policy
-declares no `defaults.approval_ttl` (no TTL means no lapse).
+`pending` is `[]` for an empty inbox. Both TTL fields are measured against the
+window the gate judges the request by (APRV-423): the policy's
+`defaults.approval_ttl`, narrowed by the harness ceiling the requesting hook
+declared, if any. `ttl_ms` is that whole window and `ttl_remaining_ms` is what is
+left of it; both are null only when nothing bounds the request (no TTL and no
+cap means no lapse). A hook-opened request under a policy with no TTL therefore
+shows its real remaining window here rather than `null`.
 
 ## gate
 
@@ -2397,9 +2818,47 @@ informational: it moves neither the health verdict nor the exit code. An empty
 store is the normal state of a repo that has never made a request carrying
 `--payload`. (`approval doctor` is where an unwritable store is a failure.)
 
+**attestation** names the policy in force: its state, the seq of the attestation
+the log last recorded, and `attested_by`, the actor of that record (APRV-449).
+The identity is read from the verified record and never from the file, so a
+hosted tenant can see whether their starting policy is the operator's
+bootstrap or their own later act (docs/hosted-provisioning.md). It is the
+identity the attesting process declared, which the runtime does not
+authenticate. `attested_by` is `null` when nothing was attested; on
+`hash-mismatch` it names who attested the bytes the live file no longer
+matches. The text row reads `attested (seq 1, by human:carter)`, and `approval
+doctor`'s attestation row carries the same name.
+
 **anomalies** are informational for the same reason `approval log verify`
 declined to refuse on them: status does not get to overrule that.
 
+**refusals** is the two refusal families, counted, with the newest five of each
+(APRV-376). `decision` counts `audit.decision_refused`: a human decided and the
+gate would not take it, which is APRV-235's record. `gesture` counts
+`audit.gesture_refused`: a human made a gesture that is not a decision (a
+checkpoint signature, a review, a review note) and the surface refused it before
+any verb ran, which is APRV-355's. Until this field existed neither was reported
+anywhere, and an operator could reach them only through `approval log tail` and
+`approval log export`. The question the field answers is small enough that the
+chain was a poor place to answer it: told that taps from an account they did not
+map are being refused, an operator wants to know how many and from which account.
+
+Each entry carries the `seq`, the surface's own refusal code verbatim, and the
+observed `sender` when the record carries one, in the form the record carries it
+(`hashed: true` marks APRV-370's keyed digest rather than a raw account id). The
+count is every record of that family in the log; the listing is the newest five,
+newest first, because a row that grew with the log would push the rest of the
+report off a terminal for a fact that decides nothing.
+
+It is informational, exactly as `coverage` and `anomalies` are: it moves neither
+`healthy` nor the exit code. A refusal is the gate having worked, and a report
+that went red because the gate turned away a stranger's tap would teach an
+operator to stop reading it. It reads only verified records (SPEC.md §11.1
+invariant 1), which is also why a log that does not verify reports no refusals
+rather than reporting some it cannot stand behind. A family with no records is
+absent rather than zero, and the whole field is absent when both families are, so
+a repository where nothing has been refused emits the object it always emitted.
+
 **coverage** is one line of `approval coverage` (APRV-245): the commits git
 recorded on THIS branch, counted against the verified log. The range is the
 merge base with `origin/main` to `HEAD`, so what it measures is what this branch
@@ -2420,7 +2879,7 @@ does not know the flag exists.
 **What it reports**, in one object:
 
 - `attestation` — attested | hash-mismatch | not-attested | unreadable, with the
-  seq of the governing `policy.updated` record.
+  seq of the governing `policy.updated` record and `attested_by`, its actor.
 - `verification` — the latest chain verdict, and the record count (null when
   corrupt).
 - `dangling` — executions the runtime meant to watch and never closed. Not
@@ -2443,12 +2902,25 @@ does not know the flag exists.
   how many the log records as pruned, and how many are unbound. Informational.
 - `anomalies` — additive and present only when non-empty: gate-typed events whose
   `ts` steps backwards by more than 2s. Informational.
+- `refusals` — additive and present only when the log carries a refused decision
+  or a refused gesture: `{count, recent}` per family, each recent entry naming the
+  `seq`, the refusal `code` and the observed `sender` where there was one.
+  Informational.
+- `daemon` — `{id, source, allowed}`, always present (APRV-383): the daemon
+  instance id a daemon run against THIS log would write onto every record it
+  appends, whether it came from `APPROVAL_DAEMON_ID` (`source: "environment"`) or
+  was derived from the instance (`source: "derived"`), and the `daemons` allowlist
+  the attested policy puts in force. `id: null` means `APPROVAL_DAEMON_ID` holds
+  something that is not a usable id, so a daemon started here would be refused
+  every append. `allowed: null` means no restriction, which is not the same fact as
+  an empty list. Informational: nothing here moves `healthy` or the exit code, and
+  being listed grants a daemon nothing beyond the ability to write.
 
 **`--json`** (one object on stdout):
 
 ```
 {"ok":true,"healthy":false,
- "attestation":{"state":"attested","seq":1},
+ "attestation":{"state":"attested","seq":1,"attested_by":"human:carter"},
  "verification":{"status":"clean","records":6},
  "dangling":[{"action_key":"...","task":"...","ts":"...","seq":5}],
  "budgets":[{"limit":"global.daily_usd","scope":"global",
@@ -2460,12 +2932,16 @@ does not know the flag exists.
  "reconciliation":[{"seq":18,"ts":"...","action_key":"...","task":"...",
    "class":"records.write","obligation":"gated-revert","review_seq":17}],
  "payload_store":{"present":true,"files":2,"pruned":0,"orphans":0,
-   "note":"..."}}
+   "note":"..."},
+ "refusals":{"decision":{"count":2,"recent":[{"seq":21,"code":"policy-drift"}]},
+   "gesture":{"count":1,"recent":[{"seq":24,"code":"sender-unmapped",
+     "sender":{"channel":"telegram","id":"5551234567"}}]}},
+ "daemon":{"id":"daemon-3f2a9c11","source":"derived","allowed":null}}
 ```
 
-`ok` is true whenever status ran; `healthy` is the verdict. `attestation.seq` is
-null for not-attested and unreadable. `note` carries the unrebuildable warning
-verbatim.
+`ok` is true whenever status ran; `healthy` is the verdict. `attestation.seq` and
+`attestation.attested_by` are null for not-attested and unreadable. `note`
+carries the unrebuildable warning verbatim.
 
 ## coverage
 
@@ -2657,7 +3133,8 @@ The checks, at length:
   `--as`: this reports what the next command will find.
 - **attestation** — anything other than "the live bytes match" makes every gated
   operation refuse, and that refusal reads like "the policy says no" when it
-  means "the policy is unverified".
+  means "the policy is unverified". A pass names the seq and the attester read
+  from that record (`attested at seq 1 by human:carter`, APRV-449).
 - **log** — a torn tail and a corrupt log are both failures here; neither is
   repaired, and doctor never truncates a torn line.
 - **telegram** — `getMe` against `--api-base`, when both variables are set;
@@ -2674,7 +3151,17 @@ The checks, at length:
   `--payload` request creates it); an existing directory this process cannot
   write FAILS, because a request already accepted by the gate would refuse
   `payload-store-failed` mid ceremony. The probe creates and removes one empty
-  file and reads no payload.
+  file. Since APRV-457 the row also reads back every payload a verified record
+  binds (pruned ones excepted) and FAILS on two distinct readings. An empty or
+  all-NUL file, or a missing file whose record proves the store held it
+  (`policy.proposed`, `policy.updated`, or `approval.requested` carrying
+  `display_hash`), is the crash-before-writeback signature: nothing was
+  tampered and the bytes are gone from this store; the fix moves a torn file
+  aside and restores a copy that `approval payload hash` confirms. A file
+  holding any non-NUL byte that does not verify is NOT the crash signature
+  (a partial writeback leaving a valid prefix and a NUL tail lands here too, the stricter reading) and reads as tampering or
+  corruption; the fix moves it aside as `.suspect`. Doctor moves, restores and
+  deletes nothing.
 - **audit-sampling** — sampling fails open by design (SPEC.md §5.2), so an
   unconfigured sampler silently audits nothing; this states the disabled reason
   out loud. A sampler nobody configured skips; a half-configured one fails,
@@ -2749,17 +3236,25 @@ The checks, at length:
   of the gate, so the repair is a line for a human to commit, printed by
   `approval instructions hook`.
 - **harness-hook-wiring** — whether THIS checkout's `.claude/settings.json`
-  registers `approval hook` for PreToolUse over every gated tool (Bash, Edit,
-  Write, NotebookEdit). SKIP, named, when the file is absent, unreadable, or
+  registers `approval hook claude-code` for PreToolUse over every gated tool.
+  The roster is read from the adapter that answers the calls (Bash, Edit, Write,
+  MultiEdit, NotebookEdit since APRV-408, where it was a hand list that had
+  drifted behind them). SKIP, named, when the file is absent, unreadable, or
   registers the hook for only some tools: a spawned-agent worktree without the
   entry is how the APRV-151 bypasses happened, and a session started elsewhere
   may still be hooked, so this row can only speak for the checkout it runs in.
   PASS means the entry is present on disk, and says so plainly: it is not proof
-  the running session loaded it. The check that trusts no session is the
-  CI-side grant cross-check (`scripts/protected-path-guard.mjs`) over the
-  committed log, which since APRV-202 requires every added and removed line of a
-  protected path to trace to the bound material of a grant, rather than only
-  that the path was granted at some point in the week.
+  the running session loaded it. The one FAIL is a handler whose `--dir` names a
+  checkout other than this one, which answers from another policy, another log
+  and another open window. Two informational lines never decide anything: the
+  adapter read tools the matcher leaves out (Read, Glob, Grep) are named as the
+  documented default they are, and a matcher tool the adapter handles as none of
+  its own is named as the unclassified `allow` it will actually receive. The
+  check that trusts no session is the CI-side grant cross-check
+  (`scripts/protected-path-guard.mjs`) over the committed log, which since
+  APRV-202 requires every added and removed line of a protected path to trace to
+  the bound material of a grant, rather than only that the path was granted at
+  some point in the week.
 - **keychain-scope** — whose keystore items this instance's `.approval/env`
   names, answered from the NAMES alone so that it too can never block on an
   unlock dialog. FAIL for an item whose eight-hex scope suffix belongs to
@@ -2863,7 +3358,14 @@ The checks, at length:
   the `fix` is the promptless self-test in `docs/claude-code-hook.md`, one
   supervised-class tool call, after which the row is green. PASS says only that
   the versions match — the field is self-reported (SPEC.md §11.1 invariant 4)
-  and reduces nothing anywhere, so a match is not proof the hook fired.
+  and reduces nothing anywhere, so a match is not proof the hook fired. Since
+  APRV-415 the row carries a second finding for one harness: a Hermes below the
+  **fail-closed version floor** (a build at or after `main` `118984d7` of
+  2026-09-20) FAILS, because `v0.21.3` ignores `fail_closed` silently and every
+  broken hook on it proceeds. That half is read from `hermes --version` rather than
+  from a record — Hermes prints its build stamp behind a non-ASCII separator the
+  write boundary refuses, so no record can carry it — and it compares the build
+  date and the upstream commit, because the two builds report the same semver.
 - **live-draw** — whether a daemon is answering `supervised-live` draws for this
   log (APRV-208). SKIP when the policy declares no live class: no draw is ever
   made, and a missing socket is nothing. It FAILS in three shapes, all of them
@@ -2997,6 +3499,22 @@ The checks, at length:
   would find nothing and report green, which is the worst direction a health
   check can fail in. The `fix` points at the harness's own configuration,
   because nothing here can turn another system's reviewer off.
+- **daemon-identity** — which daemon id a daemon run against this log would
+  write onto every record it appends, and whether the attested policy admits it
+  (APRV-383). The id is `APPROVAL_DAEMON_ID` from this shell where it is set and
+  otherwise `daemon-` plus the instance id the `keychain-scope` row names, so the
+  two rows describe one gate. A FAIL where `APPROVAL_DAEMON_ID` is set to
+  something that is not an id: a daemon started from this shell would be refused
+  `daemon-id-invalid` on every append, so it would read, render and report while
+  writing nothing, and the `fix` is that one variable. A loud SKIP where the
+  attested policy's `daemons` list does not admit the id, naming what the list
+  does admit — expected where the daemon for this log runs on another machine,
+  which is the hosted case the key exists for, and wrong if that daemon is meant
+  to be this one. A PASS where the list admits it, and where there is no list at
+  all, which is every installation that never adopts the key. Being listed grants
+  nothing beyond the ability to write: no verdict, budget, floor, draw or token
+  reads the id. The row reads the policy and one variable's SHAPE, prints no
+  value on any path, and asks no running daemon anything.
 
 
 
@@ -3078,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):
 
@@ -3460,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
@@ -3669,6 +4498,16 @@ This starts the standalone Telegram component. For normal operation, use
 `up` or another listener polling the same bot, even for a different policy
 project: competing `getUpdates` calls produce Telegram HTTP 409.
 
+A bot whose updates go to a webhook cannot be long-polled at all, so this verb
+and `approval up` refuse `webhook-registered` in the same preflight that asks
+`getMe`, naming the origin that holds it. That preflight also takes this gate's
+transport lease (`.approval/daemon/telegram-transport.lock`), so a second
+listener or a webhook runner started in the same project refuses
+`telegram-poller-running` naming the pid that holds it, rather than both
+processes putting every request on the phone under their own nonce. See
+[`channel telegram webhook`](#channel-telegram-webhook), which is the other
+transport and removes both its registration and its lease when it exits.
+
 **Delivery is per cycle, not only at startup.** Before every `getUpdates` the
 listener re-derives the pending queue from the verified log and sends whatever
 it has not already sent, so a request appended while this listener is running
@@ -3766,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
@@ -3809,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,
@@ -3826,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
@@ -3864,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.
 
@@ -3978,6 +4920,256 @@ rather than a query:
 
 The raw execution token is never in the JSON stream.
 
+## channel telegram webhook
+
+The same channel, the other arrival (APRV-424). `listen` holds a socket open
+against `getUpdates` for as long as the gate exists, which needs one
+always-running process per bot and forbids a second poller on the same token.
+This registers a URL with `setWebhook` and serves the callback, so Telegram
+posts each update as it happens and a host that sleeps between requests can run
+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 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
+second decision path and no second copy of the sender mapping:
+`tests/telegram-webhook.test.ts` drives one callback through both transports and
+compares the records the log ends up holding, field for field.
+
+### The secret, which is the whole of the authentication
+
+`APPROVAL_TG_WEBHOOK_SECRET` is REQUIRED and is read from the launch
+environment, never from a file in the tree (SPEC.md §11.1 invariant 7, the rule
+`approval serve`'s two credentials follow). It is Telegram's own `secret_token`:
+set on `setWebhook`, echoed on every delivery in the
+`X-Telegram-Bot-Api-Secret-Token` header, compared here in constant time over
+SHA-256 digests.
+
+A webhook URL is a public endpoint, and nothing in a request body could tell a
+delivery from a forgery — a self-reported field never reduces scrutiny (§11.1
+invariant 4). So the header is checked FIRST, before the path, the method and
+the body, and a post without the matching value is refused with its own code,
+counted, and reported on stderr. **A refusal is never a decision, and it appends
+nothing to the log.** That is the rule `TELEGRAM_ANOMALY_KINDS` states for
+ignored callbacks, and it binds harder here: an endpoint the internet can reach
+that could append would be an endpoint anyone could use to pad the record a
+human is asked to trust.
+
+The value is refused at startup when it is unset, shorter than 24 characters, or
+holds a character outside Telegram's `A-Z a-z 0-9 _ -`. It appears in no policy,
+no log, no record, no message and no error line: the channel redacts it from
+everything that leaves it, exactly as it redacts the bot token.
+
+| refusal | what happened |
+|---|---|
+| `webhook-secret-mismatch` | no `X-Telegram-Bot-Api-Secret-Token`, or not the registered value |
+| `webhook-duplicate-secret-header` | more than one of that header; malformed, and not resolvable by choosing |
+| `webhook-malformed-request` | the request line and `Host` header do not form a URL (400) |
+| `webhook-unknown-path` | a path this process does not serve (404) |
+| `webhook-method-not-allowed` | the right path, the wrong method; Telegram POSTs |
+| `webhook-body-too-large` | over 256 KiB; drained before the refusal is written |
+| `webhook-body-unreadable` | the body could not be read off the socket, or is not JSON |
+| `webhook-not-an-update` | JSON that is not an Update object |
+| `webhook-transport-conflict` | this channel is already receiving updates by long poll |
+| `webhook-handler-failed` | the channel threw; the log is what says what was recorded |
+
+Startup refuses in its own vocabulary before anything binds:
+`webhook-secret-missing`, `webhook-secret-weak`, `webhook-secret-charset`,
+`webhook-url-missing`, `webhook-url-insecure`, `webhook-url-port`,
+`webhook-url-userinfo`, `webhook-path-invalid`, `webhook-path-mismatch`,
+`webhook-cycle`, and `webhook-registration-failed` for a `setWebhook` the Bot
+API turned down (its status and its own description, scrubbed of the token and
+the secret), plus every `channel telegram listen` refusal, which this verb
+inherits because it needs the same bot token, chat, identity, log and policy.
+
+Four of those are the review's, and each one closes a start that used to
+succeed and then not work:
+
+- **`--path` must be the url's own path.** `telegram/webhook` with no leading
+  slash, or `/hook/` against a `--url` ending `/hook`, registered cleanly and
+  then answered every real delivery 404 after verifying its secret. `--path` is
+  an explicit restatement of the url's path and nothing else; rewriting belongs
+  in the proxy in front of this process.
+- **`--url` may not carry userinfo.** `https://user:pw@host/hook` is a
+  credential on a command line. It is refused, never stripped.
+- **The bind port may not be 0**, and must be inside 1..65535. Port 0 asks the
+  kernel for an ephemeral port, and this transport is a fixed public url
+  forwarded to a fixed local address: a receiver on a port nobody registered
+  verifies nothing and answers nothing.
+- **Every line that prints the url prints its origin and a redacted path**, in
+  the start-up banner, in `webhook_started` and in refusals: with two segments
+  or more the first is kept and the rest becomes `<path redacted>`, a path of
+  exactly one segment is replaced whole (that is the shape a tunnel's own token
+  takes), and a query string becomes `<query redacted>`. A tunnel that hands out
+  `https://host/hook/<random>` puts a bearer value in a path, and this runtime
+  does not copy it into three more places. The local bind line is redacted the
+  same way, because it carries the same path. The operator has the whole of it
+  already: they typed it into `--url`.
+
+### The proxy or tunnel is required, and this process holds no certificate
+
+Telegram delivers to HTTPS only, on port 443, 80, 88 or 8443. This process
+terminates no TLS and holds no certificate, exactly as `approval serve` does
+not: `--url` names the PUBLIC address your proxy or tunnel answers on, and
+`--port` / `--listen` names this process's own bind, which is `127.0.0.1:4683`
+unless you say otherwise. A routable bind takes both `--listen <host:port>` and
+`--allow-non-loopback` and prints a banner, because the secret arrives in a
+header and a cleartext hop hands it to whoever is on it.
+
+So a working deployment is a reverse proxy (nginx, Caddy, a cloud load balancer)
+or a tunnel (Cloudflare Tunnel, ngrok, Tailscale Funnel) terminating TLS on a
+name you control and forwarding to the loopback bind. Without one there is
+nothing to register: a plain-HTTP `--url`, or one on another port, is refused
+before any call is made rather than attempted and rejected by the Bot API.
+
+### One transport per bot, refused on both sides
+
+`getUpdates` is refused by the Bot API outright while a webhook is set, so the
+two are alternatives and never a pair. Four checks say so before anything runs,
+and they are in that order because the first needs no network:
+
+- **A lease per gate.** `approval up`, `approval channel telegram listen` and
+  this verb take a lockfile in the gate's own derived state directory,
+  `.approval/daemon/telegram-transport.lock`, holding the holder's pid, which
+  transport it is running and when it started. It is created with `O_EXCL`, so
+  two processes racing cannot both believe they took it, and a holder that is
+  no longer running is reclaimed automatically (a crash must not lock a gate
+  out of its own channel). A second taker refuses `telegram-poller-running`
+  when a poller holds it and `webhook-registered` when a webhook does, naming
+  the pid and the mode; a directory the lease cannot be written in refuses
+  `telegram-lease-unavailable`, because this file is the only thing keeping one
+  gate from running two transports. Both transports release it on a clean stop.
+
+  **A holder is a process, not a number.** Pids are reused, so the probe asks
+  three questions: does a process with that number exist, can this process
+  signal it, and did it start before the lease was written. A number that is
+  gone, one owned by a process this one cannot signal, and one belonging to a
+  process that started *after* the lease are all reclaimed, and the line says
+  which of the three it was. Only a process that is running, signalable and
+  older than its own lease keeps the gate. Where the platform will not report a
+  start time, a running pid keeps the gate, which is the stricter reading.
+
+  **Taking a lease over is a critical section, and the section is owned.**
+  Reclaiming happens inside a sibling `O_EXCL` lock that carries the entering
+  process's pid and a nonce. Inside it the lease record must still be exactly
+  the one that was judged (same pid, same `started_at`), the lock must still
+  name this entry at the moment of the write, and the lock is removed on the
+  way out only while it still does. Without the first, two processes that had
+  both read one dead holder took turns deleting each other's live lease;
+  without the other two, a process that stalled inside the section renamed its
+  lease over the one that replaced it and deleted the new holder's lock. The
+  replacement is a rename, so the lockfile is never absent and never half
+  written. A reclaim lock is evicted only when its own process is gone, judged
+  by the probe above: its age is reported and decides nothing, because "five
+  seconds have passed" says nothing about whether anybody is still inside. A
+  lock this build cannot read names no process, so the take refuses and names
+  the file rather than forcing it.
+
+  This is the check the other three cannot make. Two processes started in the
+  SAME project — one `approval up` long-polling, one `approval channel telegram
+  webhook` — passed all of them: `getWebhookInfo` is empty while the poller is
+  the one running, and the ownership registry compares instance ids, which are
+  equal because it is the same instance. Each then ran its own dispatch cycle
+  over its own state against one log, so every request reached the phone twice
+  under two nonces and only one copy could resolve a tap.
+- **What the Bot API says.** `listen` and `approval up` ask `getWebhookInfo` in
+  the same preflight that asks `getMe`, and refuse `webhook-registered` naming
+  the origin that holds the bot. For a poller an unreachable Bot API is not a
+  refusal (a captive portal says nothing about which transport owns a bot) and
+  the HTTP 409 path is the backstop. For THIS verb it is: a probe it could not
+  make refuses `webhook-probe-failed`, because the next call would be a
+  `setWebhook` that overwrites a registration this process never saw.
+- **Any existing registration, including the same url, refuses.** Telegram
+  allows one webhook per bot and keeps the last registration, so a second host
+  registering takes the taps: it overwrites the first host's `secret_token`, and
+  from then on every real tap arrives at the first host with a secret it does
+  not recognise, indistinguishable from a forgery. `--reclaim` is how an
+  operator takes the bot deliberately; with it, a url that matches the
+  registered one (host lowercased, trailing slash dropped) is reported as a
+  re-registration and anything else as a takeover that stops the other receiver
+  being posted to.
+
+  **One case needs no flag: this gate's own runner was killed.** A `SIGKILL`
+  leaves the registration in place, because the dead process never reached
+  `deleteWebhook`, and a restart that refused every time would teach operators
+  to put `--reclaim` in the unit file, which retires the protection above for
+  good in exchange for a crash recovery. So a restart may re-register the SAME
+  normalised url without the flag when the lease it just reclaimed was this
+  gate's own, written by a webhook runner, and that process is **gone**. A dead
+  poller's lease does not count, a different url does not count, and a gate
+  with no such lease does not count. Nor do the other two reclaim reasons: a
+  lease reclaimed because its pid is owned by a process this one cannot signal,
+  or because the number has been reused, is the right call for the lease and no
+  evidence at all that the runner which registered the url has stopped. Those
+  keep the refusal and the `--reclaim` demand.
+- Within one process, `TelegramChannel.claimTransport` refuses the second claim.
+
+A clean stop (SIGINT, SIGTERM) removes the webhook, so long polling works again
+afterwards. Pending updates are kept in both directions: a tap that arrived
+while the process was down is the approver's answer, and the gate is what
+decides whether it is still honourable.
+
+### Redelivery, and the cycle
+
+Telegram retries a delivery it did not get a 2xx for, so the same tap can arrive
+twice. Nothing deduplicates it: the second one reaches the gate through the same
+path as the first and is refused `already-decided`, with the first human answer
+standing — the property a button pressed twice has had since the channel
+shipped. Updates are handled one at a time, in arrival order, and the response
+is written after the update has been handled.
+
+`--cycle <duration>` (default 30s) is the dispatch period, the webhook's
+equivalent of the poll loop's per-cycle dispatch: it re-derives the pending
+queue and sends what has not been sent. A cycle also runs immediately after each
+handled update, so a paced listener's next question follows a tap without
+waiting for the timer.
+
+**A stop waits for the update it is holding.** Ctrl-C stops the receiver
+accepting, then drains: an update mid-append keeps its socket, finishes its
+decision and writes its response, and only then is `deleteWebhook` called and
+the stopped line printed. A second Ctrl-C during the drain is absorbed rather
+than killing the process, and a request that never finishes is dropped after ten
+seconds, because a stop has to end. `deleteWebhook` on that path is given five
+seconds rather than the channel's usual thirty, for the same reason: a stop an
+operator has asked for twice should not sit behind an unreachable Bot API, and
+a removal that does not land is reported as a webhook still registered.
+
+### The daemon id it stamps (APRV-448)
+
+Every record this process appends (a decision a tap delivers, the refusal of
+one, anything a dispatch cycle writes) carries the `daemon` field, with the id
+`approval status` reports for the same store: `APPROVAL_DAEMON_ID` from the
+launch environment, or `daemon-` plus the instance id derived from the log's
+`.approval` directory, which is the id the daemon loop derives. The started line
+names it (`records stamped daemon <id> (<source>)`) and `webhook_started`
+carries it as `daemon`. A declared id that is not a usable id refuses the verb
+before the bot is claimed or a port is bound, exit 2.
+
+The attested policy's `daemons` list governs this process at the write
+boundary, as it does the daemon and [`approval serve`](#serve). It is re-read at
+startup and at the top of every dispatch cycle, which is this process's tick: a
+list a human narrows and re-attests takes effect within one cycle (a cycle runs
+after every handled update and every `--cycle`), and a resolution that fails
+leaves the previous list standing. A tap whose decision is refused
+`daemon-not-allowed` appends nothing, and the refusal is reported on stderr. The
+process declares the id without marking itself the daemon.
+
+```json
+{"event":"webhook_started","url":"https://gate.example/telegram/<path redacted>",
+ "host":"127.0.0.1","port":4683,"path":"/telegram/<path redacted>","cycle_ms":30000,
+ "daemon":"daemon-3f2a9c11"}
+{"event":"stopped","notified":1,"updates":1,"decisions":1,"pollErrors":0,
+ "anomalies":{"foreign-chat":0,"malformed-callback":0,"unknown-callback":0,
+ "key-mismatch":0},
+ "webhook":{"requests":2,"updates":1,"refusals":{"webhook-secret-mismatch":1}}}
+```
+
 ## channel telegram health
 
 Makes no network call. A health check that contacted the Bot API would announce
@@ -3991,6 +5183,194 @@ belong to a RUNNING listener: they are on its stderr as they happen, in its
 Which variables are read comes from the policy, so a renamed variable reads back
 as the name you set.
 
+## channel relay
+
+A third arrival for a human gesture, beside a Telegram tap and a terminal
+(APRV-455). An operator's control plane holds an authenticated session for a
+person (the Agent Village control plane holds an EdgeOS session for each
+resident), shows them a request or their policy, and posts what they did to
+this verb. The post carries the gesture, the EdgeOS `/humans/me` id of the
+session that made it, the policy hash or the action key it answers, a nonce and
+an `issued_at`. The daemon resolves the id against the attested policy exactly
+as it resolves a Telegram `from.id`, and records the gesture through the same
+`recordChannelDecision` a tap goes through.
+
+```
+approval channel relay [--listen [host:]port | --port <n>] [--allow-non-loopback]
+                       [--proposer agent:<id>] [--policy <p>] [--dir <p>]
+                       [--log <p>] [--json]
+```
+
+### Trust level
+
+**The daemon trusts the relay's attribution.** A post that carries the relay
+secret is the operator's control plane reporting which EdgeOS account acted,
+and the daemon believes that report the way it believes the Telegram Bot API's
+report of `callback_query.from.id`. That is operator trust, stated in
+APRV-422's words: no hosted service has authority over decisions. The relay
+carries a person's gesture and decides nothing. Which approver the account is,
+whether that approver may decide this request or attest this policy, and
+whether the request is still answerable are all decided by the runtime, from
+the verified log and the attested policy, with the same codes a tap gets.
+
+What the relay cannot do, by construction:
+
+- **Act as anyone of its own.** It takes no `--as` and reads no
+  `APPROVAL_HUMAN`. Every gesture is attributed to the account
+  `approvers.<id>.senders.edgeos` maps, or refused `sender-unmapped` with one
+  `audit.decision_refused`. A policy that maps no EdgeOS account refuses every
+  gesture the same way; there is no fallback to a configured identity.
+- **Read a mapping nobody has attested.** Every gesture, decisions included,
+  resolves its sender against the policy IN FORCE: the verified bytes the
+  latest attestation names, recovered from the payload store. A mapping
+  sitting unattested on disk (the relay's own `propose` puts one there) decides
+  nothing until a human attests it. Where the in-force bytes cannot be
+  recovered, a decision is refused `policy-not-attested` (an attestation,
+  `attest-requires-terminal`) and nothing is appended; a log that cannot be
+  read keeps its own code.
+- **Choose who may sign for a policy change.** An attestation is resolved
+  against the policy IN FORCE, never the one being attested, so an account a
+  proposal adds or repoints cannot accept the proposal that names it, and an
+  amendment that introduces the EdgeOS mapping is refused
+  `attest-requires-terminal` (the operator bootstrap of APRV-449 is what maps
+  the resident the first time).
+- **Hold a token.** A grant that mints a token for the deciding surface has it
+  dropped unread; the response says only `token_issued`. Requests in the Agent
+  Village are harness-executed or sealed, so none is lost; a manual-delivery
+  request granted here has a token nobody holds and is asked again.
+- **Be reached through `approval serve` or `approval mcp serve`.** It is its
+  own process, port and credential. The registry marks it `human_only`, so no
+  wrapper publishes it, and neither serve credential reaches it.
+- **Be started by an agent.** The attribution a relay records is exactly as
+  strong as control over who launches it, because its launcher chooses the
+  secret. The hook classifier holds `approval channel relay` as `policy.core`
+  (human-only in the reference policy), so an agent session cannot start one; a
+  deployment starts it from its own launcher as the store's user. A keyed
+  `senders.edgeos` mapping adds a second lock: a process without
+  `APPROVAL_SENDER_KEY` cannot resolve any account.
+
+### The secret
+
+`APPROVAL_RELAY_SECRET` is REQUIRED and is read from the launch environment,
+never from a file in the tree (SPEC.md §11.1 invariant 7). At least 24
+characters of `A-Z a-z 0-9 _ -` (generate it: `openssl rand -hex 32`), with the
+same value given to the control plane; surrounding whitespace is stripped at
+start, so the control plane sends the trimmed value. Under the `APPROVAL_`
+prefix it is withheld from every child `approval run` spawns. The control plane sends it
+in `x-approval-relay-secret`; it is compared in constant time over SHA-256
+digests, BEFORE the path, the method or the body, and a duplicate header is
+refused rather than resolved. **A refusal never reaches the gate and appends
+nothing to the log**: it is counted, written to stderr, and answered with its
+code. The secret appears in no response, no log record and no stderr line.
+
+Loopback by default (port 4684). There is no TLS here; a routable bind takes
+`--listen <host:port> --allow-non-loopback` and prints a banner every start.
+
+### The body
+
+`POST /relay/gesture`, one JSON object, closed: an unknown field is refused, so
+nothing that looks like authority (an `actor`, a second sender, a `ts`) rides
+along on a valid post.
+
+```json
+{"gesture":"propose","policy_sha256":"<64 hex>","nonce":"<16..128 of A-Za-z0-9_->","issued_at":"2026-10-03T12:00:00Z"}
+{"gesture":"attest","policy_sha256":"<64 hex>","sender":{"channel":"edgeos","id":"<EdgeOS id>"},"nonce":"...","issued_at":"..."}
+{"gesture":"decline","policy_sha256":"<64 hex>","sender":{"channel":"edgeos","id":"..."},"nonce":"...","issued_at":"..."}
+{"gesture":"grant","action_key":"<the request's key>","sender":{"channel":"edgeos","id":"..."},"nonce":"...","issued_at":"..."}
+{"gesture":"reject","action_key":"<the request's key>","sender":{"channel":"edgeos","id":"..."},"nonce":"...","issued_at":"..."}
+```
+
+- `sender.channel` is `edgeos` and nothing else. `sender.id` is the raw
+  `/humans/me` id: an ASCII letter or digit, then up to 127 letters, digits,
+  `.`, `_` or `-`, the grammar `senders.edgeos` pins. Never a digest (a keyed
+  policy is resolved with `APPROVAL_SENDER_KEY` in the relay's environment) and
+  never an email address.
+- `issued_at` is RFC 3339 in UTC ending in `Z`, within five minutes of the
+  relay's clock either side. It is used for that window and recorded nowhere;
+  every record's `ts` is the runtime's own.
+- `nonce` is claimed before the gesture is applied, in a ledger of exclusively
+  linked files under the gate's `.approval/daemon/relay-nonces/`, kept for eleven
+  minutes. A replay is refused `relay-nonce-replayed` at this process, after a
+  restart, or at a second relay on the same gate. A retry is a new post with a
+  new nonce, and the gate answers a repeated decision `already-decided`.
+
+`propose` is the control plane's half of the onboarding review. It writes the
+rendered policy into the store, then posts its hash: the relay re-hashes the
+file and refuses `relay-policy-mismatch` when the bytes are not the ones named,
+then appends a `policy.proposed` under `--proposer` (an `agent:` id, default
+`agent:edgeos-relay`: the relay is a machine, and a `human:` proposer would say
+a person proposed what nobody typed) with the semantic diff against the
+verified in-force text and a deadline one hour out, after which the prompt
+retires from every queue. A retry of an open proposal of the same bytes returns it with
+`"existing":true`. It also admits bytes ALREADY in force (`"reaffirm":true`):
+the review most residents make is "accept, unchanged", and that acceptance is
+still their attestation. A reaffirmation changes the attester of record and
+nothing else. The prompt also reaches Telegram, where the resident's tap
+answers it equally.
+
+**Until a proposal is attested, the bytes on disk are not the policy in
+force.** Every gated call refuses `policy-not-attested` in that window (a
+grant through the relay included), exactly as during any amendment. So the
+control plane proposes and collects the acceptance in the same screen, and
+restores the in-force bytes when the resident declines or the proposal lapses.
+A `decline` appends `policy.declined` and leaves the attestation in force
+where it was, the operator's included: it is a refusal to adopt the proposed
+bytes, never a withdrawal of the policy already attested.
+
+`attest` / `decline` answer the open proposal of that hash. `attest` appends
+`policy.updated` with `actor: human:<approver>` and `payload.sender
+{channel: edgeos, id}`. A hash that names no open proposal (superseded,
+answered, never proposed) is refused `proposal-not-found`, and a file changed
+under the proposal is refused `proposal-stale`; neither attests anything.
+
+`grant` / `reject` answer a pending request exactly as a Telegram tap does,
+including `expired`, `policy-drift` (with its `audit.decision_refused` and
+withdrawal), `already-decided` and `actor-not-approver`.
+
+### Responses
+
+| status | body | meaning |
+| --- | --- | --- |
+| 200 | `{"ok":true,"gesture":…,"event":…,"seq":…,"actor":…}` | recorded (`propose` returns `sha256`, `seq`, `existing`, `reaffirm`, `changes`, `loads`) |
+| 409 | `{"ok":false,"gesture":…,"refusal":{"code","message"}}` | the gate or the decision surface refused; the code is from `gate_refusal_codes` or `channel_decision_refusal_codes` |
+| 4xx/5xx | `{"error":{"code","message"}}` | the relay refused the post; the code is from `relay_refusal_codes`, and nothing was appended |
+
+`relay_refusal_codes` (frozen, pinned in `conformance/vectors/refusal-unions.v1.json`):
+`relay-secret-mismatch`, `relay-duplicate-secret-header` (401),
+`relay-malformed-request` (400), `relay-unknown-path` (404),
+`relay-method-not-allowed` (405), `relay-body-too-large` (413),
+`relay-body-unreadable`, `relay-body-invalid`, `relay-sender-invalid`,
+`relay-gesture-stale` (400), `relay-nonce-replayed` (409),
+`relay-nonce-unavailable` (503, the ledger could not record the nonce, so
+nothing was decided), `relay-policy-mismatch` (409), `relay-handler-failed`
+(500).
+
+Start-up refusals (exit 2, `{"error":{"code"}}` under `--json`):
+`relay-secret-missing`, `relay-secret-weak`, `relay-secret-charset`,
+`relay-proposer-invalid`, `relay-bind-invalid`. An unreadable log exits 4, a
+torn tail 3, a corrupt chain 1.
+
+With `--json`, stdout carries one object per line: `relay_started` (`host`,
+`port`, `path`, `proposer`), one `relay_gesture` per gesture that reached the
+gate (`gesture`, `ok`, and `seq`/`record`/`actor` or `code`), and `stopped`
+with the counters. Never a body, a sender id or the secret.
+
+There is no transport lease. A Telegram bot admits one receiver; a relay has no
+such constraint, because compare-and-append, the gate's idempotency and the
+nonce ledger (each claim written whole and linked into place, so exactly one
+claimant wins) make two relays on one gate safe. A second relay on the same
+port fails to bind.
+
+**Who is listening on the port is the caller's check.** The secret travels in a
+header, so whoever holds the loopback port when the control plane posts
+receives it. In a sandbox where another uid can bind loopback (the Agent
+Village's `hermes` user), the control plane checks that the listener on 4684
+belongs to the relay's own user before it posts, the same foreign-listener
+rule the hook applies to `serve`, and posts to the literal `127.0.0.1`, never
+`localhost`, which another uid could answer on `[::1]`. A unix socket in a directory only the relay's
+user can write, or a signature over the body in place of a bearer secret, would
+remove the check; neither is in this version.
+
 ## quickstart
 
 `approval quickstart [--dir <path>] [--api-base <url>]` is the human-only solo setup ceremony. It
@@ -4041,17 +5421,20 @@ code. A re-run in a scaffolded directory writes nothing and exits 0. A directory
 carrying `APPROVALS.md` (the SPEC.md §5 fallback filename) already has a policy:
 init reports `policy-exists` and writes no `APPROVAL.md` beside it.
 
-Payloads are tracked. `.approval/payloads/` is deliberately not ignored: those
-bytes are what each approval bound to, and evidence belongs in the history. To
-ignore them instead, add `.approval/payloads/` yourself — the log keeps every
-`payload_hash`, but the bytes behind them stop being rebuildable.
+Payloads are ignored (APRV-445; they were tracked before it). `.approval/payloads/`
+holds the exact bytes each approval bound to, and for a proposal those are a
+person's own words, so the merged block lists it. To keep the bytes in history
+as evidence instead, remove that line yourself; the log keeps every
+`payload_hash` either way. Files in the store are written 0600 in a 0700
+directory whatever the umask.
 
 Keys are not. The merged block ignores `.approval/*.sqlite` (a projection),
 `.approval/vault.enc`, `.approval/env`, `.approval/keys/`, `.approval/**/*.tmp-*`
 and `.approval-journal/`. `.approval/keys/` is the one that matters most and is
 easiest to miss: it holds the X25519 private halves of sealed token delivery, and
-because the payload store beside it is tracked on purpose, `.approval/` is a
-directory people `git add` from. A key committed there opens that action's
+because the payload store beside it was tracked by default before APRV-445 (and
+still is wherever an operator chose that), `.approval/` is a directory people
+`git add` from. A key committed there opens that action's
 `token_sealed` for everyone holding the log. The line is written whether or not
 your policy has opted into `token_delivery: sealed`, and `approval doctor`'s
 `sealed-keys` row reports a key that is tracked or in a store no line covers.
@@ -4097,6 +5480,81 @@ setting to change it, which the fail-closed invariant does not survive;
 `docs/grok-hook.md` states which cases the adapter cannot cover and is worth
 reading before the file is committed.
 
+**`hook muse` emits exactly ONE dialect and nothing else (APRV-350).** Muse Code
+treats output carrying any key it does not support as a failed hook, and a failed
+hook fails OPEN, so the belt-and-braces payload that satisfies several harnesses
+at once satisfies this one not at all. Its envelope is snake_case with its own
+tool names (`bash` carrying a per-call `workdir`, `write_file`, `read_file`, and
+`search` naming an ARRAY under `paths`), and a Contributor-tier model is refused
+for every tool call regardless of policy (`hook-muse-contributor-model`).
+`approval hook muse --help` prints the `.muse/hooks.json` the human commits;
+`docs/muse-hook.md` opens with the fail-open finding and the model warning.
+
+**`hook hermes` is the second exception to the exit codes above, and the one
+harness whose configuration is not in the repository (APRV-398).** Its event
+names are its own — `pre_tool_call` and `post_tool_call`, not `PreToolUse` — and
+its envelope is snake_case (`tool_name`, `tool_input`, `session_id`, `cwd`,
+`profile`, `extra`). A deny is `{"action":"block","message":…}` **at exit 2**,
+which Hermes treats as an unconditional block whose message it takes from the
+stdout directive first; an **allow is `{}`** at exit 0, because Hermes has no
+allow directive and no directive is the allow, so an allow's reason goes to
+stderr. `execute_code` is refused outright
+(`hook-hermes-execute-code-unbound`): it carries a program and no path, no argv
+and no working directory, so no verdict could bind it. **A call whose effective
+directory the event does not carry is refused too** (`hook-unsupported-execution-context`,
+APRV-415): a live probe found that the envelope `cwd` is the Hermes PROCESS
+directory while `terminal` keeps a per-session recorded directory that a `cd` moves
+and no field reports, and that the file tools resolve relative paths against that
+one — so a `terminal` call with no absolute `workdir`, and a `write_file`, `patch`,
+`read_file` or `search_files` call whose path is relative or missing, are refused
+with a reason telling the session to retry with an absolute path. The file a human
+commits is `$HERMES_HOME/config.yaml` — name the home explicitly and spell its last
+segment `.hermes`, or the classifier does not recognise the organ — where the event
+is a mapping KEY rather than an `event:` field, `fail_closed: true` belongs on every
+entry because its default is false, and TWO timeouts bound the wait: the per-entry
+`timeout` caps at 300s and `plugins.hook_callback_timeout` defaults to 30s and
+fails closed by itself, so `--timeout` must come down under 300s. `--dir` is
+mandatory here, because a gateway session's `cwd` is the user's home. Without
+`hooks_auto_accept: true` (or `HERMES_ACCEPT_HOOKS=1`) and no TTY, Hermes
+**silently never registers the hook**. `fail_closed: true` was OBSERVED to block a
+hook crash, a hook timeout and unparseable output on `main` `118984d7`, which makes
+this the first adapter since Claude Code that is a gate rather than a backstop;
+`v0.21.3` (build 2026.9.14) does not know the key and fails open silently, so
+`approval doctor`'s `harness-version-unverified` row pins that floor.
+`approval hook hermes --help` prints the YAML; `docs/hermes-hook.md` opens with the
+fail-closed result, the floor, and what a post event does not prove.
+
+**`--harness-cap <duration>` makes the question end before its asker does
+(APRV-423).** Every harness in the table kills the hook at some ceiling (Hermes
+caps a `pre_tool_call` entry at 300s, Claude Code kills it at the `timeout` in
+its settings file), and every one of them reads the killed process as a
+non-blocking error and runs the tool call. Before this flag the request that
+hook had opened stayed pending afterwards, so a tap arriving later was recorded
+as a plain `approval.granted` on a call nobody was holding, and the deny and the
+grant described one request and disagreed about it (APRV-410).
+
+The flag states the ceiling. The hook records it on `approval.requested` as
+`payload.harness_cap_ms`, and the runtime judges the request against the SHORTER
+of the policy's `defaults.approval_ttl` and that ceiling minus a 60s margin
+(`HARNESS_CAP_MARGIN_MS` in `src/core/harness-wait.ts`, two of the daemon's 30s
+sweep intervals, so the `approval.expired` record lands while the harness is
+still listening in the common case; a skipped sweep or a slow intake can put it
+after the kill, and what keeps a late tap safe then is the gate's lazy `expired`
+refusal, which judges the lapse by arithmetic whether or not the record exists).
+A cap can only SHORTEN: the runtime takes a minimum, so a stated ceiling longer
+than the TTL changes nothing, which is SPEC.md §11.1 invariant 4 applied to a
+duration. Without the flag, `hook hermes` assumes **30s**, Hermes's default
+`plugins.hook_callback_timeout`, which does not clear the margin: every
+manual-class call is refused `hook-harness-cap-too-short` until the operator
+raises `plugins.hook_callback_timeout` above the per-entry `timeout` and passes
+`--harness-cap` with the smaller of the two (`--harness-cap 300s` for the
+documented `600` over `300`). A stated cap is still clamped to Hermes's observed
+300s per-entry maximum. No other adapter assumes a ceiling, because no other
+harness documents one. A ceiling at or below the margin leaves no window for a
+human and is refused `hook-harness-cap-too-short` before anything is registered
+or requested. `approval serve` pins the same value on every hook call it makes
+with `--hook-harness-cap`, as it pins `--timeout` with `--hook-timeout`.
+
 **Register the same command for the post-execution event too (APRV-145).** One
 binary answers two events, dispatched on `hook_event_name`. A `PostToolUse` or
 `PostToolUseFailure` run closes the delegated `execution.started` the
@@ -4133,7 +5591,38 @@ semantic-version-shaped tag, `tag <name>`, `--tags`, or `--follow-tags` is
 that DELETES a remote ref — `--delete`, `-d`, or a colon refspec such as
 `:refs/heads/x` — is `vcs.ref.delete` with the ref names bound (APRV-352), and a
 tag deletion keeps `release.publish`; ordinary branch pushes retain their branch
-or trunk class. Claude file tools
+or trunk class.
+
+`git tag` splits on its flags since APRV-397: a LISTING (`-l`, `--list`, `-n`,
+`-n<num>`, `--contains`, `--points-at`, `--merged`, `--sort`, `--format`,
+`--color`, `--ignore-case`, `--omit-empty`, or no argument at all) is
+`read.shell`, rule `git-tag-read`, the same class `git log`, `git status` and
+`git branch` take for reading local repository metadata. Everything else stays
+`release.publish`: `-a`, `-d`, `-f`, `-s`, `-m`, a bare tag name, and any flag
+the listing allowlist does not name, so a future `git tag` option cannot arrive
+as a read. A positional under `-l` is a pattern rather than a name.
+
+The packaging and archive tools are classified too, for the same reason and in
+the same release (APRV-397): they were `unclassified`, so a verification could
+not run them and reached for `curl` and a script instead. `npm pack` is a
+workspace write of the tarball, scoped to `--pack-destination`, and
+`network.call` when a positional names a registry package; `npm init` writes
+`package.json`; a bare `npm --version`, `-v`, `-V`, `--help` or `-h` is a read,
+while every npm subcommand the table does not name keeps its `unclassified`
+deny; `tar -t` lists (a read) and `tar -x`/`-c` writes into `-C` or the archive
+`-f` names; `gunzip` reads only with `-c`/`--stdout`, `-t`/`--test` or
+`-l`/`--list` and otherwise replaces the file it names; `base64` reads unless
+`-o` names an output;
+`openssl dgst` (and the `md5`/`sha*` spellings) reads unless `-out` names one,
+while every other `openssl` subcommand stays unclassified. Each write is scoped
+by the arithmetic `rm` uses: a destination under a resolved scratch root or a
+relative one is `files.write.workspace`, and an absolute destination elsewhere, a
+`..` segment, an unreadable value, or a destination flag with nothing readable
+after it is `files.delete.out_of_scope`, rule `packaging-write-out-of-scope`,
+with the destination bound. A `tar` whose mode is not in its words is
+`hook-opaque`. `docs/claude-code-hook.md` holds the table and the reasoning.
+
+Claude file tools
 (Edit, Write, MultiEdit, NotebookEdit) and
 Cursor Write/Delete are gated only when the file is policy-protected
 (`APPROVAL.md`, `.approval/`, `CLAUDE.md`, `AGENTS.md`, `.claude/settings*`,
@@ -4170,7 +5659,8 @@ its own flags are not parsed as this verb's.
 - `hook-rejected` — a human said no.
 - `hook-revoked` — a granted approval was withdrawn.
 - `hook-expired` — the TTL lapsed before a decision.
-- `hook-timeout` — no decision inside `--timeout`; the request stays live.
+- `hook-timeout` — no decision inside the wait (`--timeout`, clamped to what
+  `--harness-cap` leaves after the 60s margin; APRV-423); the request stays live.
 - `hook-gate-refused:<c>` — the gate refused intake; `<c>` is its own frozen code
   (`policy-not-attested`, `budget-exceeded`, …).
 - `hook-policy-unavailable` — `APPROVAL.md` could not be loaded.
@@ -4536,6 +6026,57 @@ defined over the canonical VALUE, so non-JSON input has no defined
 could reproduce. Empty input is the same answer. A file that exists but cannot be
 read is exit 4.
 
+## payload run
+
+The payload `approval run` will recompute for a command, printed before any
+approval exists: its argv, the cwd it will run in, and the size and SHA-256 of
+the script that argv names.
+
+```
+approval payload run -- bash scripts/install.sh
+{"argv":["bash","scripts/install.sh"],"cwd":"/repo",
+ "script":{"argv_index":1,"path":"/repo/scripts/install.sh","bytes":412,
+           "sha256":"fef0…"}}
+```
+
+The `script` object is the whole point of the verb (APRV-401). A grant over
+`bash scripts/install.sh` used to bind that STRING, so the bytes behind the path
+were whatever the file held at execution time and the requester controlled the
+file between the request and the grant. The digest is inside the hashed value,
+so a script edited after the declaration is refused `payload-mismatch` before the
+child is spawned and before anything is appended, and the approver's card carries
+the path, the byte count and the digest because the payload does.
+
+The argv names a script in two shapes: a known interpreter (the six shells,
+`node`, `python`/`python3`, `perl`, `ruby`, `deno` — each a name the command
+classifier already knows) followed by a path operand, or a path at `argv[0]` the
+kernel reads a shebang from. An inline program (`bash -c …`, `node -e …`) is
+already a word of the argv and binds no file.
+
+An argv naming no readable script carries no `script` key and hashes exactly as
+it did before the rule existed, which is why every record already in a log and
+every declaration already written into a task file still verifies.
+
+`--hash` prints the `payload_hash` instead of the bytes — the value a task file's
+action declaration carries. `--cwd` states the directory the run will happen in,
+because that directory is inside the hash and every relative argv word resolves
+against it. The two ends must agree, so pass the same `--cwd` the run will use.
+
+What is NOT bound is stated in full in `docs/run-payload-binding.md`: nothing
+resolved through `PATH`, nothing a bound script itself reads or executes, and the
+instant between this hash and the spawn.
+
+This verb reads the one file the argv names as its script and nothing else. No
+log, no policy, no network, no token, and it executes nothing.
+
+It is **local only**: the MCP wrapper and `approval serve` withhold it, because
+the path it digests is one of the command's own words and no transport guard
+confines those the way the store confinement confines `payload hash`'s
+positional. A remote caller could otherwise ask for the digest of any file the
+server process can read (`-- bash /etc/shadow`) and learn that the path exists
+and what its bytes fingerprint to. Compute the binding where the command will
+run, which is the only place the value is true.
+
 ## payload agentmail-draft
 
 An AgentMail draft is mutable server-side state, so an approval of a draft id
@@ -4791,7 +6332,15 @@ says nothing about it.
   it, and neither is a log to append onto. A working log that is a strict prefix
   of the committed copy is an `anchor-behind` warning, not a stop. The `started`
   line names the rev and seq this run is held to (`"anchor"`), and the tick line
-  carries the comparison it made. Git is read, never fetched.
+  carries the comparison it made. Git is read, never fetched. When the log was
+  rewritten between the tick's opening read and the check's own read of the file
+  (a `log sync` or a records pull replacing `events.jsonl` under the loop), the
+  check reads the file again through the same verified read, reports one
+  `anchor-reread` warning naming both heads, and the verdict beside it is the
+  second read's (APRV-389). Every `anchor-diverged` stop is reached from the
+  file's bytes and confirmed by that second read, and its message names the seq
+  the chains parted at and both heads without also claiming either chain is a
+  prefix of the other.
 - ENVELOPE DRIFT — a task file whose `state:` contradicts the log gets an
   `envelope.drift` event (actor `system:daemon`), once per claim.
 - TTL SWEEP — every live request whose TTL lapsed gets an `approval.expired`
@@ -4910,8 +6459,11 @@ Warnings go to stderr as `{"event":"warning","code":"...","message":"..."}`, wit
 `code` one of `task-unreadable`, `frontmatter-invalid`, `envelope-invalid`,
 `task-id-missing`, `tasks-dir-unreadable`, `append-refused`, `expire-refused`,
 `render-failed`, `watch-unavailable`, `prune-refused`, `write-back-refused`,
-`advance-refused`, `draw-unavailable`. A warning never stops the
-loop, and neither does `{"event":"git_evidence_failed","step":"commit",…}`.
+`advance-refused`, `dark-session-undetermined`, `anchor-behind`,
+`anchor-reread`, `checkpoint-due`, `draw-unavailable`, `sample-deferred`,
+`drift-deferred`. A
+warning never stops the loop, and neither does
+`{"event":"git_evidence_failed","step":"commit",…}`.
 
 Dangling advance cycles (APRV-264): at startup and before every trigger, the
 daemon lists every advance execution nobody closed and closes each one this
@@ -4936,6 +6488,73 @@ rather than inferred from the queue's backlog. `rendered` is emitted when the qu
 CHANGES; the file itself is rewritten every tick, because TTL countdowns move even
 when the log does not.
 
+**A sample that met another writer is deferred, not dropped (APRV-381).** The
+audit sweep's append is a compare-and-append against the head it read, so it can
+meet a lock another writer holds (`lock-timeout`) or a record another writer
+landed in between (`head-moved`). Both are reported as `sample-deferred` on
+stderr, naming the action key and saying that the sweep retries on the next tick:
+
+```
+warning  sample-deferred  audit sampling deferred hook:6f2a:vcs.push.main
+  (lock-timeout): another writer holds .approval/log/events.jsonl.lock; gave up
+  after 2000ms The sample is NOT lost: it is still pending in the log's own terms
+  (eligible, drawn, no audit.sampled yet), and the sweep retries it on the next
+  tick.
+audit.sampled: hook:6f2a:vcs.push.main drawn for review (execution.started at
+  seq 51445) — recorded at seq 51447, the retry of the sample this run deferred
+  earlier
+```
+
+The second line is the same `sampled` event with `"retry":true` added, and it
+appears only when this run is the run that deferred the sample: a restarted
+daemon still makes the append, and says nothing about a promise it did not make.
+Nothing is remembered across processes because nothing needs to be: the sweep
+re-derives the pending set (eligible, drawn by the sampler, no `audit.sampled`
+yet) from the verified log on every tick, so a deferral is lost work only if the
+daemon never runs again.
+
+Every other append refusal on a sample keeps the `append-refused` form, because
+`validation`, `canonicalization`, `corrupt-tail` and `io` are facts about the
+record or the file that no amount of retrying repairs.
+
+**A drift record that met another writer is deferred too (APRV-403).** The drift
+scan's append is the same compare-and-append against the head it read, and it
+met the same contention: the end-to-end test that holds the append lockfile for
+a whole tick showed the scan printing `append-refused … (lock-timeout)` for an
+`envelope.drift` the next tick went on to write. So the same split applies, from
+the same closed list of transient codes, on both drift reasons:
+
+```
+warning  drift-deferred  envelope.drift for task-042 was deferred (lock-timeout):
+  another writer holds .approval/log/events.jsonl.lock; gave up after 2000ms The
+  record is NOT lost: the disagreement is still there in the log's own terms, and
+  the scan re-derives it and retries on the next tick.
+envelope.drift: task-042 (backlog/tasks/task-042.md) claims state approved, the
+  log says proposed — recorded at seq 12, the retry of the record this run
+  deferred earlier; the file is repaired to match the log later in this tick
+```
+
+The `retry` flag has the same standing as the sample's: it is on the `drift`
+event only when THIS run is the one that deferred the record, it is output
+bookkeeping that no append consults, and a restarted daemon makes the same
+append and claims nothing. Deferring costs nothing because the scan carries no
+state between ticks: it re-reads the folder, re-derives the state from the
+verified log, and `driftAlreadyLogged` keeps a repeat idempotent.
+
+An `envelope.drift` refused for `validation`, `canonicalization`, `corrupt-tail`
+or `io` keeps the `append-refused` form it always had.
+
+**The sweep waits `2000ms` for the lock and no longer, by decision.** The daemon
+is the one writer that could afford a longer wait and deliberately takes the
+default. A tick is serial, so a blocking wait here delays the expiry lines, the
+`state:` write-back and `QUEUE.md`; the writers it contends with hold the lock
+across spans no polite wait covers (`approval log advance` across a whole
+verify-and-commit, `approval log sync` across a baseline move); and the appends it
+would be muscling in front of are the ones somebody is waiting on, a hook's gate
+verdict or a lane's execution record. Deferring costs one line and at most one
+tick interval, and it is provably lossless. Raise `--interval` only if you want
+the retry later; there is no flag for the lock wait, on purpose.
+
 ## up
 
 **Normal startup after setup and human attestation.** Run from the intended
@@ -5019,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
@@ -6035,6 +7661,14 @@ STARTTLS, AUTH — and then QUIT. It proves the host answers, that the TLS mode
 the one the server offers, and that the credential is accepted. It does not prove
 delivery, and it puts no message on the wire.
 
+An `smtp.host` that is an IP address is probed without SNI (APRV-416). A server
+name is a name, so there is nothing to send for an address, and Node 26 refuses
+the session outright where earlier versions only warned. The certificate is
+still verified; what it is verified against is the address, which the server's
+certificate has to carry as an IP entry in its subject alternative names. A
+relay whose certificate names only a hostname therefore fails the probe when it
+is configured by address and passes when it is configured by that name.
+
 A failed probe keeps the values. A laptop behind a captive portal is not a reason
 to make you type five things again. The refusal prints the SMTP code and the
 server's first line, with the credential redacted, and the undo.
@@ -6335,6 +7969,442 @@ The guest instructions string says so, tells the caller to poll `status`, and
 states plainly that a granted request executes nowhere: the demo is the approval
 flow itself.
 
+## serve
+
+`approval serve` is the same agent-facing surface as `mcp serve`, over HTTP,
+for a harness that has no local log and no local policy: a sandboxed tenant
+whose daemon runs elsewhere, one process per tenant. It is a transport and not
+a second gate. Every verdict, every verb and every batch of records comes from
+the function the CLI dispatches to; nothing under `src/serve/` classifies a
+command, resolves a policy, mints a token or verifies a chain.
+
+STDOUT IS EMPTY. The bound address, the identity, the daemon id every record
+it appends carries (see [Which daemon wrote it](#which-daemon-wrote-it-aprv-448))
+and the store root go to stderr on one started line. SIGINT and SIGTERM close
+the listener and exit 0.
+
+### The two credentials
+
+Two bearer values, both read from the launch environment (SPEC.md §11.1
+invariant 7: nothing is loaded out of the working tree), both required before
+the listener exists, and refused when they are equal or shorter than 24
+characters:
+
+| variable | opens |
+|---|---|
+| `APPROVAL_SERVE_AGENT_TOKEN` | `GET /verbs`, `POST /hook/<harness>`, and the allowlisted verbs below |
+| `APPROVAL_SERVE_TENANT_TOKEN` | `GET /verbs`, `GET /log/follow`, `GET /export`, `GET /status`, and every other published verb |
+
+**The agent credential never reads the log it is judged by.** That is the
+sentence the split exists for. An agent that could stream the verified log
+could read every decision made about it and the shape of the oversight it is
+under; an agent that could export the store could carry all of it away.
+
+Authorization is therefore per verb, and it is an ALLOWLIST. The party at the
+other end of this transport is a sandboxed harness on another machine, not the
+operator at their own laptop, so the agent credential opens only what a harness
+under oversight needs in order to ASK and to ACT ON a grant:
+
+> `instructions`, `hook_classify`, `request`, `wait`, `withdraw`
+
+Five verbs, and the shortness is the point: a harness under oversight asks and
+is answered, and everything else about the gate belongs to the party the gate
+is for.
+
+Neither payload builder is on it, under the rule that a builder is the agent's
+only if it builds from the request's own arguments and never reaches a host
+resource. `payload_hash` takes a FILE, and on this transport that file is on
+the daemon's machine while the caller is not: every path it could name is one
+the host put there, so answering would be a hash oracle that also files the
+bytes into the payload store. `payload_agentmail-draft` takes two ids rather
+than a path, but reads the draft over HTTPS with `AGENTMAIL_API_KEY` from this
+server's own environment, so a remote caller would be spending the host's
+credential on ids it chose: the same fault wearing a network instead of a
+filesystem.
+
+Everything else the catalog publishes is the tenant's. The ones easiest to wave
+through and most worth naming: `log_tail` and `log_export` return records,
+`log_verify` and `gate_status` return the log's length, its head hash and the
+live state of the gate, `queue` returns the tenant's pending decisions,
+`policy_check` and `policy_test` answer what the policy does with a class and
+name the absolute store path while doing it, and `status` is the tenant's view
+of the oversight the agent is under. So are the verbs that touch the host
+rather than the log: `run` and `sandbox` spawn argv on the daemon's machine,
+every `adapter_<name>` spends vault credentials, `log_advance` opens pull
+requests against the tenant's records. And so are `register` (its positional is
+a host path; the hook endpoint is a harness's way to register, and it
+synthesises the envelope itself), the two payload builders, `token`,
+`coverage`, `doctor`, `audit_list`, `audit_obligations`,
+`channel_telegram_health`, `journal_write`, `journal_read`, `feedback`,
+`values`, `import_agents-md`, `reindex` and `render`.
+
+**No caller names a path, and no positional wears a dash.** Four rules, and
+each closes a route around the others.
+
+1. The server appends `--dir`, `--log` and `--policy` to every verb call in
+   every scope from its own launch configuration, and a call supplying one of
+   them is refused `serve-path-pinned` even when the value is correct.
+2. A positional beginning with `-` is refused `serve-positional-flag`, in every
+   scope. Positionals are emitted first and verbatim, and the verb reads any
+   token starting with `-` as a flag — including the `--payload=/path`
+   spelling — so without this rule a refused flag could be sent as a value and
+   reach the parser through the front door. `trailing` needs no such rule: it
+   always follows a `--` separator, and the flag parser stops there, which is
+   what lets `hook classify -- git push -f` classify a command line that has
+   flags in it.
+3. The AGENT credential may not use a path-typed flag at all
+   (`serve-flag-not-permitted`), and may use only the flags on a short
+   per-verb list. A harness reached through this transport has no files on the
+   daemon's machine, so a path it names is either useless or somebody else's;
+   payload bytes arrive through the hook route, which builds the envelope from
+   the tool call.
+4. The TENANT credential's path-typed flags are confined to the store
+   (`serve-path-outside-store`), resolved through `realpath` on the deepest
+   existing ancestor so traversal and a symlinked directory both refuse.
+
+Which flags are path-typed comes from the registry rather than from a list
+kept beside the server: a flag declared `"path"` publishes as an ordinary
+`{"type":"string"}`, so the wire contract is unchanged, and it is confined on
+the day it appears. A test walks every published verb and fails on any flag
+that is neither declared `"path"` nor reviewed as something else.
+
+A verb added to the registry tomorrow is published on both surfaces the same
+day and is TENANT-scoped until somebody decides otherwise. The allowlist is
+what widens, and widening it is a diff in the server and a diff in a test.
+
+An agent-credential call to anything off that list is refused
+`serve-agent-forbidden`, and a tenant-credential call to an allowlisted verb
+(`request`, `wait`, `withdraw`, `hook_classify`, or `consume`, which this
+surface withholds entirely) is refused `serve-tenant-forbidden`. Both are scope refusals rather
+than not-founds: a caller that guessed a path learns that the door exists and
+is not theirs.
+
+Every path requires one of the two. There is no unauthenticated surface at all,
+not a health check and not a 404, so a caller with no credential learns nothing
+about what exists.
+
+### The endpoints
+
+`GET /verbs` is the published catalog: `approval mcp serve`'s tool list, name
+for name and schema for schema, because it is derived from the same registry
+filter by the same function. `--as` is absent from every published schema and
+the launch identity is appended last to every argv, so a caller can neither
+name an identity nor change one. `grant` is absent, as it is there and for the
+same reason: SPEC.md §11 makes the agent the untrusted policy, and a tool list
+is a statement about what a surface is for. Each entry carries the scope that
+opens it, so the catalog is honest about `status` being the tenant's.
+
+### The response contract
+
+`POST /verb/<tool_name>` and `POST /hook/<harness>` answer with ONE body:
+
+```json
+{"exit_code": 0, "stdout": "…", "stderr": "…",
+ "stdout_truncated": false, "stderr_truncated": false}
+```
+
+`stdout` and `stderr` are exactly what the CLI wrote to each stream, and
+`exit_code` is exactly what it exited. A client reproduces the invocation by
+writing `stdout`, writing `stderr`, and exiting `exit_code`. A client that
+wants the verb's machine-readable refusal parses `stderr`, which is the stream
+the CLI prints refusals on. Both streams are bounded at 256 KiB and clipped at
+a codepoint boundary, with a flag saying whether that happened.
+
+**Nothing about a verdict travels in a header.** It used to: the exit code rode
+on `x-approval-exit-code`, and server-authored refusals did not set it. A
+client following the documented rule then read a missing header as zero, and
+zero is ALLOW on Claude Code, Cursor, Codex and Muse — so a 1.1 MB hook
+envelope came back as a 413 that meant *proceed*. The exit code is now data in
+the body, it is present on every response including every refusal, and on a
+refusal it is always non-zero.
+
+**A client treats a missing, unparseable or truncated body as a BLOCK.** That
+rule is not a nicety: a transport failure this server never saw (a proxy, a
+dropped connection, a process killed mid-response) has no exit code to carry,
+and the only safe reading of "no answer" from a gate is no.
+
+`POST /hook/<harness>` takes the harness envelope the stdin form would read, for
+every harness this runtime speaks a hook protocol for. Its `stdout` is
+BYTE-FOR-BYTE what `approval hook <harness>` prints for that envelope, because
+it IS that stdout: the request body is handed to `commandHook` as its stdin and
+nothing reshapes the answer. The exit code must travel with it, because the
+dialects disagree about where a block lives — Claude Code, Cursor, Codex and
+Muse put it in the body at exit 0; Grok Build and Hermes use exit 2. Hermes's
+ALLOW is `{}` and carries its reason on stderr and nowhere else, which is why
+`stderr` is part of the contract rather than a diagnostic.
+
+A refusal the SERVER raises on the hook route — an oversized body, a credential
+at the wrong door, a method it does not answer — carries `{"error":{…}}` and
+`exit_code: 2` **and** a `stdout` holding the harness's own block directive,
+rendered by the same function that prints one. A client that writes `stdout`
+and exits `exit_code` therefore blocks on both halves of every dialect at once.
+That holds for the refusals that fire BEFORE the URL is parsed, too — a
+rotated credential, a malformed `Host` — because the harness is read off the
+raw request target for the purpose of the refusal body and nothing else. A
+credential rotation must not read as a permission, and on four of the six
+dialects a body with no block directive at exit 0 is exactly that.
+
+Where the harness is not known (an unroutable path, an unrecognised name)
+`stdout` is absent, and the client rule in the paragraph above is what covers
+it.
+
+A deny is a VERDICT, so its HTTP status is 200; only a refusal by the server
+is not.
+
+**A Hermes tenant needs `--hook-harness-cap`, or every manual class is refused
+(APRV-423).** `approval serve` pins `--harness-cap` on every hook call with
+`--hook-harness-cap`, as it pins `--timeout` with `--hook-timeout`. Without it a
+`POST /hook/hermes` runs as `approval hook hermes` with no flag, which assumes
+Hermes's 30s default `plugins.hook_callback_timeout`; 30s does not clear the 60s
+margin, so every manual-class call answers `hook-harness-cap-too-short` (a
+block, nothing registered or requested, no prompt sent) and a tenant is gated
+shut rather than gated. The repair for a serve operator, who does not own the
+tenant's `$HERMES_HOME`: have the tenant raise `plugins.hook_callback_timeout` in
+the harness's config above the per-entry `timeout`, then start `serve` with
+`--hook-harness-cap <the smaller of the two>` (`--hook-harness-cap 300s` for the
+documented `600` over `300`). The value is per server rather than per tenant, so
+a server fronting several Hermes tenants states the smallest ceiling any of them
+runs under; a stated cap can only shorten a window, never lengthen one. The
+same flag bounds the hook's WAIT on every route: `--hook-timeout` is clamped to
+what the ceiling leaves after the margin, so a hook that adopts an already-open
+question under a ceiling with no room in it answers `hook-timeout` at once
+(question left open for the retry grace) instead of being killed mid-wait.
+
+`GET /log/follow?from=<seq>&cursor_hash=<64hex>&limit=<n>` answers one page of
+verified records and the cursor to ask with next time. The cursor is EXCLUSIVE
+and the subscription is `core/log-subscribe.ts`'s, so SPEC.md §8 holds
+unchanged: the chain is verified from genesis before anything is emitted, and a
+`cursor_hash` that does not match the retained prefix is refused with the
+`integrity` code, `cursor-mismatch` as its reason, and NO RECORDS, not even the
+ones a partial drain had already produced. `caught_up` says whether the page
+exhausted the log or the limit. The server keeps no subscription state: a page
+is a function of the cursor in the request and the bytes on disk, so a host that
+sleeps and wakes serves the same next page it would have served before.
+
+**`from` greater than zero REQUIRES `cursor_hash`.** The subscription calls the
+sequence-only form a weaker bootstrap, weak in exactly one way: it cannot
+detect a fully recomputed replacement prefix on its first read. A streaming
+consumer pays that once and then retains the digest it verified. A paged one
+never does — every request is a first read — so the weakness would be
+permanent, and a caller who dropped the hash would be served a replaced prefix
+silently while an honest caller who kept it got the refusal. `from=0` is the
+only hashless form, because replaying from genesis binds nothing.
+
+`from` must be a sequence number this runtime can represent and `limit` must be
+between 1 and 1000. Both are refused `serve-invalid-cursor` when they are not,
+rather than clamped: a clamp answers a different question than the one asked
+and the caller cannot tell it happened.
+
+`GET /export` answers the store as a gzipped POSIX tar. Its contents are a
+positive allowlist (`APPROVAL.md`, `.approval/log/`, `.approval/payloads/`,
+`.approval/QUEUE.md`, `.approval/index.sqlite`), so `.approval/keys`,
+`.approval/env`, `.approval/daemon` and any `vault.enc` are out by not being
+named rather than by a denylist remembering them. `.approval/payloads/` is in,
+and it is the entry the reasoning turns on: the log records a `payload_hash`
+for every action a human was shown, and those bytes live there. An archive
+carrying the hashes without the bytes would hand a tenant a chain of references
+to evidence they no longer hold, which is a receipt for an exit rather than an
+exit.
+
+**No link is followed, of either kind, and a link refuses the whole export.**
+A name-based allowlist is no defence against one: `ln -s
+.approval/keys/sender.key .approval/log/note.jsonl` passes every check that
+reads the name and hands over the key, and a link out of the store hands over
+any file on the host.
+
+So every entry is `lstat`ed and a symbolic link refuses the export with
+`serve-export-symlink`; every file is then opened `O_NOFOLLOW` and `fstat`ed,
+so the checks are made against the descriptor that is actually read rather
+than against a name that could have been swapped in between; and a regular
+file whose link count is greater than one refuses with
+`serve-export-hardlink`. That last is the case with nothing to notice — a hard
+link is a second name for one inode, with no link to refuse to follow and no
+target to inspect — so the link count is the only thing that distinguishes it.
+Each refusal names the path and never its target.
+
+The whole export is refused rather than the offending file skipped, because an
+archive silently missing a file is one nobody can tell from a complete one.
+
+The only file the export drops on its own account is the append lockfile
+derived from the log path, which exists for exactly the span of the copy
+because the export holds that lock. It is matched as an exact path, not as a
+`*.lock` class: a tenant's own `.approval/payloads/x.lock` is the tenant's, and
+a name this runtime happens to use for bookkeeping is no reason to drop
+somebody else's file.
+
+`GET /status` is the `status` verb, answered to the tenant credential.
+
+### The bind, and where TLS is
+
+`--port <n>` picks the port (default 4682) and always binds `127.0.0.1`.
+`--listen <[host:]port>` is the only way to bind anything else, passing both is
+a usage error, and a non-loopback host ALSO requires `--allow-non-loopback`: two
+flags, because the credentials here are bearer values and a cleartext hop hands
+them to whoever is on it. A widened bind prints a banner on stderr saying
+exactly that. This process terminates no TLS and holds no certificate; the
+supported deployment is a loopback bind behind a proxy the operator owns.
+
+`--listen unix:<path>` (or `APPROVAL_SERVE_LISTEN=unix:<path>`, which the flag
+overrides) binds a unix-domain socket instead (APRV-445), for a sandbox on the
+same machine running as a different uid. The path must be absolute, inside an
+existing directory OWNED BY THE SERVING UID: that directory is the access
+control, so a directory somebody else owns is refused at startup (exit 2). The
+socket itself is opened `0666` once bound, and who may reach it is decided by
+the directory's mode, group or ACL. An other-writable directory (`/tmp`) is
+refused, since anyone could swap the socket. The widening to `0666` happens only
+in a directory nobody but the serving uid can write; in a group-writable one the
+socket keeps the umask's mode (a notice says so). The residual: between the bind
+and the chmod the socket carries the umask's narrower mode, which fails closed.
+A socket file is stale, and replaced, only when a connect to it is refused
+(`ECONNREFUSED`) or it vanished (`ENOENT`); a live one (another server answers)
+is refused rather than taken over, one whose probe fails any other way
+(`EACCES`, a full backlog) is left in place and refused, and anything at the
+path that is not a socket is refused rather than destroyed. Clients speak plain HTTP over the socket, with the same two
+bearer credentials. `--allow-non-loopback` has nothing to say about it.
+
+### Which daemon wrote it (APRV-448)
+
+Every record this server appends, from a verb call and from a hook call alike,
+carries the `daemon` field, and the id is the one on the started line
+(`records stamped daemon <id> (<source>)`). It is resolved once, at startup, by
+the rule the daemon loop uses: `APPROVAL_DAEMON_ID` from the launch environment
+when it is set, otherwise `daemon-` plus the instance id derived from the
+store's `.approval` directory. That is the id `approval status` reports for the
+same store, so a tenant who reads `daemon` on a record can look it up. No
+request names any part of it. A declared id that is not a usable id (lowercase
+letters, digits, `.`, `-`, `_`, at most 64 characters) refuses the server
+before it binds, exit 2.
+
+The attested policy's `daemons` list governs this server at the write boundary,
+exactly as it governs the daemon. It is re-read from the verified log and the
+attested policy inside the store lock before every verb call and every hook
+call, so a list a human narrows and re-attests while the server runs refuses
+the very next call. A refused append writes nothing, and the verb answers
+`append-failed` with the write boundary's code under `error.append`:
+
+```json
+{"ok":false,"error":{"code":"append-failed","append":"daemon-not-allowed",
+ "message":"task.registered could not be appended: this daemon's id is village-goa-1 and the attested policy's `daemons` list admits village-goa-2, …"}}
+```
+
+A hook call whose append is refused blocks, in the harness's own dialect.
+
+The processes that stamp the field are three: the daemon loop (`approval daemon
+run`, and `approval up`, whose Telegram listener runs in the daemon's process),
+this server, and [`channel telegram webhook`](#channel-telegram-webhook). A
+session's own CLI calls, `approval hook <harness>` run as a harness's own
+process, and a standalone `channel telegram listen` stamp nothing. This server
+declares the id without marking itself the daemon: the mark is what routes an
+advance under the daemon's own autonomous class, and a process that dispatches
+the verbs an agent asks for does not hold it.
+
+### What it never does
+
+It appends no record on its own account. Every event in the log under it was
+written by a verb a caller asked for, under the identity the operator fixed at
+launch, and stamped with the daemon id on the started line. It reads no
+`.approval/env`.
+
+### What it serialises, and what it does not (APRV-427)
+
+One lock per store, held inside this process. It is the lock for every stretch
+of work that may append to the store or must read it as one snapshot:
+
+| work | holds the store lock |
+|---|---|
+| `POST /verb/<name>`, including `GET /status` | for the whole call |
+| `GET /log/follow` | for the page, so no append this process makes lands under a verified read |
+| `GET /export` | for the whole snapshot, and the log's append lockfile as well, so no other process appends during it either |
+| `POST /hook/<harness>` | for its MUTATION sections only: everything up to its poll loop (intake, the abandoned-question sweep, register, request) and everything after it (the spend, a withdrawal) |
+| a hook call's WAIT | never |
+| `GET /verbs` | never |
+
+So one hook call waiting on a human holds nothing. While it polls, the tenant's
+`status`, `queue` and follow answer, and a second hook call opens its own
+question and waits beside the first. A hook call runs on a worker thread of
+this process, because a hook's wait is a synchronous sleep and on the
+listener's own thread it would stop the listener; the verdict, its bytes and
+its exit code are `approval hook <harness>`'s, exactly as before. A new thread
+reads the log once BEFORE it asks for the store lock, so the cold walk of a
+mature log (hundreds of milliseconds) happens in parallel and never inside the
+lock; its reads under the lock are then warm.
+
+**The pool is bounded, because each thread holds its own copy of the log**
+(about 26 MB idle, plus roughly 84 MB once it has read a 73k-record log). At
+most `--hook-threads` hook calls run at once, 16 by default, and no more
+threads than that ever exist. Up to `--hook-queue` further calls, 64 by
+default, wait for a slot in arrival order; a queued call has registered and
+requested nothing yet. A call that finds every slot and every place in line
+taken is refused at once with `serve-hook-saturated` (HTTP 503), carrying the
+harness's own block directive in `stdout` and `exit_code: 2`, and nothing is
+appended for it. Four finished threads are kept warm for the next call.
+
+**Time in line is charged to the harness's ceiling.** The ceiling a harness
+puts on its hook (`--hook-harness-cap`, or the adapter's documented default)
+runs from the moment the call ARRIVED at this server. A call that waits for a
+slot or for the store lock spends that budget, and the hook judges, waits by
+and records on its request the ceiling less that wait, so any question it
+opens lapses at arrival plus ceiling minus the 60s margin, while the harness
+is still listening. A call that arrived with room and has less than the
+margin left when its slot or the lock arrives is refused
+`serve-hook-saturated` instead, appending nothing: a question opened then
+would still be on the approver's phone when the harness kills its asker. A
+ceiling that never had room is the hook's own `hook-harness-cap-too-short`,
+as before.
+
+A torn read in a hook's poll (another writer's line caught half-landed, which a
+filesystem that grows a file a page at a time can show a reader) is read again
+on the next tick, up to five ticks in a row, before the hook treats the log as
+unreadable. This holds for the stdin form too, beside the daemon. Verb calls still run one at a time, in the
+order they arrive, because some of them are synchronous and blocking too (`run`
+spawns, and `wait` sleeps on the listener's thread, so an agent's `POST
+/verb/wait` still holds the listener for its own timeout; the hook route is the
+one a harness waits on).
+
+Two appends never interleave. Inside this process the store lock is the
+reason: every append is inside one of the sections above, and the sections run
+one at a time. Across processes (a daemon, a CLI run beside this server) the
+reason is the one every `approval` process relies on: each append takes the
+log's lockfile and compares-and-appends against the head it read.
+
+**A client that goes away is not answered, and does not spend.** When the HTTP
+connection of a waiting hook call closes before its answer, the call stops at
+its next poll tick without spending a grant and without withdrawing its
+question, and nothing is sent. A grant that lands afterwards is left for the
+harness's retry of the same command, which carries it and spends it once; an
+undecided question is adopted by that retry. A call still in line for a
+thread simply leaves the line. A grant already spent before the connection
+closed stays spent.
+
+Closing the listener runs in this order: stop accepting connections; cancel
+every hook call the same way (waiting calls stop at their next tick, queued
+ones leave the line); terminate the hook threads from inside the store lock,
+which also waits out any verb or mutation section still running, so no thread
+is killed while holding the log's append lockfile; and only then destroy the
+remaining sockets. A question a cancelled call opened stays open for the retry
+grace, exactly as for an `approval hook` process that was killed mid-wait.
+Shutdown therefore takes as long as the longest work already holding the store
+lock (a `POST /verb/wait` runs to its own timeout), so a platform that kills
+the process a fixed time after SIGTERM (a container's stop timeout, a
+supervisor's kill timeout) should allow more than that, or the kill lands on
+work the lock was protecting. A hook call whose thread fails answers a
+refusal, `serve-hook-failed`, with the harness's own block directive in
+`stdout`.
+
+## muse
+
+`approval muse` starts a local, single-tenant synthetic consumer facade. The
+operator fixes the tenant and distinct read/propose credentials in the launch
+environment and the store root with `--dir` before the listener binds to
+loopback. The proposal
+scope can register an in-memory envelope and request its declared action. The
+read scope sees status, pending requests and the canonical rendering of a live
+request. Both scopes are narrow: the listener has no grant, reject, execution,
+token, generic verb or export route. Human decisions use the separately
+configured Telegram listener. A pending request does not prove delivery to
+Telegram. See `docs/muse-connector.md` for the local HTTP contract, native
+evidence limits and prerequisites.
+
 ## Constrained Codex preparation
 
 approval codex prepare is an artifact generator. It writes one fresh review
@@ -6473,7 +8543,9 @@ The deadline is the policy's `approval_ttl`, not a harness ceiling. Every hook
 adapter answers inside a timeout its harness sets, and the retry grace exists so
 a denial-by-deadline is recoverable; this transport has no timeout at all, so a
 human who answers in eleven minutes is answering rather than arriving too late.
-`--wait` overrides it.
+`--wait` overrides it. The bridge therefore states no `--harness-cap` and the
+window shortening of APRV-423 never applies to it: there is no process here that
+something else will kill, so there is nothing for a cap to keep ahead of.
 
 It answers accept or decline only, in the vocabulary the request advertised
 through `availableDecisions`, matched exactly and never by prefix, so