approval-md 0.2.0 → 0.3.0

package/docs/cli-reference.md

@@ -390,6 +390,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 +492,12 @@ 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).
+
 `--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.
@@ -712,7 +725,21 @@ 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.
 
 ### `--organ <path>`: the gate's organs (APRV-272)
 
@@ -769,6 +796,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 +945,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 +1035,62 @@ 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
+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 +1132,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 +1227,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 +1293,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 +1325,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 +1366,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
@@ -1798,7 +2091,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 +2129,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.
@@ -2530,6 +2832,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
@@ -2573,7 +2892,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 +2948,57 @@ 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.
+
+
 
 **`--json`** (one object on stdout):
 
@@ -2650,8 +3027,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
@@ -3501,6 +3879,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
@@ -3647,6 +4083,20 @@ 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.
+
 **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 +4129,11 @@ 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. 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,8 +4151,21 @@ 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.
@@ -3778,8 +4244,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 +4379,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
@@ -4191,7 +4672,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
@@ -4483,6 +4979,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 +5041,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 +5059,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 +5914,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,
@@ -5551,6 +6168,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
@@ -5710,7 +6349,268 @@ 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.
+
+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.