approval-md 0.2.0 → 0.4.0

package/dist/src/cli/help.js

@@ -47,6 +47,10 @@ Usage:
                       [--yes] [--json]
   approval register   <task-file> [--as <id>] [--log <path>] [--json]
   approval request    <task> --action <key> [--as <id>] [--json]
+  approval propose    --class <c> --key <k> --summary <s> --payload-json <j>
+                      [--as <id>] [--json]
+  approval start      <task> --action <key> --payload-json <j> [--as <id>]
+                      [--json]
   approval grant|reject|revoke <action-key> [--note <text>] [--as human:<id>] [--json]
   approval expire     <action-key> [--json]
   approval token      <action-key> [--policy <path>] [--dir <path>] [--json]
@@ -54,7 +58,7 @@ 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 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|->
@@ -93,6 +97,7 @@ Usage:
   approval doctor     [--log <path>] [--policy <path>] [--dir <path>]
                       [--api-base <url>] [--json]
   approval payload hash <file|-> [--json]
+  approval payload run [--cwd <dir>] [--hash] [--json] -- <cmd…>
   approval payload agentmail-draft <inbox-id> <draft-id> [--api-base <url>]
                       [--json]
   approval journal write --message "<text>" | - [--task <id>] [--session <id>]
@@ -121,6 +126,11 @@ Usage:
   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 serve      --as agent:<id> [--dir <path>] [--log <path>]
+                      [--policy <path>] [--port <n> | --listen <host:port>
+                      | --listen unix:<path>]
+                      [--allow-non-loopback]               (HTTP; foreground)
+  approval muse       [--dir <path>] [--port <n>]  (local prototype; foreground)
   approval reindex    [--log <path>] [--index <path>] [--force] [--json]
   approval render     [--log <path>] [--out <path>] [--policy <path>]
                       [--dir <path>] [--json]
@@ -184,6 +194,12 @@ Ask — an agent declares an action and acts on the answer:
   request   ask the gate to admit a declared action (manual classes append
             approval.requested; supervised/autonomous append nothing and
             proceed straight to execution, per amended SPEC.md §6.3)
+  propose   register and request one action in one call, payload inline as
+            JSON, in a class the policy declares by name and opens to agents
+            (agent_may_request); retry-safe on the same class, key and bytes
+  start     record execution.started for a proposed action its requester is
+            carrying out: spends the harness grant, or records the policy's
+            own authorization for a non-manual class. REQUESTER-ONLY
   token     report whether a live single-use execution token exists for an
             action (the RAW token is printed once, by grant, and stored nowhere)
   consume   spend a token and append execution.started (internal plumbing;
@@ -204,7 +220,10 @@ Ask — an agent declares an action and acts on the answer:
             draft the agent composed, refused if the draft changed after the
             snapshot a human approved
   wait      block until a task's requests are decided; the exit code IS the
-            decision (0 granted, 1 rejected/revoked/withdrawn, 3 expired, 6 timeout)
+            decision (0 granted or nothing-to-wait-for, 1 rejected/revoked/
+            withdrawn/not-registered, 3 expired, 6 timeout, 7 void: a
+            re-attest voided it, ask again); run only on --json status
+            "granted", which means an unspent grant
   withdraw  take back your OWN pending request (timeout, cancelled, superseded);
             terminal, requester-only, and a late grant then authorizes nothing
   hook      put the gate in front of an agent HARNESS. "hook claude-code" and
@@ -245,6 +264,15 @@ Ask — an agent declares an action and acts on the answer:
             channels are not published, because an MCP client is an agent's
             harness and SPEC.md §11 makes the agent the untrusted policy. It
             runs as ONE agent identity, fixed at startup, that nothing changes
+  serve     the same agent-facing surface over HTTP, for a harness in a sandbox
+            with no local log and no local policy. It adds the three things MCP
+            withheld for transport reasons: hook <harness> taking the harness
+            envelope as the request body, log follow paged by an exclusive
+            (seq, hash) cursor, and the store as an archive. TWO CREDENTIALS
+            from the launch environment, and authorization is per verb: the
+            agent one opens the hook and an allowlist of what a harness under
+            oversight needs to ask and to act on a grant, the tenant one opens
+            everything else, so the agent never reads the log it is judged by
 
 Decide — a human answers, and only a human can:
   queue     the pending-decision INBOX: requests awaiting a human, inside their
@@ -300,6 +328,9 @@ Inspect — what the log says, and whether anything needs repair:
             over its RFC 8785 canonical serialization), the value a declaration
             carries and a grant binds to. Most flows never need it: "request
             --payload" hashes, verifies and stores the bytes in one step.
