approval-md 0.3.0 → 0.4.1

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]
@@ -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:
@@ -410,6 +441,7 @@ Usage:
   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]
+  approval log unlock --pid <n|none> --as human:<id> [--json]
 
 Subcommands:
   verify   walk the hash chain end to end; clean | torn-tail | corrupt
@@ -417,11 +449,10 @@ Subcommands:
   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)
+  checkpoint / unlock  sign the head / take over a dead writer's lock (human-only)
 
-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}
+verify, tail, export, follow only read; sync, advance move the FILE; checkpoint, unlock append.
+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
@@ -544,6 +575,27 @@ hashes they replaced, which is what \`log verify --checkpoints\` then catches.
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
 ${why("log-checkpoint")}`;
+export const LOG_UNLOCK_HELP = `approval log unlock — take over a lock a dead writer left, by hand
+
+Usage:
+  approval log unlock --pid <n|none> --as human:<id> [--log <path>] [--json]
+
+Flags:
+  --pid <n|none>    the pid the lockfile names (a lock-timeout refusal prints
+                    it), or none for a lockfile that names no holder
+  --as human:<id>   who is unlocking; or set APPROVAL_HUMAN
+  --log <path>      log whose lock to take (default .approval/log/events.jsonl)
+  --json / -h, --help   machine-readable output / this text
+
+A writer takes a dead holder's lock back by itself only when it can prove the
+holder gone in its own pid namespace and boot. Run this for any other lock,
+once you know no writer is running: it takes the lock as a writer would and
+appends audit.lock_reclaimed under your name. It refuses a --pid that is not
+the lockfile's and a holder it sees running. HUMAN-ONLY.
+
+${EXIT_CODES_POINTER}
+${JSON_ERRORS}
+${why("log-unlock")}`;
 export const TAIL_HELP = `approval log tail — print the last records of the log
 
 Usage:
@@ -677,21 +729,21 @@ 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>]
-                         [--path <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 / -h, --help   machine-readable output / this text
 
-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.
+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
@@ -779,6 +831,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"
@@ -1012,7 +1103,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
@@ -1020,12 +1111,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")}`;
@@ -1066,9 +1157,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)
@@ -1126,7 +1217,7 @@ export const AUDIT_HELP = `approval audit — the retrospective review of sample
 
 Usage:
   approval audit list        [--all] [--log <path>] [--json]
-  approval audit review      <seq|action-key> [--deny] [--note "<text>"] […]
+  approval audit review      <seq|action-key> (--ok | --deny) [--note "<text>"] […]
   approval audit obligations [--all] [--log <path>] [--json]
   approval audit reconcile   <obligation-seq> --note "<text>" [--revert <key>] […]
 
@@ -1172,23 +1263,23 @@ ${why("audit-list")}`;
 export const AUDIT_REVIEW_HELP = `approval audit review — record that a human reviewed a sample
 
 Usage:
-  approval audit review <seq|action-key> [--deny] [--note "<text>"]
+  approval audit review <seq|action-key> (--ok | --deny) [--note "<text>"]
                         [--reaction <w>] [--as human:<id>] [--log <path>] [--json]
 
 Arguments:
-  <seq|action-key> a bare integer is the SEQ OF THE audit.sampled RECORD; any
-                   other value is an action key with one open sample
+  <seq|action-key> SEQ of the audit.sampled record, or a key with 1 open sample
 Flags:
+  --ok             this action should have happened. One of --ok/--deny REQUIRED
   --deny           this action should NOT have happened. Opens an obligation
   --note <text>    what you concluded. OPTIONAL, but loved/disliked REQUIRE it
   --reaction <w>   disliked|indifferent|liked|loved. GUIDANCE, never enforcement
   --as human:<id>  the reviewer; else APPROVAL_HUMAN. HUMAN-ONLY
   --log <path> / --json / -h, --help   the log / machine-readable output / help
 
-Appends audit.reviewed. NO ATTESTATION IS REQUIRED. Refuses (exit 1) not-sampled,
-already-reviewed, ambiguous-subject, actor-not-human, note-required and
-reaction-conflicts-verdict (--deny with liked or loved); log untouched. --deny
-ALSO appends reconciliation.required, shaped by the DECLARED reversible, not you.
+Refuses (exit 1), log untouched: actor-not-human, note-required, not-sampled,
+reaction-conflicts-verdict (--deny + liked/loved), already-reviewed,
+ambiguous-subject, actor-not-approver (reviewer or --as off the class's roster),
+policy-not-attested, policy-invalid, then verdict-required (no --ok or --deny).
 JSON: docs/cli-reference.md#audit-review
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
@@ -1319,14 +1410,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
@@ -1435,7 +1525,7 @@ ${why("quickstart")}`;
 export const HOOK_HELP = `approval hook — put the gate in front of an agent harness
 
 Usage:
-  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 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:
@@ -1444,16 +1534,16 @@ Commands:
   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:<harness>)
-  --timeout/--interval/--retry-grace <d>  wait / poll / hold for a retry (9m/1s/5m)
+  --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-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.
+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")}`;
@@ -1461,7 +1551,7 @@ export const HOOK_GROK_HELP = `approval hook grok — the gate in front of Grok
 
 Usage:
   approval hook grok [--as agent:<id>] [--timeout <d>] [--interval <d>]
-                     [--retry-grace <d>] [--policy <p>] [--dir <p>] [--log <p>]
+                     [--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,
@@ -1486,7 +1576,7 @@ export const HOOK_MUSE_HELP = `approval hook muse — the gate in front of Meta
 
 Usage:
   approval hook muse [--as agent:<id>] [--timeout <d>] [--interval <d>]
