approval-md 0.2.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
@@ -390,6 +399,13 @@ did left conflict markers inside the log mid-ceremony.
 So the ritual became deterministic code, on the `policy amend` precedent: when a
 hand-ritual proves dangerous, it becomes a verb the gate can read.
 
+**You rarely type it any more (APRV-346).** `approval up`'s preflight calls this
+function itself whenever the working log is a byte-for-byte extension of the
+committed one, which is the state every records advance leaves behind. What is
+left for a hand-run `approval log sync` is the fork: two chains that share a
+prefix and then carry different records at the same `seq`. See
+[up](#up) for what the preflight checks before it delegates.
+
 Everything runs inside ONE hold of the append lockfile. The lock is normally
 taken per append; here it spans the whole operation, because an append landing
 between the snapshot and the restore is exactly the interleaving that forks a
@@ -485,6 +501,17 @@ range they cover, and pushed to a short-lived records branch that exists for
 exactly that commit. Main is protected here, so the commit reaches it through a
 pull request; `--pr` opens that pull request through the ordinary `gh` path.
 
+This verb carries the class `log.advance` for everyone who runs it, in a
+session, in an orchestrator, or at a human terminal. The daemon's cadence
+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.
@@ -656,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.
@@ -712,7 +748,77 @@ refusal  {"ok":false,"error":{"code":"...","message":"..."}}  on stderr
 
 `path` is the file that was hashed; the logged payload carries its basename only,
 so an exported log leaks no home directory. The event's payload is
-`{"policy_path":"APPROVAL.md","sha256":"<64 hex>"}`.
+`{"policy_path":"APPROVAL.md","sha256":"<64 hex>","payload_hash":"<64 hex>"}`.
+
+**`payload_hash`: the attested bytes, recoverable (APRV-356).** The verb also
+writes the attested text to the payload store beside the log and binds that
+file's hash on the record, so the policy IN FORCE can be produced rather than
+only named. A digest cannot produce the file it names, and the privileged-gesture
+rule (`policy.core` gestures from a channel, SPEC.md §10.3) has to be decided
+against the policy in force rather than against the one being proposed. A reader
+re-hashes the recovered text against `sha256` from the verified log, so the store
+is checked rather than trusted, and a store that cannot be written REFUSES the
+attestation: nothing is appended, because a record claiming a binding whose bytes
+are absent is a worse artifact than no record. Records written before this
+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)
 
@@ -769,6 +875,92 @@ current bytes carry no attestation. It never moves doctor's exit code: an
 unattested organ breaks nothing on this machine, and the enforcement for one is
 the guard in CI.
 