+            "payload run" prints the payload a gated command binds to: its
+            argv, its cwd, and the digest of the script that argv names, so a
+            grant over a script binds the script and not its path.
             "payload agentmail-draft" snapshots one AgentMail draft with the
             AGENT's key, so a human approves the words and not a draft id
   daemon    "daemon run" is the watch loop of SPEC.md §10.2, in the FOREGROUND:
@@ -607,24 +638,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
 
@@ -652,22 +708,22 @@ export const POLICY_TEST_HELP = policyVerbHelp("test", "check");
 export const POLICY_ATTEST_HELP = `approval policy attest — record a human's sign-off on the policy file
 
 Usage:
-  approval policy attest [--policy <path>] [--dir <path>] [--organ <path>]
-                         [--as human:<id>] [--log <path>] [--json]
+  approval policy attest [--policy|--dir <path>] [--organ|--path <path>]
+                         [--bootstrap] [--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
+  --bootstrap      a store's FIRST policy only; re-run: policy-already-attested
   --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 policy.updated with the file's exact SHA-256; gates refuse while it
+differs ("policy-not-attested"). Bytes, not parse. Human-only, CONFIG-DECLARED:
+the trust boundary is the local machine (local control, not who). No TTY needed.
+--organ appends gate.organ.attested (policy.core); --path gate.path.signed_off.
 
 JSON shape: docs/cli-reference.md#policy-attest
 ${EXIT_CODES_POINTER}
@@ -677,22 +733,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}
@@ -754,6 +810,45 @@ JSON shape: docs/cli-reference.md#request
 ${GATE_CODES_POINTER}
 ${JSON_ERRORS}
 ${why("request")}`;
