approval-md 0.1.0 → 0.3.0

package/docs/cli-reference.md

@@ -14,6 +14,10 @@ a gate refusal is exit 1 and not 2, approval events are exclusive to the manual
 path, the raw token is shown once, a channel is transport — are stated once at
 the top of `approval --help` and are not repeated here.
 
+`approval --version`, `approval -v`, and `approval version` print the package
+version and exit 0. These aliases apply only at the top level; a version-looking
+flag after a verb remains that verb's argument.
+
 Each section below is what the corresponding `--help` points at with its
 `why: docs/cli-reference.md#…` footer.
 
@@ -35,11 +39,12 @@ resolved, and nothing is written.
 
 ## log
 
-The three subcommands open the log for reading only. `verify` walks the hash chain
+Four subcommands open the log for reading only. `verify` walks the hash chain
 end to end and reports clean | torn-tail | corrupt, `tail` prints the last N
-records (default 10), and `export` streams every stored line to stdout, byte for
-byte. The default log path is `.approval/log/events.jsonl`, relative to the
-working directory.
+records (default 10), `export` streams every stored line to stdout byte for
+byte, and `follow` emits verified records after an exclusive cursor before
+waiting for appends. The default log path is `.approval/log/events.jsonl`,
+relative to the working directory.
 
 ## log verify
 