+### `--path <path>`: signing off a protected file (APRV-338)
+
+SPEC.md's amendment-provenance rule says text that reached a protected file
+without a grant carries `(Amended APRV-n, pending sign-off.)` and holds no more
+authority than a proposal until a human ratifies it. Nothing recorded the
+ratification: no event, no verb, and no way for CI or doctor to tell a ratified
+amendment from a pending one. This flag is that record.
+
+```
+approval policy attest --path SPEC.md --as human:carter
+```
+
+One path per call, repository-relative (an absolute path under `--dir` is
+accepted and recorded relative). The runtime hashes the bytes on disk; there is
+no flag for the digest. The record is a **`gate.path.signed_off`** event:
+
+```
+{"event":"gate.path.signed_off","actor":"human:<id>",
+ "payload":{"path":"SPEC.md","sha256":"<64 hex>"}}
+```
+
+**Which paths.** Exactly those whose edits classify `policy.edit` or a
+`policy.edit.*` sub-class: the built-in prose set (`CLAUDE.md`, `AGENTS.md`,
+`.npmrc`, `.github/workflows/`) plus everything the live policy's
+`protected_paths` widens to, including a path routed to a sub-class such as
+`policy.edit.design`. The policy is loaded to answer that, and a policy that
+does not load contributes nothing, which narrows what may be signed rather than
+widening it.
+
+Three refusals are specific to this flag, all exit 2:
+
+```
+path-is-policy       the policy file: use `approval policy attest` with no flag
+path-is-core         a gate organ (use --organ), the approval home, or the log
+                     directory, which no verb ratifies
+path-not-protected   an ordinary file, or a path that is not repository-relative
+```
+
+`--organ` and `--path` together are a usage error, as are `--policy` and
+`--path`: each pair names two different claims and guessing which one was meant
+is how the wrong record gets written. `--json` adds `signed_path`:
+
+```
+success  {"ok":true,"seq":7,"sha256":"<64 hex>","path":"/abs/SPEC.md",
+          "signed_path":"SPEC.md"}
+```
+
+**Weaker than a grant, and read last.** A grant binds the exact hunk a human saw
+in a prompt; a sign-off stands for the whole file. So the protected-path guard
+asks about a sign-off only after its search for a grant covering the change has
+come up empty, and the finding it prints says so in words. A change that a grant
+does cover still passes on the grant and still names it. Signing off is for the
+case the pending-sign-off suffix was invented for: text a human has read at that
+commit and agrees with, for which no grant was ever taken.
+
+**Signing off bytes that are on a branch.** The digest the guard checks is the
+file's blob at the commit under review, and that is usually a pull request's
+head rather than anything on disk in the primary checkout. `--dir` and `--log`
+are separate flags for exactly this: `--dir` is the checkout whose bytes are
+hashed and which the recorded path is relative to, `--log` is the log the record
+is appended to. So a human ratifying an open pull request reads the change,
+puts a checkout at that commit somewhere (a `git worktree`, or the branch
+checked out in a scratch clone), and runs:
+
+```
+approval policy attest --path SPEC.md \
+  --dir /path/to/checkout-at-that-commit \
+  --log /path/to/primary/.approval/log/events.jsonl \
+  --as human:<id>
+```
+
+The record lands in the primary checkout's log, where a log advance carries it
+to a records branch, and the guard then finds it for that path at that digest.
+The verb never writes a log inside the worktree it hashed. If the digest it
+prints is not the one the guard's failure named, the checkout is at the wrong
+commit or the file has been edited since: the two must agree exactly, and a
+mismatch is a sign-off on bytes nobody reviewed.
+
+The verb classifies `policy.core` when `--path` is present (without it the verb
+attests the gate's own configuration and stays pass-through), so under this
+repository's policy the harness hook denies it to an agent with
+`hook-class-human-only` before the verb's own `actor-not-human` refusal is
+reached. `approval doctor`'s `pending-sign-off` row lists the protected files
+that still carry the marker with no record over their current bytes; like
+`gate-organs` it never moves doctor's exit code.
+
 ## policy amend
 
 **Progress, on stderr.** The verb re-verifies the whole chain and recovers the
@@ -832,6 +1024,16 @@ resolution still prints in the semantic diff below for the human who attests it.
 Until APRV-296 every declared class had to be pinned, in both directions, and a
 one-line TTL amendment on 2026-09-07 took three runs to land because of it.
 
+The one check every declared class still faces is REACHABILITY: a class nothing
+can emit is a line that will never fire, and the ceremony refuses it rather than
+leaving an operator believing in it for a year. Three ways to be reachable: the
+command classifier's fixed table, a `protected_paths` entry routing a path
+family to a `policy.edit` sub-class, and `RUNTIME_CLASSES` in
+`src/core/command-class.ts`, which names the classes a runtime cycle asks the
+gate for directly and no command spells (`log.advance.daemon` is the first,
+APRV-382). A new class of that third kind needs its line there in the SAME build
+the ceremony runs, or the amendment refuses `policy-suite-failed`.
+
 **And then the whole dogfood suite, still before the attestation.** The pin check
 is a subset of `tests/dogfood.test.ts`, and the seq 23351 ceremony passed the pins
 and went red on CI over a dogfood test about the values block. So `--commit` also
@@ -912,15 +1114,125 @@ 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`.
 
-It refuses outside a git repository, and refuses 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 the amendment" false. On the branch flow
+**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
+the amendment" false. It refuses `dirty-tree` when one of those three is staged
+in one state and modified again in the working tree, because the commit is
+assembled from the WORKING TREE and would otherwise carry bytes the operator's
+`git diff --cached` never showed. An unrelated *unstaged* path is deliberately
+not a refusal: the scratch index lays exactly the ceremony's paths over the
+remote's tree, so nothing else can reach the commit, and refusing over one would
+stop the ceremony in the checkout it is written for, where the daemon's envelope
+write-backs leave task files modified as a matter of course. On the branch flow
 it also refuses when there is no `origin` remote, and when a `--branch` name
 already exists. Every one of those refusals happens BEFORE the attestation, so a
 refused `--commit` never leaves an attested policy without its commit. The same
 holds for the fetch, the two base checks, the policy suite and the dogfood suite
 above.
 
+**`--pr`: the ceremony finishes its own job (APRV-341).** `--pr` is `--commit`
+plus "and publish it": it forces the BRANCH flow whatever the protection probe
+answered, so the amendment is committed on `origin/<default branch>` in a scratch
+index, pushed to `policy-amend-<seq>`, carried by a pull request, and armed with
+`gh pr merge <branch> --merge --auto`. The merge queue picks the strategy from
+there. `--pr --direct` and `--pr --no-publish` are usage errors: each pair asks
+for opposite ceremonies.
+
+The pull request is OPENED or UPDATED. `gh pr list --head <branch> --state open`
+is asked first, and when one is already standing its title and body are edited
+rather than a second being opened, so a re-run of a ceremony that stopped
+half-way finishes rather than failing at `gh pr create`. A `gh` that cannot
+answer the question falls through to `create`, which is the path that was there
+before.
+
+**The verb never switches branches.** On 2026-09-16 an agent-written runbook for
+the primary checkout ended with `git checkout main` after the amend commit, which
+rewound `APPROVAL.md` and `events.jsonl` under a live appender; the hook then
+appended 204 records on the stale chain and the log forked. `--pr` exists so that
+runbook does not: the commit is assembled with `git read-tree` into a scratch
+index and pushed by sha, the checkout ends the verb on the branch it started on,
+with the same HEAD, the same index and the same working tree, and the only file
+that moved is the log, which gained the attestation. A test compares all four
+before and after.
+
+Without `--pr` (and on a box with no `gh`) the printed runbook does the same
+thing by hand, and it does not switch branches either (APRV-360): `approval log
+sync`, `git add`, `git commit`, `git push origin HEAD:refs/heads/policy-amend-<seq>`,
+`gh pr create --head`, `gh pr merge --auto --merge`. A fixture test pins the six
+commands and asserts that no printed line contains a `git checkout`, because a
+fallback nobody checks is where the branch switch came back.
+
+The form printed before APRV-360 opened with `git checkout -b policy-amend-<seq>
+origin/main`. On 2026-09-18 the primary's main was fourteen commits behind, the
+switch refused rather than overwrite `QUEUE.md`, the working log and six
+payloads, and the ceremony stalled with an edited, attested, unpublished policy.
+`approval log sync` is the first line now for that reason: it brings the checkout
+current, and it refuses `log-diverged` rather than fast-forwarding over a fork.
+
 `--commit` also pushes, on both flows. When there is no `origin` to push to, the
 direct flow reports the push as still to run rather than listing it among the
 commands it ran. `--no-publish` stops the ceremony at the commit: nothing is
@@ -962,9 +1274,9 @@ beneath it.
   sha256  8acbd01cda98
 
 Committed
-  ✓ committed the policy and the log together:
+  ✓ committed the policy, the log and the attested policy text together:
 
-    git add APPROVAL.md .approval/log/events.jsonl
+    git add APPROVAL.md .approval/log/events.jsonl .approval/payloads/8acbd01cda98….json
     git commit -m "Policy: amend APPROVAL.md: 1 class resolution(s) (attested seq 2)"
 
 Publishing
@@ -1057,10 +1369,16 @@ is the human rendering only.
    prints the SEMANTIC diff, computed by the real engine on both versions;
 4. runs the load advisory;
 5. asks for confirmation (skipped by `--yes` and `--dry-run`);
-6. attests: one `policy.updated` event, identical to `approval policy attest`;
-7. prints, or with `--commit` runs, the git ceremony — `git add <policy> <log>`
-   (plus the pins when they moved), a `git commit` citing the attestation seq,
-   and the push (and, on the branch flow, the branch and the pull request);
+6. attests: one `policy.updated` event, identical to `approval policy attest`,
+   which since APRV-356 also stores the attested bytes in the payload store and
+   binds their hash on the record;
+7. prints, or with `--commit` runs, the git ceremony — `git add <policy> <log>
+   <attested bytes>` (plus the pins when they moved), a `git commit` citing the
+   attestation seq, and the push (and, on the branch flow, the branch and the
+   pull request). The store file rides in the same commit because a committed
+   log carrying a binding whose bytes were never committed leaves the policy in
+   force unrecoverable for everyone reading that copy, the CI protected-path
+   guard included;
 8. publishes, unless `--no-publish`: a push the remote refuses is answered by
    the branch, push, pull request and auto-merge above, each reported as it
    lands, and a step that fails drops to the runbook from there.
@@ -1117,7 +1435,7 @@ attestation may still proceed.
  "publishing":null|{"attempted":true,"complete":true,
              "via":"direct"|"branch"|"recovery"|"none",
              "branch":null|"policy-amend-2","pushed":true,
-             "prUrl":null|"https://...",
+             "prUrl":null|"https://...","prUpdated":false,
              "autoMerge":"armed"|"refused"|"not-attempted",
              "steps":[{"command":"git push origin main","ok":false}],
              "stoppedAt":null|"git push -u origin policy-amend-2",
@@ -1149,10 +1467,19 @@ the message.
 - `io` — the policy file or the log could not be read or written.
 - `load-failed` — `--require-load` and the policy does not load. Nothing was
   appended.
-- `commit-preconditions` — `--commit` outside a git repository, with staged
-  changes beyond the policy, the log and the pins, or (branch flow) with no
-  origin remote or a `--branch` name already taken. Checked before the
-  attestation; nothing was appended.
+- `commit-preconditions` — `--commit` outside a git repository, with the policy
+  and the log in different repositories, or (branch flow) with no origin remote
+  or a `--branch` name already taken. Checked before the attestation; nothing
+  was appended.
+- `staged-unrelated` — the index carries staged changes beyond the policy, the
+  log and the pins (APRV-341). Its own code because its repair is its own: one
+  `git restore --staged <path>`. Checked before the attestation; nothing was
+  appended.
+- `dirty-tree` — one of those three is staged in one state and modified again in
+  the working tree (APRV-341). The commit is assembled from the working tree, so
+  it would carry bytes `git diff --cached` does not show. An unrelated *unstaged*
+  path is not this refusal and never was. Checked before the attestation;
+  nothing was appended.
 - `fetch-failed` / `base-policy-diverged` / `base-log-diverged` — the remote the
   amendment would be based on could not be fetched, carries a policy this edit
   was not written against, or carries a log this working log does not contain.
@@ -1181,6 +1508,114 @@ the message.
 - `log-unreadable` / `log-torn-tail` / `log-corrupt` — nothing is amended from a
   log that does not verify.
 
+## policy apply
+
+**The hand-paste this replaces (APRV-343).** Agents may not write `APPROVAL.md`:
+it is `policy.core`, and this project's policy holds that class human-only. So a
+policy change an agent proposes travels as a document under `docs/proposals/`
+that quotes each current line byte for byte beside its replacement, and the
+human pastes. Two things go wrong with a paste, and both have:
+
+- **a whole-file copy reverts what it did not know about.** The prepared file was
+  written against the policy as it stood when the proposal was drafted, so
+  anything landed in between is silently undone. That is the failure
+  `base-policy-diverged` catches for the commit, one step too late to help;
+- **a paste carries its wrapper.** One paste of a proposal page took the page's
+  own fence with it, which hid a block from the loader (APRV-273).
+
+`approval policy apply <proposal.md>` answers both by construction. It writes no
+byte that is not anchored to a byte it proved present in the live file, and it
+reads fences by their backtick run, so a four-backtick wrapper around a
+three-backtick block is the wrapper it is rather than part of the content.
+
+### The proposal format
+
+A proposal is ordinary markdown. Anywhere in it, a fenced block **with a
+declared language** whose immediately preceding non-blank line is a label is a
+member of a pair:
+
+| label | means |
+|---|---|
+| `Current:` | the bytes as they stand in the live policy |
+| `Replace with:` | what they become |
+| `Supersedes:` | optional: an earlier section's RESULT, to match instead |
+
+A fence with no info string is skipped, which is APRV-273's hazard turned into a
+rule. A block whose label names no role is skipped too, so a proposal page can
+carry a `bash` block of commands to run afterwards without the applier mistaking
+it for policy text. Pairs apply in document order.
+
+**Supersession is declared, never inferred from position.** A later section that
+rewrites a line an earlier section already rewrote quotes the earlier section's
+*result* under a `Supersedes:` label; the applier looks for that text when the
+section's own `Current` block is no longer in the file, which is exactly the
+state the earlier section left behind. Position could not carry this: two
+sections that touch one line are not in general in the order the file needs, and
+a rule inferred from order is a rule nobody can read off the page. A pair whose
+`Current` **and** `Supersedes` blocks both occur in the file is
+`proposal-ambiguous`: two spellings of one line is a question about which the
+file means, and no verb here will pick.
+
+**Whole-file replacement is not accepted**, and that is the decision rather than
+an omission. The verb's whole value is that every byte it writes is anchored to
+a byte it proved present, which is what makes a stale proposal a refusal instead
+of a silent revert. A whole-file blob has no anchor. `approval policy amend`
+over a hand-edited file is already the supported way to replace the file
+deliberately.
+
+**The values block is treated exactly as the policy block is**, by knowing
+nothing about either. The applier is a byte-level replacement over the whole
+file: it does not parse the policy, does not locate blocks, and does not care
+which fence a pair lands in. The values block is inert (SPEC §11.1 invariant
+10), so applying one changes no verdict, and the attestation the amendment
+appends covers the whole file's bytes either way (SPEC §5.2, §5.3).
+
+`docs/proposals/README.md` is the contract as a page for proposal authors, and
+`docs/proposals/approval-md-2026-09.md` is a worked example of every part of it.
+
+### What it does, in order
+
+1. Refuses an agent identity (`apply-agent-actor`) before reading anything.
+2. Parses the proposal into ordered pairs.
+3. Resolves every pair against an **in-memory** copy of the policy. A proposal
+   whose third pair is stale writes nothing at all, so "a stale proposal cannot
+   half-apply" is a property of the code rather than of the order somebody wrote
+   the sections in.
+4. Prints the replacements, each as its matched block and its replacement.
+5. Asks for confirmation (`--yes` skips it, `--dry-run` stops here).
+6. Writes the policy, then runs `approval policy amend --pr` in this process —
+   which asks its OWN question about the semantic diff, because "are these the
+   bytes" and "is this the policy" are different questions.
+
+**It publishes by default (APRV-360).** The amendment runs with `--pr`, so the
+branch is created on the remote by refspec, the pull request is opened, the
+merge is armed, and the checkout ends where it started. Before this the amend
+ran with no flag: the policy was written and attested, and the operator was
+handed a procedure that began with a branch switch. On 2026-09-18 the primary
+refused that switch and the ceremony stalled with an edited, attested,
+unpublished policy, which is the one state in which every gated operation on the
+box refuses. `--no-publish` stops at the commit and is passed through to the
+amend; `--pr` is accepted and does nothing, because runbooks already say it, and
+`--pr` with `--no-publish` is a usage error.
+
+`--no-amend` writes and stops, and says loudly that the policy is now edited and
+unattested. A run where every pair resolves and no byte moves is a success and a
+no-op: the proposal has already been applied.
+
+**Refusal codes** (`error.code` with `--json`; frozen public API): `usage`,
+`io`, `apply-agent-actor`, `proposal-empty`, `proposal-malformed` (a `Current`
+with no `Replace with`, or the reverse), `proposal-stale` (a quoted current text
+is not in the file), `proposal-ambiguous` (it occurs more than once, or both it
+and its superseded text occur). Every one of them writes nothing.
+
+Two outcomes are deliberately not in that union. Answering no at the
+confirmation is exit 0 with `aborted:` on stdout, exactly as `policy amend`
+answers it: nothing failed, and an error object at exit 0 would be a
+contradiction the caller has to resolve. An amendment that refuses has already
+printed its own code from its own frozen union, so this verb adds a sentence
+naming the state that leaves behind — the replacements written, the policy
+unattested — and returns the amendment's exit code unchanged.
+
 ## register
 
 The task file is read only. Nothing is rewritten, so unknown frontmatter keys
@@ -1231,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
@@ -1252,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
@@ -1426,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
@@ -1491,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
@@ -1529,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
@@ -1660,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
@@ -1798,7 +2403,7 @@ refusal  {"ok":false,"error":{"code":"...","message":"...","detail"?:"...",
 ## sandbox
 
 ```
-approval sandbox [--allow-loopback] [--log <path>] -- <cmd> [args…]
+approval sandbox [--allow-loopback] [--read-jail] [--log <path>] -- <cmd> [args…]
 ```
 
 Runs a command with outbound network denied by the operating system. It appends
@@ -1836,6 +2441,15 @@ is a sandbox somebody turns off.
 server. It is a real widening: a port is a port, and anything listening on one is
 reachable from inside.
 
+**`--read-jail`** (APRV-347) goes the other way and makes the room smaller: file
+reads become deny-default, with the gate root, the scratch roots and a fixed
+runtime set opened by `subpath`. It is already on, without the flag, whenever
+the policy declares a `read_scope` block, which is the spelling an operator
+commits and attests; the flag is for trying it on one command first. There is no
+flag that turns the jail OFF where a policy asked for it, because a flag an agent
+can pass must only ever narrow what it can do. See
+[docs/sandboxed-exec.md](./sandboxed-exec.md) for the profile and its limits.
+
 **Exit 127** means the command was NOT run: this machine has no working sandbox
 primitive, or the command is not on `PATH`. Unlike `approval run`, this verb
 fails closed on both: it makes one promise and has nothing else to offer.
@@ -1852,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
@@ -1860,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
@@ -1890,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:
@@ -1925,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
@@ -1950,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
 
@@ -2095,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
@@ -2118,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
@@ -2141,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",
@@ -2158,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
 
@@ -2355,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;
@@ -2372,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,
@@ -2447,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
@@ -2530,6 +3269,23 @@ The checks, at length:
   log sync` for a diverged log, `approval up` otherwise — never a `git` command:
   a repair line telling an operator to reset a branch would be doctor making the
   decision this project keeps human.
+- **attested-policy-on-main** — whether the policy the log vouches for is the
+  policy `origin/<branch>` carries (APRV-342). `attestation` above asks whether
+  the LOCAL file is attested; between a `policy amend` and its pull request
+  merging that answer is yes while a fresh checkout of main carries the old
+  policy with no attestation covering it, so every gate operation there refuses
+  `policy-not-attested`. Nothing said so until this row: on 2026-09-16 `approval
+  up` ran in exactly that state and reported "already at the remote tip". PASS
+  when the attested hash equals the SHA-256 of `APPROVAL.md` at the remote tip.
+  FAIL with `attested at seq N, not yet on main`, naming
+  `policy-amend-<seq>` when this checkout has already seen that branch on the
+  remote, and fixing with `approval policy amend --pr` — which opens the pull
+  request or updates the open one, so the same command is right either way.
+  SKIP with no attestation, outside a git checkout, and where there is no
+  remote-tracking ref. **It fetches nothing**, for the reason
+  `main-behind-origin` fetches nothing, and it looks for the amend branch among
+  the remote-tracking refs rather than asking GitHub. `approval up`'s preflight
+  prints the same sentence on stderr and never refuses on it.
 - **harness-version-unverified** — whether the harness binary hosting the
   PreToolUse hook changed since the log last saw a record from it (APRV-227).
   The only row that asks anything about a program outside this repository, and
@@ -2544,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
@@ -2573,7 +3336,14 @@ The checks, at length:
   words SPEC.md §5.3 fixes: a file with no block is an operator who has declared
   no values, which is a state and not a fault. The only FAIL is a block that is
   present and unreadable, and its fix names the code rather than proposing a
-  repair, because what the block should say is the human's to write.
+  repair, because what the block should say is the human's to write. The one
+  exception is the block APRV-336 replaced (`version: 1` with a `wants` list):
+  that is a correct document of the wrong vintage rather than a broken one, so
+  the row's detail carries the loader's migration message and its fix names the
+  three edits (fold `wants:` into `like:`, rename `responds:` to
+  `communication:`, quote `version: "0.2"`) plus the re-attestation that the
+  whole-file digest requires. The pass detail lists what the block declares,
+  which are `love`, `like`, `dislike` and `communication` and nothing else.
 - **checkpoint** — how this log stands against its own human-signed checkpoints
   (APRV-257), running the same check as `approval log verify --checkpoints`, so
   two implementations of "does this log's own signature contradict it" cannot
@@ -2622,6 +3392,73 @@ The checks, at length:
   doctor does not interpret or merge the TOML hook tables. Malformed JSON
   FAILS; a different valid Codex hook profile SKIPS as undetermined rather than
   being called broken.
+- **autonomy-alias** — which rules of this policy still write the deprecated
+  bare `supervised` (APRV-335). The spelling parses as `supervised-retro` and
+  every gate enforces it as one, so the row is never a FAIL and never moves the
+  exit code: a red line over a spelling would be doctor going red over prose.
+  The two PASS shapes are the whole row. Where some rule uses it, the detail
+  names each one, in the order the loader's own notes name them, and the `fix`
+  is `approval policy amend`, which owns the edit and the re-attestation that
+  edit costs. Where none does, the detail says so plainly, which is the answer
+  an operator wants before a future schema version drops the alias. A policy
+  that did not load is a SKIP: it names no level at all, and its own failure is
+  reported by the attestation row and by `approval policy check`.
+- **pending-sign-off** — which protected files carry SPEC.md's
+  `(Amended APRV-n, pending sign-off.)` marker with no `gate.path.signed_off`
+  record over their current bytes (APRV-338). Informational and never a FAIL,
+  for the two reasons `gate-organs` is: nothing on this machine is broken by
+  unratified prose, and the enforcement that does bite is the CI-side
+  protected-path guard. What the row buys is that the debt is visible at the
+  terminal rather than discovered when a pull request fails. It reads the
+  enumerated directories (`.`, `.github/workflows/`, `docs/`, `design/`) plus
+  every path the policy's `protected_paths` names, keeps only what classifies
+  `policy.edit` or a `policy.edit.*` sub-class, and reports a file whose current
+  bytes ARE signed off as ratified rather than pending. The `fix` is
+  `approval policy attest --path <p> --as human:<id>`, to be run after reading
+  the file; a marker whose text was later granted through the gate should lose
+  the suffix instead.
+- **sender-mapping** — which approvers a channel whose senders the policy maps
+  can still recognize (APRV-324). A SKIP where no approver declares a `senders`
+  block, which is every installation before the key existed: decisions are
+  recorded against the identity the deciding process was launched with, no
+  channel enforces a mapping, and nothing is wrong. A FAIL where the policy
+  maps senders for a channel and lists an approver on that channel with no id
+  of their own there — that person's next tap is refused `sender-unmapped` and
+  nothing is recorded, so the file says they may decide on a surface where they
+  cannot. A PASS where every approver a mapped channel reaches carries an id
+  there. The `fix` is `approval policy amend`, which owns the edit and the
+  re-attestation it costs. The row reads the policy and nothing else: no log,
+  no network, no credential, and it prints nobody's account id — the mapping is
+  in a file the operator can open, and a health row is read over shoulders.
+- **codex-auto-reviewer** — has anything other than this gate answered a
+  question this gate exists to ask (APRV-378)? It reads
+  `audit.question_preempted` and nothing else. A FAIL where one landed in the
+  last 24 hours, naming the source, the question in the other party's terms and
+  their verdict; a PASS where none did, mentioning any older ones; a SKIP where
+  the chain did not verify. A PASS says the log holds no such record and NOT
+  that a harness auto-reviewer is off: whether it runs is configuration this
+  runtime cannot read, and a row written against a guessed configuration key
+  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.
+
+
 
 **`--json`** (one object on stdout):
 
@@ -2650,8 +3487,9 @@ reaches this backlog. A `supervised-live` class puts a declared `live_rate`
 fraction of its actions through the human gate BEFORE they run; those are
 ordinary manual requests with ordinary grants and tokens, a person has already
 answered them, and they are not drawn a second time for retrospective review. A
-`supervised-retro` class — and the bare `supervised`, which is now an alias for
-it — is what this page is about. `approval policy check` names the mode in its
+`supervised-retro` class — and the bare `supervised`, which is now a deprecated
+alias for it, still parsed and removed in a future schema version (APRV-335) —
+is what this page is about. `approval policy check` names the mode in its
 final line and in `outcome.supervision`.
 
 Supervised actions execute immediately and are audited afterwards. The daemon
@@ -3291,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
@@ -3501,6 +4349,64 @@ leaves the sample exactly where it was: open, listed by `approval audit list`,
 and reviewable with `approval audit review <seq>`. Nothing in this channel can
 empty the backlog, which is the property a sampled-audit backlog exists to have.
 
+**A refused gesture leaves a record (APRV-355).** When the policy maps senders,
+a checkpoint signature or a review from an account the attested policy names
+nobody for is refused before any verb runs, and since this change the attempt is
+recorded: one **`audit.gesture_refused`**, with a `system:gate` actor, the
+channel, and a payload carrying `gesture`
+(`checkpoint-signature`, `review`, `review-note`), `code`
+(`sender-unmapped`, `sender-ambiguous`, `sender-key-unavailable`,
+`policy-not-attested`), the refusal
+`message`, the observed `sender`, and `actor` only where the runtime could name
+a person. Under a keyed mapping (APRV-370) the `sender.id` is the digest rather
+than the account, and `sender.hashed` is `true` beside it.
+
+```
+{"event":"audit.gesture_refused","actor":"system:gate","channel":"telegram",
+ "payload":{"gesture":"checkpoint-signature","code":"sender-unmapped",
+ "sender":{"channel":"telegram","id":"5551234567"},"message":"…"}}
+```
+
+It exists because the only refusal record before it,
+`audit.decision_refused`, requires an `action_key` and a `decision` of grant,
+reject or revoke, and a signature or a review has neither; writing one there
+would mean inventing both. The record is audit tier in the strict sense: it
+authorizes nothing, settles no request, charges no budget, is not sampled, and
+no enforcement path reads it. `approval log tail` and `approval log export`
+show it like any other record. Nothing about the refusal itself changed — no
+signature is appended and no review is recorded — and a listener whose policy
+maps no senders never reaches this path at all.
+
+**A question answered by something other than the gate leaves a record
+(APRV-378).** Codex's app-server can resolve an approval with a model call
+before `approval codex bridge` is asked, and disclose it afterwards through an
+`item/autoApprovalReview` notification. The bridge stops the session on one
+(`bridge-auto-reviewer-active`), and it appends exactly one
+**`audit.question_preempted`** first, through the same append path as every
+other record:
+
+```
+{"event":"audit.question_preempted","actor":"system:gate",
+ "payload":{"source":"codex-auto-reviewer","verdict":"accept",
+ "question":{"id":"item_01H9","method":"item/autoApprovalReview/completed",
+ "thread":"thread_7f2","turn":"turn_3"}}}
+```
+
+`source` is a closed set naming who answered, so the next system that does this
+gains a member rather than a type. `question` is the other party's own
+identifiers, because a record about their decision has to name it in their terms
+or a reader cannot go and find it on their side. `verdict` is their word
+verbatim and is ABSENT when the disclosure stated none: a record that said
+`accept` by default would be this runtime inventing somebody else's decision.
+
+The record is audit tier in the strict sense: it authorizes nothing, settles no
+request, charges no budget, is not sampled, and no enforcement path reads it.
+`approval log tail` and `approval log export` show it like any other record, and
+`approval doctor`'s `codex-auto-reviewer` row reads it: fail when one landed in
+the last 24 hours, pass otherwise, and a pass says the log holds no such record
+rather than that any auto-reviewer is off. Nothing on this machine can say the
+latter, which is why the bridge probes (APRV-364) instead of reading a setting.
+
 **A settled request stops looking live.** Every terminal state the listener
 observes for a message it sent edits that message: the text becomes the outcome
 (`✓ APPROVED`, `✗ REJECTED`, `✗ REVOKED`, `✗ EXPIRED`, `WITHDRAWN`) with the
@@ -3542,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
@@ -3555,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
@@ -3605,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.
@@ -3647,6 +4991,95 @@ A HUMAN commits those files: they are `policy.edit`. `docs/agent-sdk-hook.md`
 is the third caller: a Python Agent SDK application has no settings file, so it
 spawns this same verb from a hook callback (APRV-242).
 
+**`hook grok` is the one exception to the exit codes above (APRV-243).** Grok
+Build reads exit 2 as the deny and exit 0 as the allow, whatever stdout said,
+so on that harness alone a deny is exit 2 with `{"decision":"deny","reason":…}`
+on stdout, and the post-execution event exits 0 in every case rather than
+using 2 for visibility. Its envelope is camelCase (`toolName`, `toolInput`,
+`sessionId`, `hookEventName`, plus a `workspaceRoot` this runtime ignores in
+favour of `cwd`); snake_case is still read and wins when both spellings are
+present. `approval hook grok --help` prints the `.grok/hooks/pre-tool-use.json`
+the human commits, and that entry's own `timeout` must exceed `--timeout`.
+Grok Build FAILS OPEN on hook timeout, crash and malformed output, with no
+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
@@ -3679,8 +5112,42 @@ gate.self          the "approval" CLI itself is pass-through
 Bash (Claude Code) and Shell (Cursor) commands are classified into SPEC.md §7
 action classes. A `git push` that names `refs/tags/*`, a bare `v`-prefixed
 semantic-version-shaped tag, `tag <name>`, `--tags`, or `--follow-tags` is
-`release.publish`; force and mirror pushes remain `vcs.history.rewrite`, and
-ordinary branch pushes retain their branch or trunk class. Claude file tools
+`release.publish`; force and mirror pushes remain `vcs.history.rewrite`; a push
+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.
+
+`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*`,
@@ -3698,13 +5165,27 @@ its own flags are not parsed as this verb's.
   no human is asked. This union's spelling of the gate's `class-human-only`,
   which the detail names in full. The opposite repair to `hook-unclassified`:
   that one says declare a class, this one says a person runs the command.
+- `hook-harness-launch-unruled` — some class of the command is in the
+  `harness.launch.*` family and this policy names no rule for it (APRV-354).
+  The family resolves only under an explicit rule, `harness.launch.*` or
+  `harness.launch.NAME`, and never under `defaults.autonomy`, because a grant
+  of the class covers the launch and nothing the launched session then does.
+  Distinct from `hook-unclassified` (the classifier had nothing to say; here it
+  was clear and the policy is silent) and from `hook-class-human-only` (the
+  policy has spoken and reserved the class; the repair there is for a person to
+  run the command, and here it is to write a line).
 - `hook-opaque` — a construct whose effect cannot be read from the text
-  (`bash -c`, `eval`, backticks, a non-read substitution).
+  (`eval`, `xargs`, backticks, a non-read substitution). A login shell around
+  ONE inline script is classified by that script since APRV-380, so
+  `zsh -lc 'git push origin main'` is `vcs.push.main`; a script file, an extra
+  word, a redirection on the wrapper, an assignment prefix and a nested shell
+  all stay opaque.
 - `hook-unparseable` — the command line could not be tokenized.
 - `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.
@@ -3778,8 +5259,10 @@ importer collects the bullets under those headings into a second draft fence,
 ` ```yaml approval-values ` (SPEC.md §5.3), printed after the policy draft on
 stdout and written after it with `--out`; `--json` carries it as
 `values_draft`, or `null` when no such heading exists. Every bullet lands in
-`wants` and none in `love`, `like` or `dislike`: grading is the human's act,
-and an importer that guessed a grade would be putting words in their mouth. A
+`like`, the middle grade, and none in `love` or `dislike`: how strongly a line
+is meant is the human's to say, and an importer that reached for the strongest
+grade would be putting words in their mouth. (`like` is where what an operator
+asks for lives since APRV-336 folded `wants` into it.) A
 bullet over the schema's 200 characters is truncated with a warning rather than
 dropped, and bullets past the twentieth are kept as comments inside the fence,
 which is the same stance the permissions half takes on unmapped bullets. The
@@ -3911,6 +5394,19 @@ in the file said what the operator wanted the work to be like. The optional
 ` ```yaml approval-values ` block (SPEC.md §5.3) is that, and this verb prints
 it.
 
+**The keys.** `version`, the quoted string `"0.2"` and the only required one;
+the standing grades `love`, `like` and `dislike`, printed as `loves:`, `likes:`
+and `dislikes:`; and `communication`, one sentence or two on how the operator
+reads and answers, printed under `communication:`. APRV-336 settled that shape:
+a `wants` list for what the operator asks of an agent folded into `like`, since
+a request about behaviour and a preference about the output are graded by the
+same person in the same way and one list is easier to keep true, and `responds`
+became `communication`, which no longer reads as a sibling of `approval
+feedback`. A block written to the earlier format (`version: 1`, a `wants` list)
+is refused with the code `version-unsupported` and a message naming both edits,
+rather than with a schema violation a reader has to decode. The same code
+answers `version: 0.2` written without quotes, which YAML reads as a float.
+
 **It is guidance, and it is never policy.** Every output form opens with the
 banner saying so, `--json` carries the same sentence in `note`, and the reason
 is the same discipline `journal read` applies in the opposite direction: a
@@ -4055,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
@@ -4191,7 +5738,22 @@ the clock starts when the daemon starts), and at a clean shutdown when records
 are still owed. Every attempt goes through the gate as `agent:daemon`: the cycle
 registers, requests, and proceeds only where the policy lets it, so a
 `supervised-live` draw that selects the advance, or a class that resolves
-`manual`, stops it with nothing committed and the question in the queue. A gated
+`manual`, stops it with nothing committed and the question in the queue.
+
+**Which class it asks under, and which actor may advance autonomously
+(APRV-382).** Two classes, and the running process picks between them.
+`log.advance.daemon` is the daemon's own, asked only by the cadence advance
+inside `approval daemon run` and `approval up`; `log.advance` is what every
+other actor asks under, a session in a worktree and a human terminal alike. A
+policy may hold the daemon's class `autonomous` (this repository's does, since
+the advance publishes records the log already holds, appends nothing and decides
+nothing) while leaving the base class where it was. Nothing an agent can type
+reaches the looser line: `approval log advance` classifies `log.advance`
+whoever runs it. The choice is read from the process rather than from any
+argument, a policy that declares no rule for the daemon's class leaves the
+cadence gated exactly as it was, and a cycle that is NOT the daemon's whose
+class resolves `autonomous` is refused `advance-actor-not-daemon` before
+anything is appended. A gated
 or failed attempt is an `advance` line plus an `advance-refused` warning, and the
 next tick tries again — the cadence interval is the retry bound, so a refusal
 never loops. One records branch and ONE PULL REQUEST PER DAY: the first advance
@@ -4295,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`
@@ -4414,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
@@ -4440,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
@@ -4483,6 +6123,46 @@ Stop `up` before running Telegram setup or a standalone listener for its bot.
 One bot must have one polling runtime. After setup changes, reload the instance
 environment before starting `up` again.
 
+**Two refusals keep one bot to one instance (APRV-390).** Both are made before
+the daemon's first tick and before the first poll, and both exit 1 with a
+machine-readable code on stderr:
+
+| code | what it means |
+| --- | --- |
+| `cross-instance-credential` | A credential variable holds a value this instance did not configure: an `.approval/env` line naming another instance's keystore item, or an export whose value is not what this instance's file resolves to today. The message carries the `unset` line that fixes it. |
+| `bot-owned-elsewhere` | One `getMe`, before any `getUpdates`, named a bot another instance on this machine has already claimed. The message names that instance's directory. |
+
+`--allow-cross-instance` overrides both, starts, and prints on every run what it
+is overriding. Until APRV-390 the first of these was a warning printed on the
+way past a runtime that had already started, which is how a demo gate spent an
+evening polling the primary's bot.
+
+The first refusal COMPARES VALUES rather than only reading names, because it is
+the one check that is about to use the value. That closes the case names cannot
+see: `approval env` never overrides a variable this shell has already exported,
+so a token re-stored in the keystore does not reach a terminal holding the old
+one, and the daemon answers 401 while the same line read by hand passes `getMe`.
+It also removes a false positive — an export whose value IS what the file
+resolves to is correct however it got there, so the documented `eval "$(approval
+env)"` is not a finding. `approval doctor` keeps the name-only rule; a
+diagnostic may not block on a keystore-unlock dialog. No value is printed on any
+path.
+
+The `getMe` result is recorded against the instance in
+`.approval/channel-owner.json` (gitignored) and in a per-machine registry under
+the platform's user state directory, `approval/bots.json`. `APPROVAL_STATE_DIR`
+relocates that registry. A bot is identified by its id AND its Bot API base,
+because an id is unique within one deployment and nothing more: two gates
+pointed at two different `--api-base` values hold two different bots and neither
+refuses the other. Neither file is evidence, nothing reads them to widen a
+permission, and losing them costs one `getMe`. An unreachable Bot API is not a
+refusal: it says so and starts, because a captive portal is also a `getUpdates`
+that cannot conflict with anything.
+
+A 409 that still happens at runtime — another machine, or a poller started
+outside this runtime — is reported once, with the instances the registry knows
+about, and its repeats are counted rather than reprinted.
+
 **The ambient runtime: the daemon loop and every configured channel in one
 supervised foreground process.** `approval daemon run --with-channels` is the
 same verb spelled from the other side, and it reaches the same function before
@@ -4505,13 +6185,15 @@ because `git status` does not say what the upstream range changed. So the verb
 does all four, and `approval daemon run` runs the identical preflight from the
 identical module, printing the identical two lines.
 
-It is allowed exactly three writes: a `--ff-only` merge, `npm run build`, and
+It is allowed exactly four writes: a `--ff-only` merge, `npm run build`,
 clearing an untracked `backlog/tasks/` file the incoming commit already contains
-out of the merge's way (APRV-300, described below). It
+out of the merge's way (APRV-300, described below), and the reconcile `approval
+log sync` performs on its behalf (APRV-346, described below). It
 never resets, never stashes, never checks anything out, and never touches the
-working log. That list is not caution for its own sake: a working `events.jsonl`
-rewound through git underneath a live appender is fork 2 of 2026-08-20, the
-incident `approval log sync` exists to prevent.
+working log itself. That list is not caution for its own sake: a working
+`events.jsonl` rewound through git underneath a live appender is fork 2 of
+2026-08-20, the incident `approval log sync` exists to prevent, which is why the
+one write that does move that file is made by that verb and by nothing here.
 
 **Safe** means both of: this checkout is not AHEAD of the remote, and no path the
 upstream range changes is locally modified. When it is safe, the preflight
@@ -4521,11 +6203,45 @@ running. When it is not, it refuses, and changes nothing:
 | code | fires when | next |
 |---|---|---|
 | `up-preflight-behind-ahead` | `origin/<branch>..HEAD` is non-empty: this checkout carries commits the remote has never seen. A fast-forward is not the operation for that state, and choosing a side is a decision. | look at them (`git log --oneline origin/main..HEAD`), then push them or `git reset --keep` |
-| `up-preflight-log-diverged` | the upstream range rewrites `.approval/log/events.jsonl` or `.approval/QUEUE.md`, and this working copy has uncommitted changes to one of them. The judgment a human could not make by eye. | `approval log sync` |
+| `up-preflight-log-diverged` | the upstream range rewrites `.approval/log/events.jsonl` or `.approval/QUEUE.md`, this working copy has uncommitted changes to one of them, and the two chains are **not** in a prefix relationship (or cannot be compared at all). The judgment a human could not make by eye. A working log that merely extends the committed one is reconciled instead, see below. | `approval log sync` |
 | `up-preflight-dirty-protected` | some other path the upstream range changes is locally modified, so `git merge --ff-only` would refuse rather than overwrite it. | look at the diff, or `approval up --no-preflight` |
 | `up-preflight-task-file-conflict` | an untracked file under `backlog/tasks/` stopped the fast-forward and it holds lines the incoming copy does not. Which version is wanted is a question, and no verb here will pick. | read the two copies, move yours aside, run `approval up` again |
 | `up-preflight-failed` | a write the preflight attempted did not complete: the fast-forward, or the rebuild. Not a judgment, so it is not in the union above; the message names the step, and for a build it names the exit code `npm run build` came back with. | `npm run build` to see the whole error, or `approval up --no-build` if you mean to run the stale one |
 
+**A working log that merely extends the committed one is reconciled, not
+refused (APRV-346).** Every records advance moves `origin/main`'s
+`.approval/log/events.jsonl` while the hook keeps appending locally, so
+"upstream changed the log and so did this working copy" is the normal state of
+the primary checkout after a merge. Refusing it sent the operator to `approval
+log sync` and then back to `approval up`, every time. So the collision is a
+question now: `core/log-reconcile.ts` — the same comparison `log sync` and
+doctor's `log-drift` row use — is asked how the working chain stands to the
+committed chain at the fetched tip, and:
+
+- **`ahead`, `behind` or `equal`** — one chain contains the other whole, so
+  adopting the longer one extends and rewinds nothing. The preflight calls
+  `approval log sync` itself, which holds the append lock for its whole ceremony
+  (snapshot, baseline, fast-forward, reconcile, rebuild the projections,
+  post-verify), and prints one line: `synced: fast-forwarded to origin/main
+  <sha>, kept K local records`. The `--json` stream carries it as a
+  `preflight_sync` event and the `preflight` line's `log_synced` reads true.
+  Nothing here reimplements any of that ceremony; it supplies a caller for it;
+- **`diverged`** — two appenders built different records on one predecessor.
+  Hash chains do not merge, so this is the `up-preflight-log-diverged` refusal
+  above, unchanged, and it is now the **only** case that needs a hand-run
+  `approval log sync` (which will tell you the same thing, at more length).
+
+Four conditions have to hold before the reconcile is even offered, and each of
+them answers "refuse" rather than "probably fine": the log is the repository's
+own `.approval/log/events.jsonl` (not some other file named with `--log`), no
+*other* path the upstream range touches is locally modified, both chains verify
+clean, and the relation is a prefix one. A `log sync` that refuses anyway — an
+appender that took the lock first (`log-sync-locked`), a fork that landed
+between the read and the ceremony, a git failure — comes back as the same
+`up-preflight-log-diverged` refusal with the sync's own code and sentence in
+YOUR STATE. Nothing starts, and the working log is exactly as `log sync` found
+it.
+
 **An untracked task file no longer stops it (APRV-300).** A lane files
 `backlog/tasks/aprv-299` on its branch and its pull request merges, while the
 primary checkout holds the same path untracked from its own `backlog task
@@ -5342,6 +7058,51 @@ disables it whenever the policy names no variable, and this verb does not edit a
 attested policy file. It prints the block to add and the `approval policy amend`
 ceremony that attests it.
 
+## setup sender-key
+
+The operator-held key that turns a channel account id into the value an
+`approvers[id].senders` mapping carries (APRV-370). It exists for the deployment
+that PUBLISHES its policy and its log, where the raw account id is disclosed
+once in the file and then on every decision.
+
+A plain unkeyed digest would not fix that. A Telegram account id is a ten-digit
+decimal number, the whole space is enumerable on a laptop, and a digest anybody
+can reverse states a privacy property it does not have. So the mapping value is
+`hmac-sha256:<hex>`, computed under this key, which is in the environment and
+never in the policy file.
+
+Bare, the verb mints, stores and records the key, exactly as `setup sampling`
+does with its secret, and edits no policy file. The value is not printed and
+there is no verb that prints it.
+
+With `--id <account-id>` it mints nothing and stores nothing. It reads the key
+from the environment, prints the `hmac-sha256:<hex>` for that account, and
+prints the `senders` line and a paste-ready proposal pair around it. That is the
+one thing an agent writing a policy proposal cannot do — the digest depends on a
+secret only the operator's machine holds — so the proposal page says to run it
+rather than carrying a placeholder:
+
+```sh
+approval setup sender-key           # once, interactive, human-only
+eval "$(approval env)"
+approval setup sender-key --id 7345216485
+```
+
+Because it stores nothing and prints a value designed to be published, `--id` is
+the one `setup` path that runs without a terminal and accepts `--json`.
+
+**The key is not an authenticator.** Nothing about the gate's safety rests on
+its secrecy: somebody who learns it learns which account ids a policy names,
+which is what the raw form told everybody. What it buys is that the published
+policy and the published log stop carrying the account.
+
+**A listener that holds no key under a keyed mapping decides nothing** on that
+channel. Every tap is refused `sender-key-unavailable`, and there is no fallback
+to comparing the observed id against the raw entries: without the key the
+runtime cannot tell whether the account is also claimed by a keyed approver, so
+it cannot run the ambiguity check the mapping rests on. `approval doctor`'s
+`sender-mapping` row names the form in use and says whether the key resolves.
+
 ## setup checkpoint
 
 Mints the Ed25519 keypair a human signs the log's head with (APRV-220's record,
@@ -5418,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.
@@ -5551,6 +7320,28 @@ a `human:<id>` and an `agent:` or `system:` actor is refused at exit 2. Exit 1
 means the far end refused: an invalid token, a 409 from a running listener, or no
 message reaching the bot before the deadline.
 
+**One bot per instance (APRV-390), and both names are derived.** The keystore
+item this verb creates is `approval-tg-token-<instance id>`, where the instance
+id is the eight hex digits `approval doctor` prints in its `keychain-scope` row,
+so two gates on one machine store two items. An operator who prefers a readable
+suffix may write their own name into `.approval/env` instead; nothing is
+migrated and `approval env --check` reports which item each variable resolves
+through. The variable is whatever the policy's
+`channels.telegram.token_env` declares; a policy that declares nothing gets
+`APPROVAL_TG_TOKEN`, which every other silent policy on the machine also gets,
+so a second gate on one machine declares a pair of its own (the packaged demo
+policy declares `APPROVAL_DEMO_TG_TOKEN` and `APPROVAL_DEMO_TG_CHAT`).
+
+The `getMe` that proves the token also says which bot it is, and this verb
+records that against the instance in `.approval/channel-owner.json` (gitignored)
+and in a per-machine registry under the platform's user state directory,
+`approval/bots.json`. A bot another local instance has already claimed is
+refused before anything is written, naming that instance's directory; the values
+are open names and never a token. `--allow-cross-instance` records this instance
+as an owner anyway and says what it is doing. An instance set up before this
+existed keeps working: nothing is migrated, and the first `approval up` or
+listener start writes the record from its own `getMe`.
+
 ## setup service
 
 **It writes one file: the launchd user agent or the systemd user unit that runs
@@ -5696,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
@@ -5710,7 +7937,270 @@ the broker and runner present? POSIX ownership does not establish ACL custody,
 so this slice executes no manifest-selected binary and reports runtime versions
 unchecked. Unknown evidence is a refusal.
 
-The first slice deliberately makes start and serve return codex-not-ready. An
+The first slice deliberately made start and serve return codex-not-ready. An
 npm install, generated config, or passing bundle check does not create a
 mandatory boundary. The whole approval codex family is operator-only and absent
 from the ordinary broad MCP catalog.
+
+### The workspace broker (APRV-325.2)
+
+approval codex apply is the executable half. It takes an instance manifest and a
+proposal file, and the split between them is the design: the manifest supplies
+the acting identity (agent:codex-<instance_id>), the workspace root, the policy
+file and the log, and the proposal supplies operations and the SHA-256 of the
+policy it was built against. A proposal naming anything else, an actor, a root,
+a class, a token, a sandbox posture, is refused input-invalid rather than having
+the extra key ignored, because a caller that wrote one meant something by it.
+
+The order of one apply, and why each step is where it is:
+
+1. Read the log under chain verification, read the policy once, hash those exact
+   bytes, and check them against the latest attestation. An unattested or
+   drifted policy refuses here, before a plan exists.
+2. Compare the caller's expected digest. A mismatch is attestation-drift: the
+   proposal was built against a policy nobody is enforcing.
+3. Plan through src/codex/workspace-plan.ts, which does the path work: traversal,
+   symlinks, hardlinks, case aliases, missing sources, existing destinations,
+   preimage digests, and human-only classes refused before any preimage is read.
+4. Register one action per distinct path class under a task id derived from the
+   payload hash. Classes are never collapsed: the class is what the operator's
+   roster, budget and autonomy are keyed to.
+5. Authorize every leg. A leg the policy sends to a human refuses
+   approval-required and names the action keys to grant; nothing is written, and
+   the same proposal applies once a person has decided.
+6. Start every leg before any byte moves. A later leg refusing to start closes
+   the earlier ones execution.failed and leaves the workspace untouched by
+   construction rather than by cleanup.
+7. Take the workspace lock, then revalidate the plan under it. A revalidation
+   that precedes the lock proves only what was true before another writer could
+   act.
+8. Stage the new bytes and the preimages on the same filesystem, fsync them,
+   write a journal naming the before-state and the after-state, fsync that, and
+   only then apply.
+9. Read the workspace back. All-after completes every leg, all-before fails every
+   leg, and anything else, a partial apply, a failed rollback, an endpoint that
+   cannot be read, records execution.indeterminate with the reason
+   workspace-commit-unknown on every leg and retains the journal and the lock.
+
+approval codex recover reads that retained journal and reports before, after or
+mixed. It repairs nothing, and the restraint is the point: rolling a mixed
+workspace forward would guess which half the human approved, and rolling it back
+would delete the half that committed. Exit 1 means mixed. The resolution is a
+person's, through approval execution reconcile.
+
+Custody is claimed only as far as the platform proves it. The broker takes an
+O_CREAT|O_EXCL lock, which excludes other cooperating brokers and nothing else,
+and then asks POSIX ownership and mode whether any other principal can write the
+directories it is about to touch. It reports os-exclusive only when both hold and
+advisory otherwise, and it always reports acl-unproven, because ownership and
+mode say nothing about ACLs. --require-exclusive-custody turns the weak answer
+into a refusal rather than a footnote.
+
+approval codex serve publishes that broker over stdio as exactly one MCP tool,
+codex_workspace_apply, checked at call time as well as at list time. It is a
+different server from approval mcp serve, whose catalog is the whole verb
+registry and therefore grows: a constrained session has to reach one door, and
+the same door next month.
+
+### The confined session (APRV-325.3)
+
+approval codex start prepares the room a session's shell runs in. With no
+-- <command> it reports the room and runs nothing, which is what an operator
+checking a host should not have to start Codex to learn. With one, it runs that
+command inside the room and exits with the child's own code.
+
+The shell gets a disposable workspace under the system temporary directory, and
+that workspace is the only path it may write. The canonical workspace is
+readable and never writable. Reads are jailed to exactly those two roots
+(APRV-347), so the gate home, other repositories and everything else the
+operator's home holds are unreadable whether or not anyone thought to name them,
+and the credential denials are emitted after the jail's allows so they remain
+the last word on the vault, the environment map and the sealing keys. The
+environment is an allow-list rather than a filtered copy of the operator's, so a
+provider key nobody taught this runtime about is absent rather than forgotten.
+Outbound network is denied, loopback included. Descendants inherit all of it,
+which is the property that matters: a session does not write files by calling
+into this runtime, it spawns shells that do.
+
+There is no opt-out flag and no unwrapped fallback. approval run has
+--no-sandbox because a human's grant over exact bytes is authority to reach the
+world; a confined session has no such authority to present, so a host with no
+sandbox mechanism refuses (sandbox-unsupported) where approval run would record
+unsupported and proceed. A command that cannot be resolved on the session PATH is
+refused rather than spawned outside the room.
+
+The disposable workspace is removed when the session ends, so a replay of the
+same shell work starts from an empty room. Only a brokered change survives it,
+which is the whole arrangement: the shell cannot reach the canonical workspace,
+and approval codex apply is how a change that a policy admitted does.
+
+### The app-server bridge (APRV-361)
+
+```
+approval codex bridge --prompt <text> [--workspace <dir>] [-- <server command>]
+```
+
+approval codex bridge starts `codex app-server` and answers every approval
+request it raises through the policy and the log. Each
+`item/commandExecution/requestApproval` carries `command` and `cwd` on the same
+frame, minted by the harness runtime, and those two fields are exactly the pair
+the native hook lacks: a Codex `Bash` pre-event names only the command, so
+`approval hook codex` refuses every shell call as
+`hook-unsupported-execution-context` rather than bind bytes whose directory it
+does not know. Here the directory arrives with the question.
+
+It reuses the hook's decision path rather than a copy of it. The request becomes
+the hook's own input (tool `Bash`, `tool_input.command` the string the server
+sent, `cwd` the directory it named) and goes through the same classifier, the
+same human-only refusal, the same sandbox requirement, the same loop floor and
+unattended guard, and the same register, request and wait against the verified
+view. What differs is where the answer goes: `{id, result: {decision}}` on the
+connection instead of a decision object on stdout.
+
+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. 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
+`acceptWithExecpolicyAmendment` is not read as an accept. It never sends
+`acceptForSession` (standing authority for a whole session is a grant shape this
+project does not have), `cancel` or `abort` (those mean "stop the turn", and
+sending one would record an interruption as a denial). A request advertising
+nothing gets `accept` or `decline` and the report says the word was this
+runtime's own.
+
+The vocabulary is eight spellings of those two words (`accept`, `approved`,
+`approve`, `allow`; `decline`, `denied`, `deny`, `reject`), and since APRV-367
+it is a type rather than a convention: the reply value cannot be constructed
+outside the list, one function turns a decision into bytes and re-checks
+membership there, and a word that somehow failed that check would be sent as a
+decline, since the only safe substitute for a word you cannot name is no. The
+match is case-insensitive, and what goes on the wire is this runtime's own
+spelling of the matched word. The `bridge-decisions` conformance suite pins the
+behaviour for a second implementation.
+
+Its own refusals, beside the gate's:
+
+```
+bridge-request-unbound       no command, no cwd, or no call identity on the request
+bridge-command-unbound       a command string that names no argv this client can bind (APRV-362)
+bridge-file-change-unbound   an item-based file change whose content this client cannot
+                             produce from the item/started frame its item id names: no such
+                             frame, an item that is not a fileChange, an empty change set, or
+                             a frame belonging to another thread or turn (APRV-379)
+bridge-file-change-already-completed
+                             item/completed for that item arrived before the question, so the
+                             change had finished before this client was asked (APRV-379)
+bridge-unknown-request       a server request this client has no reading for
+```
+
+The **item-based file change is correlated, not guessed** (APRV-379). That API
+puts the content on an earlier `item/started` notification and the approval
+request refers to it by `itemId`, so the bridge keeps every item the thread
+announces and decides the request against the frame that id names: the paths
+take their classes, the payload binds the change set verbatim with
+`content_sha256` over it as received, and nothing parses the `diff`. The request
+carries no directory, so the paths resolve against the workspace the bridge
+named on `thread/start`, and one landing outside it is refused `hook-io`.
+
+The **exec request binds words, not a rendering** (APRV-362). The item-based API
+delivers the command as one string, joined from the argv Codex will run, so the
+bridge un-joins it and the registered payload carries the string that arrived
+and the argv beside it. A string that is not readable as a join (an unterminated
+quote, a double quote outside a quoted run, a trailing backslash, or separation
+no join produces) is `bridge-command-unbound`, because approving it would
+approve this client's own re-parse. Byte equality with a re-rendering is
+deliberately not required: a join written for shell safety quotes more than this
+one does, and demanding equality would refuse ordinary traffic over a quoting
+rule nothing here records. A legacy argv array is rendered word by word rather
+than concatenated, so `["bash", "-lc", "rm -rf build"]` reaches the classifier
+as `bash -lc 'rm -rf build'` and not as five separate words.
+
+A **legacy `applyPatchApproval` is decided rather than declined** (APRV-363).
+Its `fileChanges` map rides on the request, so there is nothing to correlate and
+nothing is re-rendered: the change is classified by the paths it names, through
+the same protected-path rules every other file tool uses, and the registered
+payload carries those paths, the change verbatim and `content_sha256` over the
+map as it arrived. A path that is absolute, or that resolves outside the
+directory the server named, is refused `hook-io`; a request with a map and no
+directory (`cwd` or `grantRoot`) is `bridge-request-unbound`. The item-based
+`item/fileChange/requestApproval`, which carries an identifier and no content,
+stays declined.
+
+The thread is started with `approvalPolicy: untrusted` and `sandbox: read-only`.
+`untrusted` is the wire spelling of the source's `UnlessTrusted`, the only
+variant under which every command asks, and the server refuses the source name.
+There is no flag for it: a session gating an unknown fraction of itself is what
+the pin exists to prevent (APRV-366).
+
+The pin is checked as well as sent, and a failure ends the run rather than
+declining one request:
+
+```
+bridge-thread-start-refused       the server refused thread/start, so no thread
+                                  exists and no policy was established; its own
+                                  error is carried verbatim
+bridge-approval-policy-mismatch   the server reported an effective approval
+                                  policy that is not untrusted
+```
+
+A server that reports no policy at all is run against, because the observed
+0.155.0 server echoes none and a client demanding an echo could not start. The
+report says which case it was: `thread.requested` is what went on the wire,
+`thread.effective` is what the server said, and `thread.confirmed` names where
+the claim comes from: `unconfirmed`, `reported` (a frame echoed the pin back)
+or `observed` (a probe command produced an approval request that reached this
+client). Both stops exit 4, as every other protocol stop in this verb does; the
+code in the report is the part to branch on.
+
+**A preflight probe runs before every turn** (APRV-364). Codex's auto-reviewer
+can resolve an approval with a model call before this client is asked, and
+nothing in the protocol reports whether it is running, so the bridge watches one
+command instead of reading a setting. Each start asks a preflight turn for
+`true` and nothing else, before the operator's prompt, with no flag to skip it;
+it costs one turn per start. The probe's own request is declined immediately as
+an observation and never reaches the gate, so nothing is registered for it and
+no approver is asked about it.
+
+```
+bridge-preflight-void             the preflight turn ran no command at all, so
+                                  nothing was established; the report carries
+                                  the turn's frames verbatim and nothing is
+                                  retried. Run the verb again
+bridge-auto-reviewer-active       an item/autoApprovalReview notification
+                                  arrived in either turn: something other than
+                                  this client answered a question
+```
+
+A probe that RAN without asking is `bridge-approval-policy-mismatch`, because a
+policy under which one command did not ask is not `untrusted` whatever the
+server reports about itself. A probe that was asked about lets the real turn
+run, and `thread.confirmed` becomes `observed`. That word is narrow on purpose:
+it says one question reached this client unanswered by anything else, and it is
+not a claim that the auto-reviewer is off. The report's `preflight` block
+carries the turn id, the command, the outcome (`asked`, `executed`, `void` or
+`pending`), the word sent, and, on a void, the frames.
+
+**It is an advisory checkpoint and not a boundary**, for reasons
+docs/codex-app-server-bridge.md states in full: Codex's auto-reviewer can
+resolve a question before this client sees it, and the approval policy and
+sandbox posture decide how many questions exist. An open gate window is not
+honoured here either, which is the strict direction. The claim it supports is
+"this client decided every question this app-server child asked in this
+session", and nothing wider.
+
+**Custody is the operating system's** (APRV-365). The server is started by this
+verb as its own child over stdio pipes: there is no socket, nothing binds a
+path, and no other process holds a descriptor to speak on, so the replay of a
+pending request to whatever connects next cannot arise inside one run. The
+scope of the claim is that child and that session; a Codex started outside this
+arrangement is a different process and nothing here observes it. The verb does
+not inspect the command after `--` for a shape that would attach to something
+already running instead: that would be a guess at another program's command
+line, and a check written against a guessed shape finds nothing while reporting
+that it looked.