approval-md 0.3.0 → 0.4.0

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
@@ -498,6 +507,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 +683,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 +764,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 +1114,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 +1666,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 +1705,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 +2002,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 +2067,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 +2106,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 +2251,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 +2466,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 +2501,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 +2549,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 +2585,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 +2610,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 +2760,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 +2821,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 +2844,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 +2874,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 +3075,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 +3093,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 +3178,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 +3300,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 +3441,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.
 
 
 
@@ -3669,6 +4129,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
@@ -3978,6 +4448,253 @@ 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 four function objects `listen` registers. 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 +4708,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 +4946,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 +5005,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 +5116,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 +5184,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 +5551,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 +5857,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 +5984,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 +6013,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
@@ -6035,6 +7179,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 +7487,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 +8061,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