approval-md 0.1.0 → 0.3.0

package/dist/src/cli/help.js

@@ -36,8 +36,10 @@ Usage:
   approval log verify [--log <path>] [--json]
   approval log tail   [--log <path>] [-n <count>] [--json]
   approval log export [--log <path>] [--json]
+  approval log follow [--log <path>] [--from <seq>] [--cursor-hash <64hex>] --json
   approval instructions [--schemas] [--json]
   approval init       [--dir <path>] [--json]
+  approval quickstart [--dir <path>] [--api-base <url>]      (interactive; no --json)
   approval policy check|test <class> [--reversible true|false] [--policy <path>] [--dir <path>] [--json]
   approval policy attest [--policy <path>] [--dir <path>] [--as human:<id>] [--json]
   approval policy amend  [--policy <path>] [--dir <path>] [--log <path>]
@@ -52,10 +54,12 @@ Usage:
                       [--as <id>] [--json]                            (internal)
   approval run        <action-key> [--token <t>] [--payload-hash <64hex>]
                       [--as <id>] [--no-sandbox] [--json] -- <cmd…>
-  approval sandbox    [--allow-loopback] [--log <path>] -- <cmd…>
-  approval adapter email <action-key> --token <t> --payload <file|->
+  approval sandbox    [--allow-loopback] [--read-jail] [--log <path>] -- <cmd…>
+  approval adapter email <action-key> [--token <t>] --payload <file|->
                       [--as <id>] [--vault <path>] [--timeout <ms>] [--json]
-  approval adapter agentmail <action-key> --token <t> --payload <file|->
+  approval adapter agentmail <action-key> [--token <t>] --payload <file|->
+                      [--as <id>] [--vault <path>] [--timeout <ms>] [--json]
+  approval adapter zzz <action-key> [--token <t>] --payload <file|->
                       [--as <id>] [--vault <path>] [--timeout <ms>] [--json]
   approval execution resolve <action-key> --outcome completed|failed
                       --note "<text>" [--as human:<id>] [--json]
@@ -114,6 +118,7 @@ Usage:
                       [--log <path>]                    (reads preToolUse JSON)
   approval hook classify [--json] [--policy <path>] [--dir <path>] -- <command…>
   approval import agents-md <file> [--out <path>] [--json]
+  approval codex      prepare|setup|doctor|start|serve (strict host workflow)
   approval mcp serve  --as agent:<id> [--dir <path>] [--log <path>]
                       [--policy <path>]              (MCP over stdio; foreground)
   approval reindex    [--log <path>] [--index <path>] [--force] [--json]
@@ -129,6 +134,10 @@ Set up — make this directory and this machine ready:
             atomic-write temp files. Appends
             nothing, attests nothing, overwrites nothing; a re-run writes
             nothing and reports what already exists
+  quickstart ask three decisions, write a solo policy with the named human as
+            its sole approver, configure identity and an optional Telegram
+            channel, show the exact bytes, then require typed \`understood\`
+            before attesting. HUMAN-ONLY and INTERACTIVE ONLY
   setup     the WRITER for that file: "setup identity|vault|sampling" and
             "setup channel <name>" store each secret in the OS keystore and
             record where it lives, and "setup adapter <name>" fills the VAULT
@@ -145,7 +154,7 @@ Set up — make this directory and this machine ready:
             "vault set|list|remove" are HUMAN-ONLY; list shows NAMES and never
             values, and there is no "vault get" — a credential's only sanctioned
             journey is from .approval/vault.enc into an adapter, inside the
-            verified-token window. The passphrase comes from the environment
+            verified execution window. The passphrase comes from the environment
             variable the policy NAMES (vault.passphrase_env), never from a flag
   env       resolve .approval/env — the environment SOURCE MAP — and print an
             export block for your shell to evaluate. THE ONLY VERB THAT READS
@@ -182,13 +191,15 @@ Ask — an agent declares an action and acts on the answer:
   run       execute a command behind the gate: appends execution.started before
             spawning it, execution.completed/failed with the child's exit code
             after, and exits with that same code
-  adapter   execute an approved action through a side-effect adapter, the hard
+  adapter   execute an action through a side-effect adapter, the hard
             boundary of SPEC.md §10.4. "adapter email" sends one RFC 5322
             message over SMTP for a communicate.email.external action: the
-            credentials come from the vault inside the verified-token window,
-            the payload is the bytes the grant bound to, and the runtime — not
-            the adapter — recomputes the hash, spends the token, and writes both
-            execution events around the send. "adapter agentmail" serves the
+            credentials come from the vault inside the execution window, the
+            payload is the bytes the declaration or grant bound to, and the
+            runtime recomputes the hash, applies policy, and writes both
+            execution events around the send. Manual and selected-live paths
+            require --token; policy-authorized supervised/autonomous paths do
+            not mint one. "adapter agentmail" serves the
             same class over the AgentMail API: a direct send, or the send of a
             draft the agent composed, refused if the draft changed after the
             snapshot a human approved
@@ -395,6 +406,7 @@ Usage:
   approval log verify  [--log <path>] [--json]
   approval log tail    [--log <path>] [-n <count>] [--json]
   approval log export  [--log <path>] [--json]
+  approval log follow  [--log <path>] [--from <seq>] [--cursor-hash <64hex>] --json
   approval log sync    [--remote <name>] [--branch <name>] [--json]
   approval log advance [--branch <name>] [--pr] [--dry-run] [--json]
   approval log checkpoint --as human:<id> [--key-file <path>] [--json]
@@ -402,17 +414,40 @@ Usage:
 Subcommands:
   verify   walk the hash chain end to end; clean | torn-tail | corrupt
   tail / export   the last N records (default 10) / every line, verbatim
+  follow   verified records after an exclusive cursor, then verified appends
   sync     fast-forward pull, with a snapshot and a chain reconcile
   advance  commit the log's new records onto a records branch
   checkpoint  sign the current head with your own key (human-only)
 
-verify, tail and export only read. sync and advance move the FILE and append no
-record; checkpoint appends one. Default log: .approval/log/events.jsonl
-JSON shapes: docs/cli-reference.md
-
-${EXIT_CODES_POINTER}
+verify, tail, export and follow only read. sync and advance move the FILE and append no record;
+checkpoint appends one. Default log: .approval/log/events.jsonl
+JSON shapes: docs/cli-reference.md; ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
 ${why("log")}`;