-                     [--retry-grace <d>] [--policy <p>] [--dir <p>] [--log <p>]
+                     [--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.
@@ -1507,6 +1597,31 @@ 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:
@@ -1548,12 +1663,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
@@ -1585,6 +1703,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:
@@ -1754,22 +1896,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 [--dir <path>] [--log <path>] [--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 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.
+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 — 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.
+records each decision against the attested person and refuses every other account.
 
 ${EXIT_CODES_POINTER}
 ${JSON_ERRORS}
@@ -1779,16 +1922,16 @@ export const TELEGRAM_LISTEN_HELP = `approval channel telegram listen — delive
 Usage:
   approval channel telegram listen [--once] [--as human:<id>] [--payloads <f>]
                                    [--policy <p>] [--dir <p>] [--log <p>] [--no-gloss]
-                                   [--gloss-provider <claude|codex>] [--gloss-model <id>] [--api-base <url>] [--poll-timeout <s>] [--json]
+                                   [--gloss-provider <claude|codex>] [--gloss-model <id>] [--api-base <url>] [--no-stale-copy] [--poll-timeout <s>] [--json]
 
 Flags:
-  --once / --json  one getUpdates batch then exit / ONE JSON OBJECT PER LINE
   --no-gloss / --gloss-provider <p>   drop gloss (ON by default) / choose claude|codex (default claude)
   --gloss-model <id>   model to request; required with Codex; no fallback
   --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> / --allow-cross-instance   Bot API base / long-poll seconds (25) / start on another instance's bot
+  --no-stale-copy / --once / --json   refuse a button this process is not holding (implied by any --api-base but the Bot API) / one getUpdates batch then exit / ONE JSON OBJECT PER LINE
   -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.
@@ -1798,6 +1941,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-stale-copy] [--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 / --no-stale-copy   register over the webhook already holding this bot / refuse a button this process is not holding (implied by any --api-base but the Bot API)
+  -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:
@@ -1869,13 +2060,13 @@ export const UP_HELP = `approval up — the daemon and every configured channel,
 
 Usage:
   approval up [every "daemon run" flag] [--as human:<id>] [--port <n>]
-              [--payloads <f>] [--payload-dir <d>] [--api-base <url>] [--poll-timeout <s>] [--no-gloss]
+              [--payloads <f>] [--payload-dir <d>] [--api-base <url>] [--no-stale-copy] [--poll-timeout <s>] [--no-gloss]
               [--gloss-provider <claude|codex>] [--gloss-model <id>] [--no-telegram] [--no-web] [--no-preflight] [--no-build]
 
 Flags (every "daemon run" flag, unchanged, plus):
   --as human:<id>  the approver every decision is recorded against
   --payloads <f> / --payload-dir <d>  payload overrides: telegram / web
-  --api-base <url> / --poll-timeout <s>   Bot API base / long-poll seconds
+  --api-base <url> / --poll-timeout <s> / --no-stale-copy   Bot API base / long-poll seconds / refuse a button this process is not holding (implied by any base but the Bot API)
   --port <n>       queue-page port. Precedence: --port, channels.web.port
   --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
@@ -2441,4 +2632,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