+export const PROPOSE_HELP = `approval propose — register and request one action, payload inline
+
+Usage:
+  approval propose --class <c> --key <k> --summary <text> --payload-json <json>
+                   [--as <id>] [--policy <p>] [--dir <p>] [--log <p>] [--json]
+
+Flags:
+  --class <c>          an EXACT key of the policy's classes, opened to agents by
+                       agent_may_request: true on it or a <prefix>.* family
+  --key <k>            "<class>:<id>", recorded verbatim as action_key (≤1 KiB)
+  --summary <text>     the line the approver reads (in the log, in cleartext)
+  --payload-json <j>   the payload, a JSON object of at most 262144 bytes
+  --as <id>            human:<id> or agent:<id>; else APPROVAL_HUMAN
+
+decision "requested": poll \`approval wait <task> --timeout 0\` (7 void or 3
+expired: propose again). "autonomous"/"supervised": act, then \`approval start\`.
+A retry appends nothing (idempotent:true) unless the answer can't be used.
+
+${GATE_CODES_POINTER}
+${JSON_ERRORS}
+${why("propose")}`;
+export const START_HELP = `approval start — record that you are carrying out a proposed action
+
+Usage:
+  approval start <task> --action <key> --payload-json <json> [--as <id>]
+                 [--policy <p>] [--dir <p>] [--log <p>] [--json]
+
+Flags:
+  --action <key>       the action's idempotency key (required)
+  --payload-json <j>   the bytes you act on; must hash to the registered binding
+  --as <id>            human:<id> or agent:<id>; else APPROVAL_HUMAN
+
+Appends one execution.started, once per key. REQUESTER-ONLY. A key with a
+request spends its harness grant; a key with none is recorded as authorized by
+the policy, and a manual class is refused.
+
+${GATE_CODES_POINTER}
+${JSON_ERRORS}
+${why("start")}`;
 function decisionHelp(verb) {
     const noun = verb === "grant" ? "approval" : verb === "reject" ? "refusal" : "withdrawal";
     const body = verb === "grant"
@@ -958,19 +1053,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
@@ -985,7 +1082,7 @@ Usage:
                 [--as <id>] [--policy <p>] [--dir <p>] [--log <p>] [--json]
 
 Flags:
-  --timeout <d>    how long to wait, in the duration grammar (e.g. 6h). Required
+  --timeout <d>    how long to wait (e.g. 6h; 0 reads the state once). Required
   --interval <d>   poll interval (default 500ms)
   --withdraw-on-timeout  on timeout, withdraw the requests THIS actor opened
   --as <id>        the withdrawing actor; read only with the flag above
@@ -993,12 +1090,12 @@ Flags:
   --json           machine-readable output;  -h, --help   this text
 
 Polls until every approval.requested of the task has a decision, or the timeout
-elapses. WRITES NOTHING unless --withdraw-on-timeout. Only the MANUAL path
-produces requests to wait for; a task with none returns at once, exit 0.
+elapses. WRITES NOTHING unless --withdraw-on-timeout. Only the MANUAL path makes
+requests; none left to wait on is exit 0, nothing-to-wait-for, never granted.
 
 JSON shape: docs/cli-reference.md#wait
-${EXIT_CODES_POINTER}. THE CODE IS THE DECISION: 0 granted, 1 rejected, revoked
-or withdrawn (--json status says which), 3 expired, 4 I/O, and
+${EXIT_CODES_POINTER}. THE CODE IS THE DECISION: 0 granted or nothing-to-wait-for,
+1 rejected/revoked/withdrawn/not-registered (--json says which), 3 expired, 4 I/O, 7 VOID, and
   6  TIMEOUT — the wait elapsed with request(s) still undecided.
 ${JSON_ERRORS}
 ${why("wait")}`;
@@ -1039,9 +1136,9 @@ Flags:
 
 THIS IS NOT "approval queue": queue is what a human must answer, status is what
 an operator must fix. Writes nothing, and reports in one object: attestation,
-verification, dangling executions, budget headroom per global limit,
-loop_escalations, harness_outcomes, git coverage, payload_store, and anomalies
-when there are any. The coverage numbers move neither health nor the exit code.
+verification, dangling executions, budget headroom, loop_escalations,
+harness_outcomes, payload_store, git coverage, the daemon id, plus anomalies and
+refusals when there are any. The last three report rather than judge.
 
 JSON shape: docs/cli-reference.md#status
 ${EXIT_CODES_POINTER} (1 when anything needs attention, including a torn tail)
@@ -1292,14 +1389,13 @@ Usage:
   approval channel web [--port <n>] [--payload-dir <path>] [--as human:<id>]
                        [--policy <path>] [--dir <path>] [--log <path>] [--json]
   approval channel telegram listen|health [--once] [--as human:<id>] [--json]
+  approval channel relay [--listen [host:]port | --port <n>] [--proposer <a>] [--json]
 
 Subcommands:
-  cli        render the pending queue in this terminal and, when it IS a
-             terminal, collect decisions with a prompt
-  web        serve the pending queue as a page on 127.0.0.1 ONLY, with
-             Grant/Reject forms and a batch gesture
-  telegram   deliver the queue to a Telegram chat and long-poll for
-             Approve/Reject taps
+  cli        render the pending queue here; on a terminal, collect decisions
+  web        the queue as a page on 127.0.0.1 ONLY, with Grant/Reject forms
+  telegram   deliver the queue to a Telegram chat; collect Approve/Reject taps
+  relay      take gestures an operator's authenticated relay carries (EdgeOS)
 
 A channel is TRANSPORT: it renders what the runtime derived and reports the
 gesture a human made. Every decision collected here is recorded by the same
@@ -1408,27 +1504,103 @@ ${why("quickstart")}`;
 export const HOOK_HELP = `approval hook — put the gate in front of an agent harness
 
 Usage:
-  approval hook claude-code|cursor|codex [--as agent:<id>] [--timeout <d>] [--interval <d>] [--retry-grace <d>] [--policy <p>] [--dir <p>] [--log <p>]
+  approval hook claude-code|cursor|codex|grok|muse|hermes [--as agent:<id>] [--timeout <d>] [--interval <d>] [--retry-grace <d>] [--harness-cap <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
+  hermes       Hermes Agent snake_case pre_tool_call/post_tool_call; {action,message} out, DENY IS EXIT 2, allow is {}. fail_closed: true BLOCKS a broken hook (observed on main 118984d7; default false, and v0.21.3 ignores it silently). \`approval hook hermes --help\` prints the YAML
   classify     print what the classifier makes of a command line and exit
-
-  --as <id>        proposing identity (default agent:claude-code / agent:cursor / agent:codex)
-  --timeout/--interval/--retry-grace <d>  wait / poll / hold for a retry (9m/1s/5m)
+  --as <id>        proposing identity (default agent:<harness>)
+  --timeout/--interval/--retry-grace/--harness-cap <d>  wait / poll / hold for a retry / the harness's OWN kill timeout (9m/1s/5m/none), which lapses the request 60s inside it so approval.expired lands first
   --dir/--policy/--log <p>   policy+log root; --dir sets BOTH, default primary
   -h, --help       this text
-
 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-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.
+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-harness-cap-too-short,
+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-hermes-execute-code-unbound, 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>] [--harness-cap <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>] [--harness-cap <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 HOOK_HERMES_HELP = `approval hook hermes — the gate in front of Hermes Agent (APRV-398)
+Usage:
+  approval hook hermes [--as agent:<id>] [--timeout <d>] [--interval <d>]
+                       [--retry-grace <d>] [--harness-cap <d>] [--policy <p>] [--dir <p>] [--log <p>]
+snake_case in (hook_event_name pre_tool_call|post_tool_call, tool_name, tool_input).
+ONE dialect out: {"action":"block","message":"…"} AT EXIT 2 deny, {} at exit 0 allow
+(no allow directive; reason on stderr). Tools: terminal (command + ABSOLUTE workdir),
+write_file, patch, read_file, search_files. REFUSED: execute_code
+(hook-hermes-execute-code-unbound), and a call with no absolute workdir or a relative
+or missing path (hook-unsupported-execution-context): Hermes resolves those against a session directory no event reports.
+OBSERVED on main 118984d7: fail_closed: true BLOCKS hook crash, timeout and garbage.
+ITS DEFAULT IS false, and v0.21.3 (2026.9.14) fails open SILENTLY: run a 2026-09-20+ build.
+No hooks_auto_accept and no TTY: Hermes SILENTLY SKIPS REGISTERING THE HOOK. --dir IS MANDATORY (a gateway session's cwd is the user HOME); docs/hermes-hook.md has the evidence.
+The file the human commits, $HERMES_HOME/config.yaml — the home's LAST SEGMENT must be .hermes or the classifier does not see the organ (export HERMES_HOME=/Users/you/dev/hermes/.hermes; policy.core):
+  plugins: { hook_callback_timeout: 600 }
+  hooks_auto_accept: true
+  hooks:
+    pre_tool_call:
+      - { command: "approval hook hermes --dir <repo> --timeout 4m --harness-cap 300s", timeout: 300, fail_closed: true }
+    post_tool_call:
+      - { command: "approval hook hermes --dir <repo> --timeout 4m", timeout: 300 }
+The entry "timeout" caps at 300s; hook_callback_timeout (default 30s) fails closed
+by itself, so --timeout MUST BE UNDER 300s (4m). WITHOUT --harness-cap the hook assumes the 30s default and denies every manual call hook-harness-cap-too-short: raise hook_callback_timeout above the entry timeout, then pass --harness-cap <the smaller of the two>. The window is then cap-60s (240s above) or approval_ttl, whichever is shorter. Register BOTH events. Long form:
+${EXIT_CODES_POINTER} (0 allow, 2 deny; post_tool_call always 0; never "ask")
+${why("hook")}`;
 export const IMPORT_HELP = `approval import — turn existing permissions prose into a draft policy
 
 Usage:
@@ -1455,7 +1627,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,
@@ -1470,12 +1642,15 @@ export const PAYLOAD_HELP = `approval payload — work with the bytes an approva
 
 Usage:
   approval payload hash <file|-> [--json]
+  approval payload run [--cwd <dir>] [--hash] [--json] -- <cmd…>
   approval payload agentmail-draft <inbox-id> <draft-id> [--api-base <url>]
                                    [--json]
 
 Commands:
   hash      print the payload_hash of a JSON document: SHA-256 over its RFC 8785
             canonical serialization (SPEC.md §6.2)
+  run       print the payload \`approval run\` will recompute for a command: its
+            argv, its cwd, and the digest of the script that argv names
   agentmail-draft
             snapshot one AgentMail draft as the payload a grant can bind to,
             read with the AGENT's key from AGENTMAIL_API_KEY
@@ -1507,6 +1682,30 @@ JSON shape (stdout, one object): {"ok":true,"hash":"<64hex>"}
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
 ${why("payload-hash")}`;
+export const PAYLOAD_RUN_HELP = `approval payload run — the payload a gated command binds to
+
+Usage:
+  approval payload run [--cwd <dir>] [--hash] [--json] -- <cmd…>
+
+Flags:
+  --cwd <dir>       the directory the command will run in (default: this one)
+  --hash            print the payload_hash instead of the payload bytes
+  --json / -h, --help   machine-readable (with --hash) / this text
+
+Prints what \`approval run\` recomputes before it spawns:
+  {"argv":[…],"cwd":"…","script":{"argv_index":N,"path":…,bytes,sha256}}
+
+THE SCRIPT IS THE POINT (APRV-401): a known interpreter followed by a path, or
+a path at argv[0], binds THAT FILE'S BYTES, so a script edited before the run is
+payload-mismatch rather than a silent substitution. An argv naming no script
+carries no "script" key and hashes as it always did. NOT bound: an inline
+program, the interpreter, an unlisted launcher, what the script itself runs.
+
+  approval payload run --hash -- bash install.sh   # the declaration
+  approval payload run -- bash install.sh | approval request … --payload -
+${EXIT_CODES_POINTER}
+${JSON_ERRORS}
+${why("payload-run")}`;
 export const PAYLOAD_AGENTMAIL_DRAFT_HELP = `approval payload agentmail-draft — snapshot a draft as an approvable payload
 
 Usage:
@@ -1611,8 +1810,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\`.
 
@@ -1676,19 +1875,23 @@ ${why("render")}`;
 export const TELEGRAM_HELP = `approval channel telegram — the Telegram push channel
 
 Usage:
-  approval channel telegram listen [--once] [--as human:<id>] [--payloads <f>]
-                                   [--policy <path>] [--dir <path>]
-                                   [--log <path>] [--api-base <url>]
-                                   [--poll-timeout <seconds>] [--json]
-  approval channel telegram health [--json]
+  approval channel telegram listen  [--once] [--as human:<id>] [--payloads <f>]
+        [--policy <p>] [--dir <p>] [--log <p>] [--api-base <url>] [--poll-timeout <s>] [--json]
+  approval channel telegram webhook --url <https://...> [--listen [host:]port]
+        [--path <p>] [--cycle <d>] and every listen flag above
+  approval channel telegram health  [--dir <path>] [--log <path>] [--json]
+
+Two transports, MUTUALLY EXCLUSIVE per bot: listen long-polls getUpdates;
+webhook has Telegram post each update to a url you register (no poller).
 
 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; APPROVAL.md carries only those NAMES,
+and no flag puts 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 attested person and refuses every other account.
 
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
@@ -1707,7 +1910,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.
@@ -1717,6 +1920,54 @@ JSON shape: docs/cli-reference.md#channel-telegram-listen
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
 ${why("channel-telegram-listen")}`;
+export const TELEGRAM_WEBHOOK_HELP = `approval channel telegram webhook — decisions arrive by webhook, no poller
+
+Usage:
+  approval channel telegram webhook --url <https://host/path> [--path <p>]
+        [--listen [host:]port | --port <n>] [--allow-non-loopback] [--cycle <d>]
+        [--reclaim] [--as human:<id>] [--policy <p>] [--dir <p>] [--log <p>]
+        [--payloads <f>] [--api-base <url>] [--no-gloss] [--json]
+
+Flags:
+  --url <https://...>  REQUIRED: the PUBLIC url registered with setWebhook. https only, on port 443, 80, 88 or 8443 (Telegram's list), and no user:password
+  --port <n> / --listen <[host:]port>   this process's own bind. LOOPBACK by default (4683); routable also needs --allow-non-loopback. Never 0
+  --path <p> / --cycle <d>   must equal the url's own path / dispatch period (30s)
+  --reclaim            register over the webhook already holding this bot
+  -h, --help           this text
+
+APPROVAL_TG_WEBHOOK_SECRET is REQUIRED, from the launch environment: it is
+Telegram's secret_token, echoed on every delivery, and a post without the
+matching header is refused and never a decision. NO TLS HERE: plain HTTP
+behind a proxy or tunnel you own (--url names it); long polling then refuses.
+
+JSON shape: docs/cli-reference.md#channel-telegram-webhook
+${EXIT_CODES_POINTER}
+${JSON_ERRORS}
+${why("channel-telegram-webhook")}`;
+export const CHANNEL_RELAY_HELP = `approval channel relay — gestures an operator's authenticated relay carries
+
+Usage:
+  approval channel relay [--listen [host:]port | --port <n>] [--allow-non-loopback]
+        [--proposer agent:<id>] [--policy <p>] [--dir <p>] [--log <p>] [--json]
+
+Flags:
+  --port <n> / --listen <[host:]port>   LOOPBACK by default (4684); routable also needs --allow-non-loopback
+  --proposer <actor>   who a propose gesture is recorded under (default agent:edgeos-relay)
+  -h, --help           this text
+
+APPROVAL_RELAY_SECRET is REQUIRED, from the launch environment: the control
+plane sends it in x-approval-relay-secret, and a post without it is refused
+and never written to the log. POST /relay/gesture takes one closed JSON body:
+propose, attest or decline a policy by sha256, or grant or reject a request by
+action key, each with a nonce and issued_at. The sender is an EdgeOS id, and
+it is resolved against approvers.<id>.senders.edgeos in the policy in force:
+an unmapped account is refused sender-unmapped. This process holds NO human
+identity and NO TLS. Trust: the daemon trusts the relay's attribution.
+
+JSON shape: docs/cli-reference.md#channel-relay
+${EXIT_CODES_POINTER}
+${JSON_ERRORS}
+${why("channel-relay")}`;
 export const TELEGRAM_HEALTH_HELP = `approval channel telegram health — is this runtime configured for Telegram?
 
 Usage:
@@ -1796,7 +2047,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
@@ -2030,14 +2281,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
@@ -2110,6 +2361,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:
@@ -2290,26 +2563,28 @@ ${why("setup-service")}`;
 // ---------------------------------------------------------------------------
 // The MCP wrapper (APRV-87)
 // ---------------------------------------------------------------------------
-export const CODEX_HELP = `approval codex — prepare and inspect a constrained Codex host bundle (INERT)
+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 start|serve --manifest <abs> [--json]
-
-prepare writes a fresh review bundle only. setup --check verifies its closed file
-set, hashes, manifest and generated templates. Neither installs a package, edits
-Codex configuration, creates principals, loads services, reads credentials, or
-changes policy. doctor fails closed on unknown custody, executes no manifest
-binary in this slice, and reports runtime versions as unchecked.
-
-start and serve currently refuse with codex-not-ready. The policy-bound broker
-and confined runner arrive in APRV-325.2 and APRV-325.3. An npm or project
-installation alone is never reported as enforcement.
-
-${EXIT_CODES_POINTER} (1 means the strict boundary is absent or invalid)
+  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)
@@ -2336,4 +2611,42 @@ SERIALLY, THIS SERVER READS NO .approval/env. POST-V1: tasks/elicitation.
 ${EXIT_CODES_POINTER} (2 is a startup refusal; 0 is a clean shutdown)
 ${JSON_ERRORS}
 ${why("mcp-serve")}`;
+export const MUSE_HELP = `approval muse — local synthetic Muse consumer prototype (FOREGROUND)
+
+Usage:
+  approval muse [--dir <path>] [--port <n>]
+
+APPROVAL_MUSE_TENANT identifies one tenant per process. Distinct
+APPROVAL_MUSE_READ_TOKEN and APPROVAL_MUSE_PROPOSE_TOKEN (24+ characters) are
+required in the launch environment. Listens only on 127.0.0.1, port 4683 by
+default. This is a local prototype, not a verified native Muse protocol.
+Human decisions use the already configured Telegram listener. No decision,
+execution, export, or generic verb endpoint exists here.
+
+${EXIT_CODES_POINTER} (2 is a startup refusal; 0 is a clean shutdown)
+${why("muse")}`;
+export const SERVE_HELP = `approval serve — the agent-facing surface over HTTP (FOREGROUND)
+
+Usage:
+  approval serve [--as agent:<id>] [--dir <p>] [--log <p>] [--policy <p>]
+                 [--port <n> | --listen <host:port>|unix:<path>]
+
+Flags:
+  --as agent:<id>  the identity EVERY call is recorded under, or APPROVAL_AGENT
+  --dir/--log/--policy <p>   the store root, and the log and policy pinned
+  --port <n>=4682  loopback. --listen <host:port> widens, non-loopback ALSO needs --allow-non-loopback; unix:<path> or APPROVAL_SERVE_LISTEN: a socket
+  --hook-timeout/--hook-harness-cap <d>  pinned on every hook call, as the stdin form's --timeout and --harness-cap (the CALLER's own kill timeout)
+  --hook-threads <n>=16 / --hook-queue <n>=64  hook calls running at once (a thread each) / waiting; past both, refused serve-hook-saturated
+
+For a harness in a sandbox with no local log and no policy. THE VERBS ARE mcp
+serve's: the registry less human_only, --as absent from every schema, the
+identity appended last, no grant. It adds hook/<harness> (envelope in, the
+bytes stdin prints out), log/follow (paged, exclusive (seq, hash) cursor) and
+export (the store, minus keys, env and vault). AUTHORIZATION IS PER VERB:
+APPROVAL_SERVE_AGENT_TOKEN opens the hook and an allowlist (ask, and act on a
+grant); APPROVAL_SERVE_TENANT_TOKEN opens the rest, records included. NO TLS.
+
+${EXIT_CODES_POINTER} (2 is a startup refusal; 0 is a clean shutdown)
+${JSON_ERRORS}
+${why("serve")}`;
 //# sourceMappingURL=help.js.map