+export const FOLLOW_HELP = `approval log follow — follow verified records after a cursor
+
+Usage:
+  approval log follow [--log <path>] [--from <seq>] [--cursor-hash <64hex>] --json
+
+Flags:
+  --log <path>          log file to read (default .approval/log/events.jsonl)
+  --from <seq>          exclusive sequence cursor (default 0)
+  --cursor-hash <hex>   hash of record --from, retained by the consumer
+  --json                required; one complete event object per stdout line
+  -h, --help            this text
+
+The complete chain is verified before each emitted batch. Notifications only
+wake another verification. Corrupt, torn, unreadable, truncated or cursor-
+mismatched logs stop the stream before any record from that batch is printed.
+
+Persist seq and hash after the external effect succeeds. Reconnecting from that
+cursor is at-least-once across a crash between the effect and cursor storage;
+exactly-once external effects require the consumer's own idempotency mechanism.
+
+${EXIT_CODES_POINTER} (0 on signal or broken-pipe cancellation; 1 corrupt or cursor
+mismatch; 2 usage; 3 torn tail; 4 I/O)
+${JSON_ERRORS}
+${why("log-follow")}`;
 export const LOG_SYNC_HELP = `approval log sync — fast-forward the committed log, safely
 
 Usage:
@@ -441,12 +476,12 @@ export const LOG_ADVANCE_HELP = `approval log advance — commit and push the lo
 
 Usage:
   approval log advance [--remote <n>] [--branch <n>] [--base <n>] [--pr]
-                       [--no-auto-merge] [--dry-run] [--json]
-
+             [--co-author "Name <email>"] [--no-auto-merge] [--dry-run] [--json]
 Flags:
   --remote <name>  remote to push to (default origin)
   --branch <name>  records branch (default records-log-<date>); never main
   --base <name>    branch to parent the commit on (default: the one you are on)
+  --co-author <id> append Name <email> display credit to commit and PR body
   --pr / --dry-run  open the PR through gh and ARM its merge / write nothing
   --no-auto-merge / --json / -h, --help  do not arm / JSON output / this text
 
@@ -572,24 +607,49 @@ const POLICY_MANUAL_BECAUSE = `manualBecause is "matched-rule", "irreversibility
 export const POLICY_HELP = `approval policy — explain what policy does with an action class
 
 Usage:
-  approval policy check|test <class> [--reversible true|false] [--policy <p>]
-                             [--dir <p>] [--json]
-  approval policy attest [--policy <p>] [--dir <p>] [--as human:<id>] [--json]
-  approval policy amend  [--policy <p>] [--dir <p>] [--log <p>] [--as human:<id>]
-                         [--require-load] [--dry-run] [--commit] [--yes] [--json]
+  approval policy check|test <class> [--reversible true|false] [--policy|--dir <p>] [--json]
+  approval policy attest [--policy|--dir <p>] [--as human:<id>] [--json]
+  approval policy amend  [--policy|--dir|--log <p>] [--as human:<id>] [--require-load]
+                         [--dry-run] [--commit|--pr] [--yes] [--json]
+  approval policy apply  <proposal.md> [--dry-run] [--no-amend] [--pr] [--yes]
 
 Subcommands:
   check   explain the autonomy resolution for <class>
   test    exact alias of check (SPEC.md §10.1 names both)
   attest  record a human's sign-off on the policy file's bytes (human-only)
   amend   the whole amendment ceremony: diff, advisory, attestation, commit
+  apply   apply a proposal document's quoted replacements, then amend (human-only)
 