@@ -297,6 +302,47 @@ that is due to a refusal of anything: it is a warning on `log verify`, a
 doctor`'s `checkpoint` row. A gate that held up an action for want of a tap is a
 gate whose operator turns the check off.
 
+## log follow
+
+`approval log follow --from <seq> --json` is the channel-independent decision
+listener. `--from` is exclusive and defaults to zero, so a new consumer first
+receives the entire verified log. Output is JSON Lines: one complete stored
+event object per line. It emits every event type in chain order; a refund or
+queue consumer selects the decisions relevant to its own work. The command then
+remains in the foreground and exits 0 on SIGINT, SIGTERM, or a closed downstream
+pipe. Signal cancellation may interrupt the final native stdout write. Consumers
+must process only newline-terminated JSON records, discard any incomplete final
+fragment, and reconnect from the cursor of the last complete record they
+processed.
+
+Filesystem notifications only prompt another read. On every notification wake
+and every bounded 500ms fallback poll, the runtime rereads and verifies the
+complete chain from genesis through the observed head, even when the log has not
+changed. It emits nothing from a corrupt, torn, unreadable, truncated, or
+cursor-mismatched snapshot. Pull backpressure means a slow consumer holds one
+verified snapshot and no growing notification or event queue. Each check costs
+O(N) verification time and O(N) snapshot memory for a log of N records. This
+bounded initial implementation is not an incremental, low-overhead tail.
+
+`--cursor-hash <64hex>` supplies the hash of record `--from`. Store both the
+sequence and hash outside the log and pass both on reconnect. That binding
+detects a truncated or replaced prefix. A sequence alone is a weaker bootstrap:
+an internally valid rewritten prefix with the same sequence numbers cannot be
+distinguished from the original, for the same reason an unanchored hash chain
+cannot detect a fully recomputed forgery.
+
+Delivery across reconnects is at least once. Apply the external effect first,
+then persist the emitted event's `seq` and `hash`; a crash between those steps
+replays the event. Consumers that require exactly-once external effects must
+make their own effect idempotent or transact it with cursor storage. Persisting
+the cursor before the effect instead risks silently losing that effect.
+
+The stream uses the existing exit classes: 1 for corrupt or mismatched cursor,
+2 for usage, 3 for a torn tail, and 4 for I/O. Its error object is written to
+stderr and no event from the refused batch is written to stdout. `log follow`
+is deliberately absent from MCP because one unbounded call would occupy the
+finite MCP call queue; run it as a separate CLI process.
+
 ## log tail
 
 The chain is verified first. On a torn tail the intact records are printed and the
@@ -344,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
@@ -439,6 +492,26 @@ 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.
+This is display credit only. It does not set an event actor, name an approver,
+grant authority, or derive an identity from the log. Omitting the flag preserves
+the existing commit message, pull request body, and merge command byte for byte.
+
+The merge queue ignored the custom auto-merge commit body observed on PR 378.
+For a queued merge commit to retain this credit, the repository must use GitHub's
+PR-body merge-message setting (`merge_commit_message=PR_BODY`); the package does
+not change repository settings. The PR body is therefore the durable source the
+queue can copy, rather than a claim that `gh pr merge --body` controls the final
+queued merge.
+
 **You do not fetch or reset first (APRV-203).** The verb owns its own git
 preconditions: it fetches the base branch (the one you are standing on, or
 `--base <name>`), builds the commit on `origin/<base>` in a scratch index rather
@@ -536,7 +609,8 @@ is not manual:
   policy was read and understood, and it says ask.
 - `irreversibility-floor` — policy granted autonomous or supervised and SPEC §7's
   floor overrode it because `--reversible false` was given. `overridden` records
-  what policy actually said.
+  what policy actually said. The floor remains the default when a class rule
+  omits `allow_irreversible` or writes `false`.
 - `load-failure` — the policy could not be loaded at all, so every class is
   manual. `loadFailure` carries a code and a message.
 
@@ -561,14 +635,26 @@ The exit codes, at length. `policy check|test` uses only 0, 2 and 4:
 key may contain, never something an agent can do.
 
 `--reversible` takes an explicit value because "unstated", "reversible" and
-"irreversible" are three different questions. Only the explicit `false` engages
-SPEC §7's irreversibility floor.
+"irreversible" are three different questions. Explicit `false` asks for the
+effective irreversible answer. It resolves to `manual` by default. A nonmanual
+class retains its autonomy only when every equally most-specific matching rule
+sets `allow_irreversible: true`. Lower-specificity rules do not vote, defaults
+cannot opt in, and neither this flag nor any other action metadata can create
+the permission. Manual remains manual and human-only remains human-only.
+
+For an allowed `supervised-live` class, the existing live sampler decides
+whether this action prompts before execution. Allowed `supervised` and
+`supervised-retro` actions execute first and remain eligible for retrospective
+review. Allowed autonomous actions proceed without either review path. Telegram
+appears only when the effective path actually requests approval through that
+channel; policy-authorized execution is never represented as a human grant.
 
 **`--json`** (one object on stdout):
 
 ```
 {"class":"vcs.push.main","reversible":null,
- "outcome":{"autonomy":"supervised","approvers":null,"limits":null},
+ "outcome":{"autonomy":"supervised","approvers":null,"limits":null,
+            "allowIrreversible":false},
  "provenance":"rule"|"default"|"inherited"|"fail-closed"|"floor",
  "manualBecause":null|"matched-rule"|"irreversibility-floor"|"load-failure",
  "loadFailure":null|{"code":"file-missing"|"no-block"|"multiple-blocks"|
@@ -576,6 +662,9 @@ SPEC §7's irreversibility floor.
                      "message":"..."},
  "matched":null|{"pattern":"vcs.push.main","rule":{"autonomy":"supervised"}},
  "overridden":null|{"pattern":"read.web"|null,"autonomy":"autonomous"},
+ "irreversibility":"not-applicable"|"policy-allowed"|"floor-applied"|
+                   "already-manual"|"human-only",
+ "irreversiblePatterns":["read.*"],
  "candidates":[{"pattern":"read.*","specificity":[1,1,2],
                 "autonomy":"autonomous","winner":true,
                 "tieBreak":"specificity"|"strictest-autonomy"|
@@ -636,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)
 
@@ -693,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
@@ -756,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
@@ -836,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
@@ -886,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
@@ -981,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.
@@ -1041,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",
@@ -1073,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.
@@ -1105,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
@@ -1155,6 +1524,13 @@ 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.
 
+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
+an extra human grant. The retained bytes let later audits match the execution
+record to the actual edit. Missing bindings, mismatched material or a storage
+failure refuse the request; an existing valid payload is preserved.
+
 **`--json`** (one object on stdout):
 
 ```
@@ -1715,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
@@ -1753,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.
@@ -2447,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
@@ -2490,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
@@ -2529,6 +2938,67 @@ The checks, at length:
   where there is nothing to commit a key to. Neither fix deletes nor commits:
   `git rm --cached` for a key already in the index is named in the prose and
   left to you, along with revoking every action whose token is still unspent.
+- **codex-hook-wiring** — whether this checkout's `.codex/hooks.json` carries
+  the reviewed approval.md profile for both `PreToolUse` and `PostToolUse`: the
+  exact `Bash|apply_patch` matcher, a direct synchronous `approval hook codex`
+  command, and a `600` second outer timeout. A PASS establishes only those JSON
+  bytes on disk. Codex trust, loading, and observed execution remain separate
+  facts checked through `/hooks` and the bounded smoke test. TOML-only hook
+  configuration, or JSON combined with `.codex/config.toml`, SKIPS because
+  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):
 
@@ -2557,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
@@ -2684,9 +3155,10 @@ and cannot do. It selects the SHAPE of an obligation that exists either way; it
 cannot remove one, delay one, or decide whether the denial happened. The only
 thing a false `reversible: true` buys is the shape whose discharge this runtime
 checks against the chain, which makes the claimant's own exit harder rather than
-easier. The same reading applies to the irreversibility floor that keeps a
-`reversible: false` action out of `supervised-retro` entirely: it is a floor, not
-a proof — it acts on the acting party's own claim, so it catches the honest
+easier. The same reading applies to the irreversibility floor. By default it
+keeps a `reversible: false` action out of `supervised-retro`; an attested class
+rule may explicitly accept that consequence with `allow_irreversible: true`.
+The field acts on the acting party's own claim, so it catches the honest
 declaration and never the lie. What answers the lie is writing `manual` for the
 class, which no declaration can loosen.
 
@@ -3192,6 +3664,11 @@ would put a bot token into a shell history or a process listing.
 
 ## channel telegram listen
 
+This starts the standalone Telegram component. For normal operation, use
+[`approval up`](#up), which also runs the daemon. Do not run this listener beside
+`up` or another listener polling the same bot, even for a different policy
+project: competing `getUpdates` calls produce Telegram HTTP 409.
+
 **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
@@ -3402,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
@@ -3456,6 +3991,43 @@ 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.
 
+## quickstart
+
+`approval quickstart [--dir <path>] [--api-base <url>]` is the human-only solo setup ceremony. It
+asks three decisions: the human identifier, terminal or Telegram, and which of
+five class families always ask. The default checklist selects `communicate.*`,
+`financial.*`, `files.delete.*`, `public.*`, and `vcs.push.main`.
+
+The command validates the complete generated policy before writing it. It
+creates the same log directory, queue projection, and gitignore entries as
+`init`, writes `APPROVAL_HUMAN` through the existing `.approval/env` writer,
+and uses the existing Telegram setup path when selected. A token therefore
+follows the OS-keystore or no-echo path already documented under [setup channel
+telegram](#setup-channel-telegram). It refuses before prompting when a policy or
+`.approval` instance state already exists, so it cannot silently reuse a log,
+queue, environment map, vault, or channel setup from another ceremony.
+
+Quickstart resolves this new instance's environment map explicitly, without
+borrowing ambient approval credentials, and runs a bounded doctor preflight.
+When `--api-base` is present, the same endpoint is used for Telegram setup and
+that preflight; a local or private Bot API selection never falls through to the
+public endpoint.
+The expected `attestation` failure is the only failed row accepted before the
+ceremony; any other failed row is printed and stops before attestation. It then
+prints the exact policy bytes and requires the operator to type `understood`.
+The append rechecks the live digest and refuses if the file changed after it was
+shown. An abort or failed step therefore leaves the generated policy unattested.
+The final `activate:` line includes `approval env --dir` with the absolute,
+shell-quoted target directory. It is required because no ordinary runtime
+command loads `.approval/env` implicitly, and it still names the right instance
+when the operator starts the next shell elsewhere.
+
+This verb classifies `policy.core` and is omitted from MCP. Piped stdin and
+`--json` exit 2 before any write and print the manual sequence. The generated
+`defaults.autonomy: autonomous` applies to other classified reversible actions.
+Protected controls, fail-closed policy loading, the irreversibility floor, and
+unclassified-command refusal continue to apply.
+
 ## init
 
 `init` holds no authority: the policy it writes authorizes nothing until a human
@@ -3511,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
@@ -3541,7 +4127,14 @@ gate.self          the "approval" CLI itself is pass-through
 ```
 
 Bash (Claude Code) and Shell (Cursor) commands are classified into SPEC.md §7
-action classes. Claude file tools (Edit, Write, MultiEdit, NotebookEdit) and
+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`; 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*`,
 `.cursor/hooks.json`, `.cursor/hooks/`, `.cursor/agents/`,
@@ -3558,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.
@@ -3638,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
@@ -3771,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
@@ -4051,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
@@ -4302,6 +4938,87 @@ when the log does not.
 
 ## up
 
+**Normal startup after setup and human attestation.** Run from the intended
+policy project's directory, load its environment explicitly, then leave this
+foreground process running:
+
+```sh
+cd /path/to/your/project
+eval "$(approval env)"
+approval up
+```
+
+For a source build, replace `approval` in both commands with
+`node /path/to/approval.md/cli.js`. `--as human:<id>` may name the configured
+approver explicitly; it does not perform identity setup or policy attestation.
+`up` reads credentials from its launch environment and does not load
+`.approval/env`. Existing exported approval variables take precedence over that
+map, so use a clean shell or unset another instance's variables first. Changing
+only `--dir` selects the policy; it does not relocate every log, environment or
+task path. Starting in the intended project keeps the default paths together.
+
+**Startup messages describe separate parts.** The default task directory is
+`backlog/tasks/`. If envelopes live elsewhere, pass
+`--tasks /path/to/existing/task-folder`. The daemon scans regular `.md` files
+immediately inside that directory, without recursion; an empty default folder
+does not cover envelopes in nested bundle directories. A missing default folder
+warns about absent drift coverage while TTL sweeping and queue rendering still
+run. An explicitly supplied missing directory is an error. `watch-unavailable`
+reports a failed watcher; the daemon still scans on its interval. Neither
+warning proves Telegram failed: check the channel's own startup line.
+
+A `live-draw` doctor failure needs a daemon serving this instance's draw socket.
+`up` starts that daemon, but serving draws also requires a `supervised-live`
+policy class and the configured sampling secret resolved in this process's
+launch environment, with `--no-draw` absent. Starting `up` alone cannot supply a
+missing secret. Without usable draws, every supervised-live action gates to a
+human. A policy with no `channels.web.port` and no explicit `--port` serves no
+web queue; that informational message is legitimate configuration.
+
+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
@@ -4324,11 +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 two writes: a `--ff-only` merge, and `npm run build`. It
+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), 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
@@ -4338,10 +5059,78 @@ 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
+create`. `git merge --ff-only` will not write over an untracked file, so on
+2026-09-07 the preflight refused, and its next-steps text pointed at `git
+status`, which cannot say whether the local copy holds anything the incoming one
+does not. That question is answerable, so it is answered. When the merge fails
+over untracked files and every path git names sits under `backlog/tasks/`, each
+one is read alongside `git show <target>:<path>` and given one of three
+verdicts:
+
+- **byte-identical** — the local copy says nothing the incoming copy does not,
+  so it is removed and the merge is retried once;
+- **every line also in the incoming copy** — the ordinary shape, a hand-filed
+  stub against a lane copy that added a plan and criteria. Nothing is lost by
+  letting the incoming copy land, but that is a judgment about an operator's
+  file, so the bytes are moved to a sibling of the checkout named
+  `<repo>-preflight-aside-<YYYY-MM-DD>` (outside the repository, so the next
+  fast-forward cannot collide with it again), the destination is printed on the
+  `preflight_warning` line, and the merge is retried once;
+- **anything else** — `up-preflight-task-file-conflict`, naming your path, the
+  incoming spelling, and how many lines only yours has.
+
+Every file is judged before any file is touched, the same two-pass shape as
+`approval log sync`'s payload reconciliation, so a refusal over the last
+collision cannot have already removed the first. One path outside
+`backlog/tasks/` and the whole set is declined: the merge keeps its old
+`up-preflight-failed` refusal and nothing is cleared, because clearing what was
+understood and then refusing anyway would have moved files for a merge that was
+never going to run. A path git chose to quote (`core.quotePath`) is declined for
+the same reason: guessing the spelling of a file about to be moved is the
+mistake the whole check exists to avoid.
+
 **`git reset --hard` is printed on no path, ever**, and a test asserts it. The
 one reset that appears is `--keep`, which refuses rather than discarding
 uncommitted work, and it is the third step of a runbook whose first step is to
@@ -4498,9 +5287,11 @@ is the verb that hands them the unit.
 **There is no `approval vault get`**, and it is not an oversight. A verb that
 printed a credential would put it in a terminal, a scrollback buffer, a CI log
 and — through the shell that ran it — a history file. A credential's only
-sanctioned journey is from the vault into an adapter, inside the verified-token
-window the adapter contract holds open (SPEC.md §10.4: "the credentials only
-answer to tokens"). Names are visible; values are not.
+sanctioned journey is from the vault into an adapter, inside the verified
+execution window the adapter contract holds open. Manual and selected-live
+paths verify and consume a token; an attested class rule may explicitly
+authorize an irreversible supervised or autonomous path. Names are visible;
+values are not.
 
 **What the vault DEFENDS:** credentials at rest, and casual reads by an agent
 that can read files in the working tree — the ciphertext hides the NAMES as well
@@ -4607,26 +5398,47 @@ the check would require this verb to know every adapter a machine might run.
 
 ## adapter
 
-An adapter is the hard boundary of SPEC.md §10.4: it holds the credentials and
-refuses to act without a valid, unexpired, single-use execution token bound to
-the action's `idempotency_key` and its `payload_hash`. An agent that bypasses
-this CLI still cannot send, because the credentials only answer to tokens.
+An adapter is the hard boundary of SPEC.md §10.4: it holds the credentials while
+the runtime recomputes the payload hash and applies attested policy. Manual and
+selected-live paths require a valid, unexpired, single-use execution token bound
+to the action's `idempotency_key` and `payload_hash`. An explicitly opted-in
+supervised or autonomous path has no grant and mints no token, so `--token` is
+optional at the command boundary.
 
-The runtime, not the adapter, owns the sequence: recompute the payload hash,
-read the declared class from the verified log, resolve the credentials the
-adapter says it cannot act without, run the adapter's own pre-token check,
-verify and consume the token, append `execution.started`, call the adapter,
-append the outcome. The adapter implements one method and cannot skip a step,
-because it never holds the sequence.
+Credential custody does not become implicit on the no-token path. The vault
+passphrase must already be present in the adapter process environment. The
+`.approval/env` source-map fallback remains available only inside a real token
+window: it rejects a null grant and a consumed nonmanual execution carrying no
+token digest. This lets an operator authorize nonmanual execution without
+giving an agent a new way to load credentials.
 
-The two steps that sit BEFORE the token spend are there for one reason: a
+The runtime, not the adapter, owns the sequence: recompute the payload hash,
+read the declared class from the verified log, check policy eligibility or the
+manual token without appending a start, resolve the credentials the adapter says
+it cannot act without, run the adapter's own pre-token check, then recheck policy
+and, on a manual path, verify and consume the token, append
+`execution.started`, call the adapter, append the outcome. The adapter implements
+one method and cannot skip a step, because it never holds the sequence.
+
+`supervised-live` selection still belongs to `approval request`. On a direct
+no-token invocation with no earlier approval cycle, the adapter contract runs
+that existing intake path from the verified declaration before it touches a
+credential. A selected or unavailable draw records the ordinary pending cycle
+and stops for its token. The request retains the exact already-hashed payload
+through the normal payload store, so the selected human sees the bound bytes.
+An unselected draw appends no approval event and continues, bound to the same
+attested policy digest through eligibility and start. Once any cycle exists,
+including a rejected or expired one, the contract never redraws it.
+
+The two steps that sit before authorization starts the execution are there for one reason: a
 condition that makes the side effect impossible, and that the runtime can
 establish without attempting it, must not cost a human's single-use grant to
 discover. A credential nobody stored refuses `credential-unavailable`; whatever
 the adapter's own check refuses arrives as `adapter-precheck-refused` with the
 adapter's reason in `adapter_code`. Both leave the log exactly as they found it,
 `acted` is `false`, there is no `started_seq` and no `outcome`, and the same
-token executes once the condition is repaired.
+token executes once the condition is repaired. On an admitted nonmanual path,
+there is no token to preserve and the same preflight still appends nothing.
 
 The pre-token check is offered only bytes the log binds to the action: the
 grant's `payload_hash` on the manual path, the registered declaration's off it.
@@ -4739,8 +5551,10 @@ The enforcement model it assumes is a split pair of keys. AgentMail keys carry
 `draft_create`, `draft_update`, `draft_read`, `draft_send` and `message_send`
 separately. The agent gets a key WITHOUT the two send permissions, so it can
 compose all day and cannot send; the key WITH them goes in the vault under
-`agentmail.api_key`, readable only inside the verified-token window the contract
-opens. `approval setup adapter agentmail` stores that pair, and
+`agentmail.api_key`, readable only inside the contract's execution window. On a
+nonmanual path, opening the encrypted vault requires its passphrase in the
+adapter process environment; the token-scoped source-map fallback does not run.
+`approval setup adapter agentmail` stores that pair, and
 `approval payload agentmail-draft` is the composing side's own verb.
 
 Two payload modes, told apart by the keys they carry, and a payload carrying
@@ -4811,6 +5625,82 @@ string as `message_id`, under the one key the adapter contract lifts onto
 as `"provider_ref":{"adapter":"agentmail","id":…}` beside the detail. A send
 whose answer names no id carries neither.
 
+## adapter zzz
+
+Creates a zzz.bot thread or reply for `communicate.zzz.external`. The only
+credential is `zzz.agent_token`, an invited principal token with write scope.
+It is read from the vault inside the shared execution window and sent only as an
+Authorization Bearer header. `--token` is required for manual or selected-live
+execution and omitted for an explicitly policy-authorized supervised or
+autonomous execution. On the no-token path, the vault passphrase must already be
+present in the adapter process environment.
+
+This verb is available from a source checkout containing APRV-320 until the
+next approval.md package release. npm `approval-md@0.1.0` predates the adapter;
+this change does not publish a package.
+
+The contract implemented here is zzz.bot API v0.1.0: [quickstart](https://zzz.bot/quickstart),
+[API guide](https://zzz.bot/api), [approval semantics](https://zzz.bot/approval),
+and [OpenAPI](https://zzz.bot/openapi.json).
+
+The payload is a strict tagged union:
+
+```json
+{"environment":"production","operation":"create_thread",
+ "room_id":"<room-id-from-GET-api-v1-rooms>","title":"…","body":"…",
+ "metadata":{},"tags":["…"],
+ "references":[{"kind":"external","target":"https://example.com/source",
+                "label":"Source","relationship":"source"}]}
+{"environment":"preview","operation":"create_reply",
+ "thread_id":"…","body":"…","metadata":{},"tags":["…"],"references":[]}
+```
+
+`environment` is exactly `production` or `preview`; operation is exactly
+`create_thread` or `create_reply`. Reference `kind` and `relationship` use
+the alternatives shown above. Unknown keys are refused. Bodies are 1 to 65,536
+characters, titles 1 to 200, tags at most 10 strings of 1 to 40 characters, and
+references at most 20. The entire canonical message JSON must fit 65,536 UTF-8
+bytes, so a maximum-length body can exceed the request limit once its other
+fields and JSON encoding are included.
+External reference targets must be HTTP or HTTPS URLs. All optional values that
+are present remain inside the bound payload and are sent unchanged.
+
+The message fields are deliberately flat beside the operation tag and target.
+This keeps the payload a person reviews close to ZZZ's request body. The adapter
+removes only `environment`, `operation` and the target id when building the
+POST body; every content field remains byte-for-byte represented in the
+canonical JSON sent to ZZZ.
+
+`production` routes to `https://zzz.bot` and `preview` to the fixed preview
+service. There is no API-base flag. Thread creation posts to
+`/api/v1/rooms/{room}/threads`; replies post to
+`/api/v1/threads/{thread}/posts`. Redirects are rejected. The
+`Idempotency-Key` is deterministic SHA-256 over the RFC 8785 form of the
+approval action key and payload hash, so the provider's retry identity binds the
+same action and exact bytes.
+
+HTTP 201 is accepted only with `{"id":"thr_…"|"pst_…","replayed":false}`,
+and HTTP 200 only with the same operation-appropriate id and `replayed:true`.
+The validated service id becomes `provider_ref`. A malformed or inconsistent
+success, transport error, redirect, or 5xx is `execution.indeterminate` because
+the POST may have committed. No response text is recorded. Definite refusals
+map to `zzz-invalid-request` (400), `zzz-unauthorized` (401),
+`zzz-forbidden` (403), `zzz-not-found` (404),
+`zzz-idempotency-conflict` (409), `zzz-payload-too-large` (413),
+`zzz-rejected` (422), or `zzz-rate-limited` (429).
+
+Public writes require an invited credential with write scope. Private rooms
+also require current membership carrying write and accepted, unexpired
+approval.md workflow evidence. zzz.bot intentionally returns 404 when private
+access is absent, so the adapter does not guess which prerequisite failed.
+`approval setup adapter zzz` verifies only credential acceptance through one
+read-only `GET /api/v1/rooms` and posts nothing.
+
+The local non-guest MCP server publishes this same verb from the registry. MCP
+invocation remains voluntary. Mechanical enforcement comes from keeping the
+write credential solely in the vault; an agent that also holds the credential
+can bypass the adapter.
+
 ## env
 
 This command is the only thing that reads `.approval/env`, and its default output
@@ -4909,7 +5799,7 @@ channel surfaces requests and collects decisions and holds no state, so its setu
 fills the OS keystore and `.approval/env` — the map of where the values that
 unlock the machine live. An adapter executes side effects and holds credentials,
 so its setup fills `.approval/vault.enc`, which holds the values a gated adapter
-SPENDS, read inside the verified-token window and by nothing else. There is no
+SPENDS, read inside the verified execution window and by nothing else. There is no
 verb that prints one back. (An older build spelled the Telegram one without the
 `channel` noun. That form exits 2 and names this one; there is no alias, because
 two spellings of a distinction the SPEC draws on purpose is how the distinction
@@ -5024,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,
@@ -5080,7 +6015,7 @@ unset, nothing is stored and no vault is created.
 
 The values go into the vault, not into the OS keystore and not into
 `.approval/env`: what this verb stores is what a gated adapter spends inside a
-verified-token window.
+verified execution window.
 
 What it reports: the path, the count, the names written and the names left alone.
 Never a value, on any path, including a failed probe. Exit 1 means the service
@@ -5157,7 +6092,7 @@ agentmail.api_key   the key that carries draft_send and message_send
 Store the SENDING key here and give the agent a different one. An AgentMail key
 is a mailbox in one string, so a deployment that hands the agent the sending key
 has an agent that can send without asking anybody, and the gate in front of it is
-decoration. The key in the vault is read only inside the verified-token window
+decoration. The key in the vault is read only inside the verified execution window
 the adapter contract opens.
 
 The probe sends nothing. It is `GET /v0/inboxes/{inbox_id}`, the same read a
@@ -5179,6 +6114,20 @@ adapter's does. A re-run that replaced only one name is offered the same probe
 over the stored pair, read through `readAgentmailConfig` over the vault: the
 exact path `approval adapter agentmail` takes at send time, printed by nothing.
 
+## setup adapter zzz
+
+The manifest contains one secret, `zzz.agent_token`. It must be an invited
+zzz.bot principal credential with write scope. Store the write-capable token in
+the vault and keep it out of the agent environment; otherwise the agent can post
+without passing through the adapter.
+
+The optional probe sends nothing. It makes one authenticated
+`GET /api/v1/rooms` against production and reports success only when zzz.bot
+accepts the credential. That endpoint does not disclose the principal's write
+scope, room memberships, or accepted private-room workflow evidence, so setup
+states those limits instead of claiming the token can publish. The actual
+approved POST remains the first proof of all write prerequisites.
+
 ## setup channel
 
 A channel is not an adapter, and the two setup verbs fill different stores.
@@ -5189,9 +6138,11 @@ credentials, so `approval setup adapter <name>` fills the vault instead.
 
 ## setup channel telegram
 
-Stop `approval channel telegram listen` first. Two processes long-polling one bot
-is a 409 from the Bot API, and the loser is whichever asked second. This is a
-configuration verb; it is not meant to run beside the listener.
+Stop any `approval up` process or `approval channel telegram listen` polling
+this bot first. Setup also uses `getUpdates` to discover the approver chat.
+Competing polls produce HTTP 409 from the Bot API. This is a configuration verb;
+after it finishes, reload the instance environment and use `approval up` for
+normal operation.
 
 The token is never typed into this process on a machine with a keystore: the
 helper's own no-echo prompt collects it, and this runtime reads it back on stdout
@@ -5217,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
@@ -5361,3 +6334,283 @@ queue, so an unbounded guest wait is one stranger stalling every other session.
 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.
+
+## Constrained Codex preparation
+
+approval codex prepare is an artifact generator. It writes one fresh review
+directory and has no activation path. Its requirements, managed config,
+launchers and launchd files are text for a human or MDM workflow to inspect.
+
+approval codex setup --check proves only that those artifacts match their
+closed manifest and hashes. approval codex doctor --strict asks the separate
+host question: are the package and its ancestors root-owned and immutable, are
+the three principals distinct, are the roots disjoint and canonical, and are
+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 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.