approval-md 0.1.0 → 0.2.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
@@ -439,6 +485,20 @@ 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.
 
+`--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 +596,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 +622,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 +649,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"|
@@ -1155,6 +1231,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):
 
 ```
@@ -2529,6 +2612,16 @@ 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.
 
 **`--json`** (one object on stdout):
 
@@ -2684,9 +2777,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 +3286,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
@@ -3456,6 +3555,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
@@ -3541,7 +3677,11 @@ gate.self          the "approval" CLI itself is pass-through
 ```
 
 Bash (Claude Code) and Shell (Cursor) commands are classified into SPEC.md §7
-action classes. 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`, and
+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/`,
@@ -4302,6 +4442,47 @@ 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.
+
 **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,7 +4505,9 @@ 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 three writes: a `--ff-only` merge, `npm run build`, and
+clearing an untracked `backlog/tasks/` file the incoming commit already contains
+out of the merge's way (APRV-300, 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
@@ -4340,8 +4523,42 @@ running. When it is not, it refuses, and changes nothing:
 | `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-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 |
 
+**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 +4715,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 +4826,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 +4979,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 +5053,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 +5227,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
@@ -5080,7 +5398,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 +5475,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 +5497,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 +5521,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
@@ -5361,3 +5695,22 @@ 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 makes 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.

package/docs/codex-enforced-session.md

@@ -0,0 +1,30 @@
+# Constrained Codex preparation
+
+approval codex prepare creates a review bundle for a future constrained Codex
+session. It is packaging and diagnostics, not activation.
+
+The bundle pins one macOS/Codex version, distinct Codex, broker and runner
+principals, disjoint active-worktree, primary-gate and root-owned installation
+roots, and one exact MCP executable plus argument vector. Its requirements
+template makes native Codex tools read-only, disables command network and the
+browser, computer-use, plugin and web-search surfaces, and allowlists only the
+strict MCP identity.
+
+Preparation writes only a new output directory. approval codex setup --check
+verifies the exact file set, SHA-256 index, instance schema and every generated
+template byte. A passing check means the inert bundle is internally consistent.
+
+approval codex doctor --strict --manifest PATH inspects host custody. It rejects
+unsupported manifest platforms or version declarations, missing or overlapping principals,
+overlapping roots, symlinks, path drift, non-root-owned or writable trusted
+ancestors, invocation drift, missing executables and a workspace writable by
+the Codex principal. APRV-325.1 also unconditionally reports broker-not-ready
+and runner-not-ready. POSIX ownership and mode cannot prove the absence of
+writable ACLs, so this slice executes no manifest-selected binary and reports
+both installed runtime versions unchecked.
+
+The package does not run a postinstall script, call sudo, edit Codex
+configuration, create accounts, load services, access credentials, start a
+model, or alter APPROVAL.md. A human or MDM system must eventually install and
+own the reviewed artifacts. APRV-325.2 and APRV-325.3 must provide the broker,
+runner and end-to-end denial evidence before the session can be called enforced.