-Nothing is executed, requested, or logged: this reads APPROVAL.md and answers a
-hypothetical. Discovery is APPROVAL.md then APPROVALS.md in --dir.
-${POLICY_MANUAL_BECAUSE}
+check and test read APPROVAL.md and answer a hypothetical, executing and logging nothing.
+Discovery is APPROVAL.md then APPROVALS.md in --dir. ${POLICY_MANUAL_BECAUSE}
 
 ${POLICY_EXIT_CODES}
 ${why("policy")}`;
+export const POLICY_APPLY_HELP = `approval policy apply — apply a proposal document to APPROVAL.md, then amend
+
+Usage:
+  approval policy apply <proposal.md> [--policy <p>] [--dir <p>] [--log <p>]
+      [--as human:<id>] [--dry-run] [--no-amend] [--no-publish] [--yes] [--json]
+
+Flags:
+  <proposal.md>                   the document whose Current/Replace-with pairs to apply
+  --policy <p> / --dir <p>        the policy file, or the directory to discover it in
+  --dry-run / --no-amend          show the replacements only / write them and stop
+  --no-publish / --yes / --json   stop at the commit / skip both prompts / machine
+
+HUMAN-ONLY: an agent identity refuses apply-agent-actor, and the verb classifies
+policy.core, human-only in this project's policy. Every pair resolves against an
+in-memory copy FIRST, so a stale proposal writes nothing at all. A pair is two
+fenced blocks WITH a declared language (APRV-273), labelled \`Current:\` and
+\`Replace with:\` above; \`Supersedes:\` names an earlier section's result to match
+instead. Whole-file replacement is NOT accepted: every byte written is anchored
+to a byte proved present. The values block is treated as the policy block is.
+Refusals: usage, io, apply-agent-actor, proposal-empty, proposal-malformed,
+proposal-stale, proposal-ambiguous. Then it runs \`policy amend --pr\`, which
+PUBLISHES: refspec push, pull request, merge armed, checkout never moved.
+
+${EXIT_CODES_POINTER}
+${why("policy-apply")}`;
 function policyVerbHelp(verb, alias) {
     return `approval policy ${verb} — explain what policy does with an action class
 
@@ -618,21 +678,21 @@ export const POLICY_ATTEST_HELP = `approval policy attest — record a human's s
 
 Usage:
   approval policy attest [--policy <path>] [--dir <path>] [--organ <path>]
-                         [--as human:<id>] [--log <path>] [--json]
+                         [--path <path>] [--as human:<id>] [--log <path>] [--json]
 
 Flags:
   --policy <path> / --dir <path>   the policy file, or where to discover it
   --organ <path>   attest a GATE ORGAN instead; one path per call, under --dir
+  --path <path>    sign off a PROTECTED path's current bytes; one path per call
   --as human:<id>  the human attesting; overrides APPROVAL_HUMAN
   --log <path>     log file to append to (default .approval/log/events.jsonl)
-  --json           machine-readable output
-  -h, --help       this text
+  --json / -h, --help   machine-readable output / this text
 
-Appends one policy.updated event carrying the SHA-256 of the policy file's exact
-bytes; gate operations refuse while it differs ("policy-not-attested").
-Human-only, identity CONFIG-DECLARED: the trust boundary is the local machine,
-so it proves someone with local control signed off, not who. Bytes, not parse.
---organ appends gate.organ.attested for a policy.core harness file instead.
+Appends one policy.updated event with the policy file's exact SHA-256; gate
+operations refuse while it differs ("policy-not-attested"). Bytes, not parse.
+Human-only, identity CONFIG-DECLARED. What attestation proves is bounded: the
+trust boundary is the local machine, so someone with local control, not who.
+--organ appends gate.organ.attested (policy.core); --path gate.path.signed_off.
 
 JSON shape: docs/cli-reference.md#policy-attest
 ${EXIT_CODES_POINTER}
@@ -642,22 +702,22 @@ export const POLICY_AMEND_HELP = `approval policy amend — the whole amendment
 
 Usage:
   approval policy amend [--policy|--dir|--log <p>] [--as human:<id>|agent:<id>] [--require-load]
-      [--dry-run] [--commit] [--no-publish] [--yes] [--json] [--branch <n>|--direct] [--wait <d>]
+      [--dry-run] [--commit|--pr] [--no-publish] [--yes] [--json] [--branch <n>|--direct] [--wait <d>]
 
 Flags:
   --policy <p> / --dir <p> / --log <p>  policy, its discovery dir, and the log
   --as human:<id> / agent:<id>    attest HERE, or ask for a TAP (--wait/--interval/--note)
   --require-load                  refuse to attest a policy that does not load
   --dry-run / --commit / --no-publish   write nothing / the ceremony / stop at commit
-  --branch <name> / --direct      force the BRANCH or the DIRECT flow
+  --pr / --branch <name> / --direct     FINISH it (branch, push, PR, arm) / force either flow
   --yes / --json / -h, --help     skip the prompt / machine-readable / this text
 
-Hashes the policy, diffs it against the BASELINE (classes AND every policy key), attests, then
-commits EXACTLY the policy, the log and the pins when they moved. commit-preconditions, the pins
-and the DOGFOOD SUITE refuse BEFORE the append; git-failed, push-rejected, pr-failed break after it.
-Attested TEXT is NOT recoverable from the log: HASH-ONLY MODE. Flows, in PRECEDENCE, highest first:
---branch <name>, --direct; a refused push PUBLISHES ITSELF, dropping to a RUNBOOK. MERGE COMMIT it.
---as agent: appends policy.proposed; the TAP attests. Fail closed: no-channel, declined, timeout.
+Hashes the policy, diffs it against the BASELINE (classes AND every policy key), attests, then commits
+EXACTLY the policy, the log and the pins when they moved. commit-preconditions, staged-unrelated,
+dirty-tree, the pins and the DOGFOOD SUITE refuse BEFORE the append; git-failed, push-rejected and
+pr-failed break after it, into a RUNBOOK. Attested TEXT is NOT recoverable from the log:
+HASH-ONLY MODE. Flows, in PRECEDENCE, highest first: --branch <name>, --pr (opens or UPDATES the open
+pull request, arms --auto), --direct. MERGE COMMIT it. --as agent: appends policy.proposed, TAP attests.
 
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
@@ -923,19 +983,21 @@ ${why("run")}`;
 export const SANDBOX_HELP = `approval sandbox — run a command with no way out (APRV-193)
 
 Usage:
-  approval sandbox [--allow-loopback] [--log <path>] -- <cmd> [args…]
+  approval sandbox [--allow-loopback] [--read-jail] [--log <path>] -- <cmd…>
 
 Flags:
   --allow-loopback  also allow connections to localhost. For a suite that
                     starts its own server. A real widening: a port is a port
+  --read-jail       also deny file reads outside the gate root and the scratch
+                    roots. Already on when the policy declares read_scope, and
+                    nothing turns it off where it did (APRV-347)
   --log <path>      the log, so the credential material beside it can be made
                     unreadable to the child (vault, env map, sealing keys)
   -h, --help        this text ("--help --long" adds the reference section)
 
-Denies the child outbound network (macOS sandbox-exec), scrubs the
-credential-bearing variables out of its environment, and exits with the child's
-own exit code. It appends NOTHING: it removes a capability rather than
-authorizing anything, and the gate stays reachable because its IPC is a file.
+Denies outbound network (macOS sandbox-exec), scrubs the credential variables
+from the child's environment, exits with its code, and appends NOTHING: it
+removes a capability rather than authorizing anything.
 
 The point is laundered exec: "npm test" runs whatever was written a minute ago,
 so the command's NAME stopped describing its effect. An agent HARNESS cannot run
@@ -1346,31 +1408,105 @@ JSON shape (one object on stdout):
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
 ${why("init")}`;
+export const QUICKSTART_HELP = `approval quickstart — make a small solo gate operative
+
+Usage:
+  approval quickstart [--dir <path>]
+
+Asks three decisions: your human id, terminal or Telegram, and which five class
+families always ask. It refuses a directory that already has policy or .approval
+state, writes a fresh policy, configures identity, and runs doctor before showing
+the exact bytes. The one expected unattested row is ignored at that point; every
+other failed row stops setup before attestation. Typed \`understood\` attests only
+if the file still has the displayed digest. A Telegram token uses the existing
+OS-keystore setup path and is resolved explicitly for that preflight.
+
+Interactive only. Piped stdin and --json exit 2 and print the manual sequence.
+The generated default applies only to classified reversible actions; protected
+controls, fail-closed policy loading and unclassified-command refusal remain.
+
+Flags:
+  --dir <path>      project directory (default: current directory)
+  --api-base <url>  Telegram API base passed to channel setup and doctor
+  -h, --help        this text
+
+${EXIT_CODES_POINTER} (0 success; 1 doctor failure; 2 usage; 4 filesystem failure)
+${why("quickstart")}`;
 export const HOOK_HELP = `approval hook — put the gate in front of an agent harness
 
 Usage:
-  approval hook claude-code|cursor [--as agent:<id>] [--timeout <d>] [--interval <d>]
-              [--retry-grace <d>] [--policy <p>] [--dir <p>] [--log <p>]
+  approval hook claude-code|cursor|codex|grok|muse [--as agent:<id>] [--timeout <d>] [--interval <d>] [--retry-grace <d>] [--policy <p>] [--dir <p>] [--log <p>]
   approval hook classify [--json] [--policy <p>] [--dir <p>] -- <command…>
 
 Commands:
   claude-code  Claude Pre/PostToolUse JSON in; decision JSON out. REGISTER BOTH
   cursor       Cursor preToolUse JSON in; native {permission} JSON out
+  codex        Codex synchronous Pre/Post JSON; Bash denied, direct apply_patch experimentally gated
+  grok         Grok Build camelCase Pre/PostToolUse JSON in; {decision,reason} out, DENY IS EXIT 2. \`approval hook grok --help\` prints the config
+  muse         Muse Code snake_case Pre/PostToolUse; ONE dialect out or it fails open. \`approval hook muse --help\` prints the config
   classify     print what the classifier makes of a command line and exit
-
-Flags (claude-code, cursor):
-  --as <id>        proposing identity (default agent:claude-code / agent:cursor)
-  --timeout/--interval/--retry-grace <d>  wait / poll / hold for a retry (55s/1s/5m)
+  --as <id>        proposing identity (default agent:<harness>)
+  --timeout/--interval/--retry-grace <d>  wait / poll / hold for a retry (9m/1s/5m)
   --dir/--policy/--log <p>   policy+log root; --dir sets BOTH, default primary
   -h, --help       this text
 
-Deny: hook-unclassified, hook-class-human-only, hook-opaque, hook-unparseable,
-hook-rejected, hook-revoked, hook-expired, hook-withdrawn, hook-timeout,
-hook-gate-refused:<c>, hook-grant-unverified, hook-sandbox-required,
-hook-policy-unavailable, hook-log-unreachable, hook-io.
+Codex opt-in: register exact Bash|apply_patch synchronously with timeout 600s (default wait 9m). Bash is denied because native events hide per-call workdir; direct apply_patch is experimental. PostToolUse is diagnostic.
+
+Deny: hook-unclassified, hook-class-human-only, hook-harness-launch-unruled, hook-opaque, hook-unparseable, hook-rejected, hook-revoked, hook-expired, hook-withdrawn, hook-timeout,
+hook-gate-refused:<c>, hook-grant-unverified, hook-sandbox-required, hook-policy-unavailable, hook-log-unreachable, hook-unsupported-execution-context, hook-muse-contributor-model, hook-io.
 
 ${EXIT_CODES_POINTER} (harness verbs use 0 and 2 only; 0 is a verdict, never "ask")
 ${why("hook")}`;
+export const HOOK_GROK_HELP = `approval hook grok — the gate in front of Grok Build (APRV-243)
+
+Usage:
+  approval hook grok [--as agent:<id>] [--timeout <d>] [--interval <d>]
+                     [--retry-grace <d>] [--policy <p>] [--dir <p>] [--log <p>]
+
+camelCase in (hookEventName, sessionId, cwd, workspaceRoot, toolName, toolInput);
+{"decision":"allow"|"deny","reason":"…"} out, never "ask". DENY IS EXIT 2,
+allow is 0, post-execution always 0.
+
+READ docs/grok-hook.md BEFORE COMMITTING THIS: Grok Build fails OPEN on hook
+timeout, crash and malformed output, with no setting to change that. It
+contradicts the fail-closed invariant and the adapter cannot fix it.
+
+The file the human commits, .grok/hooks/pre-tool-use.json:
+  {"hooks":{"PreToolUse":[{"matcher":"*","hooks":[
+    {"type":"command","command":"approval hook grok --dir <repo>",
+     "timeout": 600}]}]}}
+
+That "timeout" MUST EXCEED --timeout (default 9m), or Grok abandons the call
+mid-wait and, failing open, runs the command while a human is still deciding.
+.grok/hooks/ classifies policy.core, like .cursor/hooks.json.
+
+${EXIT_CODES_POINTER} (0 allow, 2 deny; never "ask")
+${why("hook")}`;
+export const HOOK_MUSE_HELP = `approval hook muse — the gate in front of Meta Muse Code (APRV-350)
+
+Usage:
+  approval hook muse [--as agent:<id>] [--timeout <d>] [--interval <d>]
+                     [--retry-grace <d>] [--policy <p>] [--dir <p>] [--log <p>]
+snake_case in (hook_event_name, tool_name, tool_input, cwd, model); ONE dialect
+out, nested {"hookSpecificOutput":{"permissionDecision":…}} at exit 0, never
+"ask". Tools: bash (per-call workdir), write_file, read_file, search.
+
+READ docs/muse-hook.md FIRST. Muse fails OPEN on hook crash, timeout and
+malformed output — and output MIXING dialects is itself malformed, so a payload
+satisfying every harness at once satisfies this one not at all.
+CONTRIBUTOR MODELS ARE REFUSED (hook-muse-contributor-model) on every tool call
+regardless of policy: Meta trains on that tier. The guard stops tool calls; it
+cannot recall a prompt already sent.
+The file the human commits, .muse/hooks.json (no "matcher"; policy.core):
+  {"hooks":{"PreToolUse":[{"hooks":[
+    {"type":"command","command":"approval hook muse --dir <repo>",
+     "timeout": 600}]}],"PostToolUse":[{"hooks":[
+    {"type":"command","command":"approval hook muse --dir <repo>",
+     "timeout": 600}]}]}}
+That "timeout" MUST EXCEED --timeout (9m), or Muse abandons the call mid-wait
+and, failing open, runs it while a human is still deciding.
+${EXIT_CODES_POINTER} (0 for every verdict; deny is the body, not the code)
+${why("hook")}`;
 export const IMPORT_HELP = `approval import — turn existing permissions prose into a draft policy
 
 Usage:
@@ -1397,7 +1533,7 @@ Reads one markdown file, finds its permissions section, and prints a DRAFT
 \`\`\`yaml approval-policy block from a fixed, ordered keyword table.
 THE DRAFT AUTHORIZES NOTHING: this verb never writes APPROVAL.md, never logs and
 never attests. Fail closed: a bullet the table cannot place is kept verbatim.
-"What I value"-style headings become a DRAFT values fence, all under \`wants\`.
+"What I value"-style headings become a DRAFT values fence, all under \`like\`.
 
 JSON shape (stdout, one object):
   {"ok":true,"source":"<path>","out":"<path>"|null,
@@ -1553,8 +1689,8 @@ Flags:
   --json / -h, --help   machine-readable output / this text
 
 Prints the optional \`\`\`yaml approval-values block of APPROVAL.md: what the
-operator loves, likes and dislikes, what they want from you as behaviour, and
-how they read and answer. EVERY FORM CARRIES THE LABEL: this is GUIDANCE and
+operator loves, likes (including what they ask of you as behaviour) and
+dislikes, and how they read and answer. EVERY FORM CARRIES THE LABEL: this is GUIDANCE and
 never policy. It grants nothing, forbids nothing and changes no verdict; what
 you MAY do is the policy block, answered by \`approval policy check\`.
 
@@ -1622,15 +1758,18 @@ Usage:
                                    [--policy <path>] [--dir <path>]
                                    [--log <path>] [--api-base <url>]
                                    [--poll-timeout <seconds>] [--json]
-  approval channel telegram health [--json]
+  approval channel telegram health [--dir <path>] [--log <path>] [--json]
 
 Configuration is ENVIRONMENT-ONLY: APPROVAL_TG_TOKEN holds the bot token and
-APPROVAL_TG_CHAT the approver chat id. APPROVAL.md carries only those variable
-NAMES, and there is no flag that would put a bot token into a shell history.
+APPROVAL_TG_CHAT the approver chat id by default. APPROVAL.md carries only those
+variable NAMES — a second gate on one machine declares a pair of its own — and
+there is no flag that would put a bot token into a shell history.
 
 Anyone in the configured chat can approve as the actor this process was started
 with, so the chat's membership is part of your trust boundary. Use a private
-chat with the bot.
+chat with the bot — or map senders: approvers.<id>.senders.telegram: "<id>"
+records each decision against the person that Telegram account is attested to
+and refuses a tap from an account the policy does not name.
 
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
@@ -1649,7 +1788,7 @@ Flags:
   --as human:<id>  the approver every decision is recorded against. REQUIRED
   --payloads <f>   OPTIONAL OVERRIDE: JSON file of action key -> payload
   --policy <p> / --dir <p> / --log <p>   the policy, its dir, the log written to
-  --api-base <url> / --poll-timeout <s>   Bot API base / long-poll seconds (25)
+  --api-base <url> / --poll-timeout <s> / --allow-cross-instance   Bot API base / long-poll seconds (25) / start on another instance's bot
   -h, --help       this text
 Config is ENVIRONMENT-ONLY and the policy names the variables. Delivery is per cycle;
 a new request reaches the phone without restart. THE TOKEN IS PRINTED HERE, NEVER SENT TO TELEGRAM.
@@ -1738,7 +1877,7 @@ Flags (every "daemon run" flag, unchanged, plus):
   --payloads <f> / --payload-dir <d>  payload overrides: telegram / web
   --api-base <url> / --poll-timeout <s>   Bot API base / long-poll seconds
   --port <n>       queue-page port. Precedence: --port, channels.web.port
-  --no-telegram / --no-web   leave that channel out of this process
+  --no-telegram / --no-web / --allow-cross-instance   leave that channel out / start on another instance's bot
   --no-gloss / --restart-backoff <d>   drop gloss / first retry wait
   --gloss-provider <p> / --gloss-model <id>   choose claude|codex (default claude); Codex requires model; no fallback
   -h, --help       this text
@@ -1755,7 +1894,7 @@ ${why("up")}`;
 // ---------------------------------------------------------------------------
 /** One line, not a paragraph: the rest of the reasoning is in the reference. */
 const VAULT_NO_GET = `THERE IS NO "approval vault get": a credential's only sanctioned journey is from
-the vault into an adapter, inside the verified-token window.`;
+the vault into an adapter, inside the verified execution window.`;
 export const VAULT_HELP = `approval vault — the encrypted credential store adapters read from
 
 Usage:
@@ -1849,39 +1988,39 @@ JSON shape: docs/cli-reference.md#vault-remove
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
 ${why("vault-remove")}`;
-export const ADAPTER_HELP = `approval adapter — execute an approved action through a side-effect adapter
+export const ADAPTER_HELP = `approval adapter — execute an action through a side-effect adapter
 
 Usage:
-  approval adapter email|agentmail <action-key> --token <t> --payload <file|->
-                      [--as human:<id>|agent:<id>] [--vault <path>]
-                      [--policy|--dir|--log <path>] [--timeout <ms>] [--json]
+  approval adapter email|agentmail|zzz <action-key> [--token <t>] --payload <file|->
+      [--as human:<id>|agent:<id>] [--vault <path>] [--policy|--dir|--log <path>]
+      [--timeout <ms>] [--json]
 
 Adapters:
-  email   send one RFC 5322 message over SMTP, for actions declared under
-          communicate.email.external (SPEC.md §6.1's canonical example)
-  agentmail  send the same class over the AgentMail API: a direct message, or
-          a draft the agent composed, re-read and refused if it drifted
+  email   send SMTP for communicate.email.external (SPEC.md §6.1)
+  agentmail  send that class through AgentMail, directly or from a re-read draft
+  zzz     create a thread or reply for communicate.zzz.external
+
+An adapter is the HARD BOUNDARY of SPEC.md §10.4: it holds credentials while the
+runtime checks the payload and attested policy. Manual and selected-live actions
+require a valid, single-use --token bound to the action and payload. An explicitly
+policy-authorized nonmanual action has no token; its process must already hold the
+vault passphrase, and the token-scoped .approval/env fallback stays unavailable.
 
-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. The runtime, not the adapter,
-owns the sequence: recompute the hash, resolve the credentials the adapter
-declared, run its pre-token check, verify and consume the token, append
-execution.started, call the adapter, append the outcome. The two steps before
-the spend refuse without appending or spending, so the token stays live.
+A no-token supervised-live call runs intake; selected/unavailable draws stop before
+credentials. An unselected draw proceeds. Existing approval cycles are not redrawn.
 
-${EXIT_CODES_POINTER} (5 when no valid token was presented; 1 for every refusal)
+${EXIT_CODES_POINTER} (5 when a manual path needs a token; 1 for every refusal)
 ${JSON_ERRORS}
 ${why("adapter")}`;
 export const ADAPTER_EMAIL_HELP = `approval adapter email — send one approved message over SMTP
 
 Usage:
-  approval adapter email <action-key> --token <t> --payload <file|->
+  approval adapter email <action-key> [--token <t>] --payload <file|->
                       [--as <id>] [--vault <path>] [--policy <path>]
                       [--dir <path>] [--log <path>] [--timeout <ms>] [--json]
 
 Flags:
-  --token <t>      the single-use token "approval grant" printed. REQUIRED
+  --token <t>      REQUIRED for manual or selected-live; omit on authorized nonmanual
   --payload <file|->  the JSON payload the grant bound to. REQUIRED (a body on
                    a command line is a body in the shell history)
   --as <id> / --vault <path>   executing identity / the SMTP credential store
@@ -1894,17 +2033,17 @@ it, and a non-ASCII body goes quoted-printable. The VAULT holds smtp.host,
 smtp.port, smtp.security, smtp.user, smtp.password; failure codes add smtp-<NNN>.
 
 JSON shapes and failure codes: docs/cli-reference.md#adapter-email
-${EXIT_CODES_POINTER} (5 when no valid token was presented; 1 for every refusal)
+${EXIT_CODES_POINTER} (5 when a manual path needs a token; 1 for every refusal)
 ${JSON_ERRORS}
 ${why("adapter-email")}`;
 export const ADAPTER_AGENTMAIL_HELP = `approval adapter agentmail — send one approved message through AgentMail
 
 Usage:
-  approval adapter agentmail <action-key> --token <t> --payload <file|->
+  approval adapter agentmail <action-key> [--token <t>] --payload <file|->
       [--as <id>] [--vault|--policy|--dir|--log <p>] [--timeout <ms>] [--json]
 
 Flags:
-  --token <t> / --payload <file|->   the token and the bytes. BOTH REQUIRED
+  --token <t> / --payload <file|->   token: manual or selected-live; payload: always
   --as <id> / --vault <p> / --policy <p> / --dir <p> / --log <p>   as email
   --timeout <ms> / --json / -h, --help   15000 / machine-readable / this text
 
@@ -1918,9 +2057,33 @@ TWO PAYLOAD MODES, told apart by shape and never inferred between:
 The VAULT holds agentmail.inbox_id and agentmail.api_key, and that key is the one
 WITH draft_send and message_send; the agent's own key must not have them.
 
-${EXIT_CODES_POINTER} (5 when no valid token was presented; 1 for every refusal)
+${EXIT_CODES_POINTER} (5 when a manual path needs a token; 1 for every refusal)
 ${JSON_ERRORS}
 ${why("adapter-agentmail")}`;
+export const ADAPTER_ZZZ_HELP = `approval adapter zzz — send one approved zzz.bot message
+
+Usage:
+  approval adapter zzz <action-key> [--token <t>] --payload <file|->
+      [--as <id>] [--vault|--policy|--dir|--log <p>] [--timeout <ms>] [--json]
+
+The tagged payload chooses create_thread or create_reply and production or
+preview. Both destinations are fixed in the adapter; the payload cannot supply
+an arbitrary URL. The runtime binds the complete payload, including metadata,
+tags and references, and derives ZZZ's retry-safe Idempotency-Key from the
+action key and payload hash. Actions use communicate.zzz.external. The VAULT
+holds zzz.agent_token.
+
+--token is required for manual or selected-live and omitted for explicitly
+authorized nonmanual execution; then the process must already hold the passphrase.
+
+A public-room write needs an invited token with write scope. A private-room
+write also needs current room membership and accepted, unexpired approval.md
+workflow evidence. zzz.bot intentionally hides missing private access as 404.
+
+JSON shapes and failure codes: docs/cli-reference.md#adapter-zzz
+${EXIT_CODES_POINTER} (5 when a manual path needs a token; 1 for every refusal)
+${JSON_ERRORS}
+${why("adapter-zzz")}`;
 export const ENV_HELP = `approval env — resolve .approval/env into an export block for your shell
 
 Usage:
@@ -1948,14 +2111,14 @@ ${why("env")}`;
 export const SETUP_HELP = `approval setup — interactive configuration (SPEC.md §5.2, §10.1)
 
 Usage:
-  approval setup identity|vault|sampling|checkpoint [--as human:<id>] …
+  approval setup identity|vault|sampling|sender-key|checkpoint [--as human:<id>] …
   approval setup channel|adapter <name> [--api-base <url>] [--as human:<id>] …
   approval setup service [--platform launchd|systemd] [--uninstall] …
-
 Subcommands:
   identity   declare who the human is (APPROVAL_HUMAN); not human-only
   vault      mint a vault passphrase, store it, and record where it lives
   sampling   mint the audit sampling secret and print the policy line for it
+  sender-key mint the key that hashes sender ids; --id prints one mapping line
   checkpoint mint the Ed25519 key you sign the log's head with (--rotate/--retire)
   channel    configure one CHANNEL's transport credential (OS keystore)
   adapter    fill the VAULT with one ADAPTER's credentials, from its manifest
@@ -2028,6 +2191,28 @@ does not edit an attested policy file: it prints the block to add and the
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
 ${why("setup-sampling")}`;
+export const SETUP_SENDER_KEY_HELP = `approval setup sender-key — mint the key that hashes sender ids (HUMAN-ONLY)
+
+Usage:
+  approval setup sender-key [--as human:<id>] [--log <path>] [--dir <path>]
+  approval setup sender-key --id <account-id> [--log <path>] [--json]
+
+Bare, it mints the operator-held key that turns a channel account id into the
+value an approvers[id].senders block carries, stores it as approval-sender-key,
+and writes its source line. It edits no policy file (APRV-370).
+
+WITH --id it mints and stores nothing: it reads the key from the environment,
+prints the hmac-sha256:<hex> for that account, and prints the senders line and
+the paste-ready proposal pair around it. Run \`eval "$(approval env)"\` first.
+That is the one setup path that needs no terminal.
+
+A LISTENER THAT HOLDS NO KEY UNDER A KEYED MAPPING REFUSES EVERY DECISION on
+that channel (sender-key-unavailable), never falling back to a raw comparison.
+The key authenticates nothing; losing it costs the ability to resolve accounts.
+
+${EXIT_CODES_POINTER}
+${JSON_ERRORS}
+${why("setup-sender-key")}`;
 export const SETUP_CHECKPOINT_HELP = `approval setup checkpoint — mint the log-checkpoint key (HUMAN-ONLY)
 
 Usage:
@@ -2059,10 +2244,11 @@ Usage:
                                 [--policy <path>]
 
 Known adapters:
-  email     the SMTP settings \`approval adapter email\` reads: smtp.host,
-            smtp.port, smtp.security, smtp.user, smtp.password
+  email     smtp.host, smtp.port, smtp.security, smtp.user, smtp.password
   agentmail the two values \`approval adapter agentmail\` reads:
             agentmail.inbox_id and agentmail.api_key
+  zzz       the invited write credential \`approval adapter zzz\` reads:
+            zzz.agent_token
 
 Asks for each credential the named adapter DECLARES, validates every answer with
 the adapter's own rules, stores them in .approval/vault.enc, and offers to prove
@@ -2081,7 +2267,7 @@ Usage:
   approval setup adapter email [--as human:<id>] [--log <path>] [--dir <path>]
                                [--policy <path>]
 
-The five names the email adapter reads inside the verified-token window:
+The five names the email adapter reads inside the verified execution window:
 
   smtp.host      the submission server
   smtp.port      587 for STARTTLS submission, 465 for implicit TLS
@@ -2104,7 +2290,7 @@ Usage:
   approval setup adapter agentmail [--as human:<id>] [--log <path>]
       [--dir <path>] [--policy <path>]
 
-The two names the AgentMail adapter reads inside the verified-token window:
+The two names the AgentMail adapter reads inside the verified execution window:
   agentmail.inbox_id  the inbox this runtime sends from; the inbox IS the sender
   agentmail.api_key   the key carrying draft_send and message_send, no echo
 
@@ -2122,6 +2308,23 @@ says so rather than claiming the key can send. A FAILED PROBE KEEPS THE VALUES:
 ${EXIT_CODES_POINTER} (1 means AgentMail refused, or the vault would not open)
 ${JSON_ERRORS}
 ${why("setup-adapter-agentmail")}`;
+export const SETUP_ADAPTER_ZZZ_HELP = `approval setup adapter zzz — the zzz.bot credential (HUMAN-ONLY)
+
+Usage:
+  approval setup adapter zzz [--as human:<id>] [--log <path>]
+      [--dir <path>] [--policy <path>]
+
+The vault name is zzz.agent_token: an invited principal token with write scope.
+Keep it out of the agent environment, so publication remains behind the adapter.
+
+THE PROBE POSTS NOTHING. It performs one authenticated GET /api/v1/rooms. A
+success proves only that zzz.bot accepted the active credential. It does not
+prove write scope, room membership, or private-room workflow evidence; zzz.bot
+checks those when the approved message is sent.
+
+${EXIT_CODES_POINTER} (1 means zzz.bot refused, or the vault would not open)
+${JSON_ERRORS}
+${why("setup-adapter-zzz")}`;
 export const SETUP_CHANNEL_HELP = `approval setup channel — configure one channel's transport credential (HUMAN-ONLY)
 
 Usage:
@@ -2190,6 +2393,30 @@ ${why("setup-service")}`;
 // ---------------------------------------------------------------------------
 // The MCP wrapper (APRV-87)
 // ---------------------------------------------------------------------------
+export const CODEX_HELP = `approval codex — prepare a constrained Codex host and broker its workspace writes
+
+Usage:
+  approval codex prepare --instance <id> --workspace <abs> --primary <abs>
+      --install-root <abs> --output <new-dir> --codex <abs> --node <abs> [--json]
+  approval codex setup --check <bundle-dir> [--json]
+  approval codex doctor --strict --manifest <abs> [--json]
+  approval codex apply --manifest <abs> --proposal <file> [--json]
+      [--token <class>=<token>]... [--require-exclusive-custody]
+  approval codex serve|recover --manifest <abs> [--json]
+  approval codex start --manifest <abs> [--timeout <dur>] [--json] [-- <cmd>...]
+
+prepare, setup --check and doctor are the inert half: a review bundle, its exact
+file set and hashes, and host custody, executing no manifest binary. apply is the
+BROKER: a bounded create/replace/delete/move proposal, ONE ACTION PER PATH CLASS,
+gate-authorized, every leg started before any byte moves, then staged, journaled
+and applied under a workspace lock; the MANIFEST supplies actor, root, policy and
+log. recover READS a retained journal, repairing nothing. serve is EXACTLY ONE MCP
+tool, separate from \`approval mcp serve\`. start CONFINES a shell: one disposable
+writable path, read-only gate and workspace, no credentials, no egress, NO OPT-OUT.
+
+${EXIT_CODES_POINTER} (1: the boundary is absent, invalid, or the workspace mixed)
+${JSON_ERRORS}
+why: docs/cli-reference.md#constrained-codex-preparation`;
 export const MCP_HELP = `approval mcp serve — the MCP wrapper of SPEC.md §10.5 (FOREGROUND)
 
 Usage: