approval-md 0.3.0 → 0.4.0

package/dist/src/cli/verb-registry.js

@@ -73,6 +73,29 @@ function object(properties, required) {
 /** An object whose keys are not enumerated here (a log record, a policy rule). */
 const OPEN_OBJECT = { type: "object" };
 const arrayOf = (items) => ({ type: "array", items });
+/**
+ * One refusal family in `approval status` (APRV-376): how many records the log
+ * carries, and the newest few of them, newest first.
+ *
+ * `code` is the surface's own refusal code, copied verbatim from the record, and
+ * it is spelled here as a plain string rather than an enum on purpose. The two
+ * closed vocabularies live at the write boundary (`schema/event.schema.json`) and
+ * in `core/decision-refusal.ts` and `core/gesture-refusal.ts`; a third copy in a
+ * REPORT schema would refuse to describe a log it was older than, which is the
+ * wrong failure direction for a field that authorizes nothing.
+ *
+ * `sender` is the account the gesture arrived from, when the record carries one,
+ * in the form the record carries it: `hashed` marks APRV-370's keyed digest, and
+ * it is present only when the record says so.
+ */
+const REFUSAL_FAMILY = object({
+    count: INTEGER,
+    recent: arrayOf(object({
+        seq: INTEGER,
+        code: STRING,
+        sender: object({ channel: STRING, id: STRING, hashed: BOOLEAN }, ["channel", "id"]),
+    }, ["seq", "code"])),
+}, ["count", "recent"]);
 /**
  * Positional arguments, named in order. `items: false` closes the tail: an
  * unexpected argument is a usage error in the CLI and is one here too.
@@ -91,18 +114,44 @@ function positionals(names, requiredCount) {
     };
 }
 const NO_POSITIONALS = { type: "array", maxItems: 0 };
-/** The argv after `--`, for the two verbs that take one. */
+/** The argv after `--`, for the verbs that take one. */
 const TRAILING = {
     type: "array",
     items: STRING,
     minItems: 1,
     description: "everything after the first `--`, passed through untouched",
 };
-/** Flags are `string | boolean` (see `args.ts`); nothing else can be parsed. */
+/**
+ * Path-typed flags, by the input schema they belong to (APRV-421).
+ *
+ * A flag declared `"path"` PUBLISHES as an ordinary `{"type":"string"}` — the
+ * wire contract is unchanged and no consumer sees a new keyword — while the
+ * registry retains the fact that its value NAMES A FILE. `approval serve`
+ * reads that through {@link pathFlagsOf} to confine such a value to the store
+ * the server was started for, so a flag added to this file tomorrow is
+ * confined on the day it appears rather than on the day somebody remembers to
+ * add it to a list kept somewhere else.
+ *
+ * A WeakMap keyed by the schema object, rather than a field on {@link VerbSpec},
+ * because `input()` returns that schema and all hundred-odd call sites would
+ * otherwise have to change to carry a second value.
+ */
+const PATH_FLAGS_BY_INPUT = new WeakMap();
+/** The flags of `spec` whose value names a filesystem path. */
+export function pathFlagsOf(spec) {
+    return PATH_FLAGS_BY_INPUT.get(spec.input) ?? [];
+}
+/**
+ * Flags are `string | boolean` (see `args.ts`); nothing else can be parsed.
+ * `path` is a `string` the registry knows more about — see above.
+ */
 function input(parts) {
     const flagProperties = {};
+    const pathFlags = [];
     for (const [flag, kind] of Object.entries(parts.flags)) {
-        flagProperties[flag] = kind === "string" ? STRING : BOOLEAN;
+        if (kind === "path")
+            pathFlags.push(flag);
+        flagProperties[flag] = kind === "boolean" ? BOOLEAN : STRING;
     }
     const properties = {
         positionals: parts.positionals ?? NO_POSITIONALS,
@@ -115,18 +164,20 @@ function input(parts) {
     };
     if (parts.trailing !== undefined)
         properties["trailing"] = parts.trailing;
-    return {
+    const schema = {
         type: "object",
         properties,
         required: [],
         additionalProperties: false,
     };
+    PATH_FLAGS_BY_INPUT.set(schema, pathFlags);
+    return schema;
 }
 /** Flags every command accepts. */
 const HELP_FLAGS = { "--help": "boolean", "-h": "boolean" };
 const JSON_FLAG = { "--json": "boolean" };
-const LOG_FLAG = { "--log": "string" };
-const POLICY_FLAGS = { "--policy": "string", "--dir": "string" };
+const LOG_FLAG = { "--log": "path" };
+const POLICY_FLAGS = { "--policy": "path", "--dir": "path" };
 const AS_FLAG = { "--as": "string" };
 /**
  * The shared failure shape. Usage and I/O failures print
@@ -253,6 +304,8 @@ const POLICY_RESOLUTION_OUTPUT = object({
         winner: BOOLEAN,
         tieBreak: STRING,
     }, ["pattern", "specificity", "autonomy", "winner", "tieBreak"])),
+    // APRV-445: may an agent open a request in this class with `propose`.
+    agentRequest: object({ allowed: BOOLEAN, explicit: BOOLEAN, pattern: nullable(STRING), humanOnly: BOOLEAN }, ["allowed", "explicit", "pattern", "humanOnly"]),
     decisionPath: arrayOf(STRING),
 }, [
     "class",
@@ -266,6 +319,7 @@ const POLICY_RESOLUTION_OUTPUT = object({
     "irreversibility",
     "irreversiblePatterns",
     "candidates",
+    "agentRequest",
     "decisionPath",
 ]);
 // ---------------------------------------------------------------------------
@@ -289,7 +343,7 @@ const VERBS = [
         purpose: "Scaffold a working directory: APPROVAL.md (SPEC.md §5.1's canonical policy, to be read and edited), the empty .approval/log/ directory, .approval/QUEUE.md in its empty state, and the .gitignore lines for the index, the vault, the environment source map and the atomic-write temp files. It appends nothing, attests nothing, and overwrites nothing; a re-run writes nothing and reports what already exists.",
         human_only: true,
         human_only_note: "It writes the policy file a human must then read and attest, in a directory a human chose. Nothing it writes is operative, but a scaffold an agent could drop into a tree is a policy file nobody decided to have.",
-        input: input({ flags: { "--dir": "string", ...JSON_FLAG, ...HELP_FLAGS } }),
+        input: input({ flags: { "--dir": "path", ...JSON_FLAG, ...HELP_FLAGS } }),
         output: object({
             ok: { const: true },
             dir: STRING,
@@ -305,7 +359,7 @@ const VERBS = [
         purpose: "Interactive solo setup: asks for a human id, terminal or Telegram, and five manual class families; writes a new policy and identity configuration, shows the exact bytes, requires typed understood, then attests. It classifies policy.core, refuses non-terminal input and --json, and never overwrites an existing policy.",
         human_only: true,
         human_only_note: "This command authors and attests APPROVAL.md and declares APPROVAL_HUMAN. It is reserved to a person at a terminal and is never exposed through MCP.",
-        input: input({ flags: { "--dir": "string", "--api-base": "string", ...HELP_FLAGS } }),
+        input: input({ flags: { "--dir": "path", "--api-base": "string", ...HELP_FLAGS } }),
         output: null,
         error: ERROR_SCHEMA,
         exit_codes: BASE_EXIT_CODES,
@@ -323,6 +377,9 @@ const VERBS = [
                 records: nullable(INTEGER),
                 head: HEAD,
                 intactThroughSeq: INTEGER,
+                tear: { enum: ["nul-filled", "partial-line"] },
+                tornBytes: INTEGER,
+                intactBytes: INTEGER,
                 firstBadSeq: nullable(INTEGER),
                 reason: STRING,
                 message: STRING,
@@ -533,13 +590,14 @@ const VERBS = [
     {
         name: "policy",
         subcommand: "attest",
-        purpose: "Record a human's sign-off on the policy file's exact bytes, as one policy.updated event carrying their SHA-256. Gate operations refuse while the live file is unattested or has changed since the last attestation, so an edited policy is inoperative until a human re-attests it. With --organ <path> it attests one of the gate's ORGANS instead — the harness files that install the hook — as one gate.organ.attested event no gate operation reads: those paths are human-only, so no grant for a hand edit to one can exist and this record is the only evidence the protected-path guard can accept (APRV-272). With --path <path> it signs off an ordinary PROTECTED path (policy.edit or a policy.edit.* sub-class) as one gate.path.signed_off event, which is what resolves SPEC.md's `(Amended APRV-n, pending sign-off.)` suffix: whole-file evidence that a human read those bytes, weaker than the hunk a grant binds, and read by the protected-path guard only after its grant search has failed (APRV-338). All three routes are human-only, refuse an agent actor with a machine-readable code, and compute their digest in the runtime.",
+        purpose: "Record a human's sign-off on the policy file's exact bytes, as one policy.updated event carrying their SHA-256. Gate operations refuse while the live file is unattested or has changed since the last attestation, so an edited policy is inoperative until a human re-attests it. With --organ <path> it attests one of the gate's ORGANS instead — the harness files that install the hook — as one gate.organ.attested event no gate operation reads: those paths are human-only, so no grant for a hand edit to one can exist and this record is the only evidence the protected-path guard can accept (APRV-272). With --path <path> it signs off an ordinary PROTECTED path (policy.edit or a policy.edit.* sub-class) as one gate.path.signed_off event, which is what resolves SPEC.md's `(Amended APRV-n, pending sign-off.)` suffix: whole-file evidence that a human read those bytes, weaker than the hunk a grant binds, and read by the protected-path guard only after its grant search has failed (APRV-338). All three routes are human-only, refuse an agent actor with a machine-readable code, and compute their digest in the runtime. With --bootstrap it attests a store's FIRST policy only, reading the verified log first: a re-run over the same bytes refuses policy-already-attested and changed bytes refuse policy-amendment-required, both at exit 1 with nothing appended, which is the operator's provisioning step for a tenant with no shell (APRV-449).",
         human_only: true,
         input: input({
             flags: {
                 ...POLICY_FLAGS,
                 "--organ": "string",
                 "--path": "string",
+                "--bootstrap": "boolean",
                 ...AS_FLAG,
                 ...LOG_FLAG,
                 ...JSON_FLAG,
@@ -668,7 +726,7 @@ const VERBS = [
             flags: {
                 "--action": "string",
                 ...AS_FLAG,
-                "--payload": "string",
+                "--payload": "path",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...JSON_FLAG,
@@ -688,6 +746,66 @@ const VERBS = [
         error: ERROR_SCHEMA,
         exit_codes: BASE_EXIT_CODES,
     },
+    {
+        name: "propose",
+        purpose: "Register and request ONE action in one call, with the payload inline as a JSON object (--payload-json, at most 262144 bytes) rather than a file, for a requester with no file on the gate's machine. Unlike request, the caller names the class, and that is bounded by the operator: the class must be an EXACT key of the policy's classes (a wildcard match does not count) and that key or a declared <prefix>.* family must set agent_may_request: true, else class-not-agent-requestable and nothing is written. --key MUST begin with <class>: (key-class-mismatch otherwise); consumers read the class from the record. --key is at most 1024 bytes and --summary at most 4096; lone surrogates and non-finite numbers are usage errors. The task id is derived from the actor, class and key (propose:<32 hex>), so a retry with the same class, key and bytes appends nothing and answers idempotent:true while the request is pending, usably granted, refused or executed (state executed); a request that can no longer be answered usefully (withdrawn, expired, a grant whose window lapsed, or one voided by a re-attested policy) is asked again by the same call. The same key with different bytes refuses duplicate-request while a request is live and payload-mismatch otherwise. decision requested: a human is asked, poll with wait <task> --timeout 0. decision autonomous or supervised: nothing is asked, act and then record it with start. The summary is stored in the log in cleartext; the payload is stored in the payload store, never in the log.",
+        human_only: false,
+        input: input({
+            flags: {
+                "--class": "string",
+                "--key": "string",
+                "--summary": "string",
+                "--payload-json": "string",
+                ...AS_FLAG,
+                ...POLICY_FLAGS,
+                ...LOG_FLAG,
+                ...JSON_FLAG,
+                ...HELP_FLAGS,
+            },
+        }),
+        output: object({
+            ok: { const: true },
+            task: STRING,
+            action_key: STRING,
+            class: STRING,
+            payload_hash: SHA256,
+            decision: { enum: ["requested", "autonomous", "supervised"] },
+            state: nullable({
+                enum: ["requested", "granted", "rejected", "revoked", "expired", "withdrawn", "executed"],
+            }),
+            seq: nullable(INTEGER),
+            idempotent: BOOLEAN,
+        }, ["ok", "task", "action_key", "class", "payload_hash", "decision", "state", "seq", "idempotent"]),
+        error: ERROR_SCHEMA,
+        exit_codes: BASE_EXIT_CODES,
+    },
+    {
+        name: "start",
+        purpose: "Record execution.started for a proposed action you are about to carry out yourself, once per key. Proposals only (task-not-proposal otherwise). REQUESTER-ONLY: the actor must be the one that registered the task. --payload-json is the bytes you are about to act on and must hash to the registered payload_hash. A key whose request is pending or granted-and-unspent spends its harness grant (refused unless granted, unexpired, unspent and under the policy it was asked under); a key with no such request (none, or one withdrawn, expired, rejected or revoked) is recorded as authorized by the policy (refused for a manual or human-only class). It grants nothing: it writes only what the grant or the policy already authorized, and a second start of the same key is already-executed.",
+        human_only: false,
+        input: input({
+            positionals: positionals([{ name: "task", description: "the task id propose returned" }], 1),
+            flags: {
+                "--action": "string",
+                "--payload-json": "string",
+                ...AS_FLAG,
+                ...POLICY_FLAGS,
+                ...LOG_FLAG,
+                ...JSON_FLAG,
+                ...HELP_FLAGS,
+            },
+        }),
+        output: object({
+            ok: { const: true },
+            task: STRING,
+            action_key: STRING,
+            class: STRING,
+            authorization: { enum: ["grant", "policy"] },
+            seq: INTEGER,
+        }, ["ok", "task", "action_key", "class", "authorization", "seq"]),
+        error: ERROR_SCHEMA,
+        exit_codes: BASE_EXIT_CODES,
+    },
     {
         name: "grant",
         purpose: "Record a human approval of a pending request and mint the single-use execution token for its action. The raw token is PRINTED ONCE here and stored nowhere: the log holds only its SHA-256, so nothing can recover it afterwards. Budgets are re-evaluated at grant time, because the moment that matters for a commitment is the moment the human commits.",
@@ -1163,7 +1281,7 @@ const VERBS = [
     },
     {
         name: "wait",
-        purpose: "Block until every approval.requested of a task has a decision, or the timeout elapses. THE EXIT CODE IS THE DECISION: 0 granted, 1 rejected, revoked or withdrawn, 3 expired, 6 timeout. It writes nothing by default, not even the expiry it may derive; --withdraw-on-timeout is the one exception, appending approval.withdrawn for the requests this actor opened so a question nobody can answer to does not sit in a human's queue. Only the manual path produces requests to wait for, so a task with none returns immediately at exit 0. Under policy token_delivery: sealed, a granted action's --json entry also carries the raw execution token, opened from the grant's ciphertext with the private key this machine kept when it opened the request; that removes the terminal paste and works across machines. Recovering a minted token is not minting one: it still exists only because a human granted it, still binds to the payload bytes, and is still single-use.",
+        purpose: "Block until every approval.requested of a task has a decision, or the timeout elapses. THE EXIT CODE IS THE DECISION: 0 granted (or nothing-to-wait-for, which `status` names and which is no grant), 1 rejected, revoked, withdrawn or not-registered, 3 expired (a grant whose request window lapsed included), 6 timeout, 7 void (a re-attest voided a pending request or a harness grant: ask again). It writes nothing by default, not even the expiry it may derive; --withdraw-on-timeout is the one exception, appending approval.withdrawn for the requests this actor opened so a question nobody can answer to does not sit in a human's queue. Only the manual path produces requests to wait for, so a registered task with none, or whose every grant an execution has already spent, returns immediately at exit 0 with status nothing-to-wait-for, NEVER granted; a task the log has never registered is refused not-registered at exit 1 (APRV-428). --timeout 0 reads the current state once and never sleeps (an undecided request answers timeout, exit 6, at once; it refuses --withdraw-on-timeout): use it to poll through approval serve, which runs every call through one queue that a sleeping wait would hold. Under policy token_delivery: sealed, a granted action's --json entry also carries the raw execution token, opened from the grant's ciphertext with the private key this machine kept when it opened the request; that removes the terminal paste and works across machines. Recovering a minted token is not minting one: it still exists only because a human granted it, still binds to the payload bytes, and is still single-use.",
         human_only: false,
         input: input({
             positionals: positionals([{ name: "task", description: "the task id" }], 1),
@@ -1181,7 +1299,18 @@ const VERBS = [
         output: object({
             ok: BOOLEAN,
             task: STRING,
-            status: { enum: ["granted", "rejected", "withdrawn", "expired", "timeout"] },
+            status: {
+                enum: [
+                    "granted",
+                    "executed",
+                    "rejected",
+                    "withdrawn",
+                    "void",
+                    "expired",
+                    "nothing-to-wait-for",
+                    "timeout",
+                ],
+            },
             actions: arrayOf(object({
                 action_key: STRING,
                 state: STRING,
@@ -1195,10 +1324,13 @@ const VERBS = [
         }, ["ok", "task", "status", "actions"]),
         error: ERROR_SCHEMA,
         exit_codes: [
-            { code: 0, meaning: "granted (a task with no requests is granted vacuously)" },
+            {
+                code: 0,
+                meaning: "granted; or executed on the policy's own authority after its request ended; or nothing-to-wait-for, a registered task with no requests or whose every grant is already spent. `status` says which, and only `granted` is a grant",
+            },
             {
                 code: 1,
-                meaning: "NOT AUTHORIZED and terminal — a human said no (rejected/revoked), or the requester withdrew the request; or the log is corrupt. `status` says which",
+                meaning: "NOT AUTHORIZED and terminal — a human said no (rejected/revoked), or the requester withdrew the request (`status` says which); or the task has no task.registered record (refusal `not-registered`); or the log is corrupt",
             },
             USAGE,
             { code: 3, meaning: "EXPIRED — the TTL lapsed before a decision landed; or a torn tail" },
@@ -1207,6 +1339,10 @@ const VERBS = [
                 code: 6,
                 meaning: "TIMEOUT — the wait elapsed with request(s) undecided. Nothing was appended, they are still live, and waiting again is legitimate",
             },
+            {
+                code: 7,
+                meaning: "VOID — the policy was re-attested since the request was routed, and the answer can never be used: a PENDING request (any task; no decision may land on it) or a HARNESS grant (execution: harness, every proposal included; its spend refuses policy-drift). A token grant for approval run is not void and reads granted. Ask again: for a proposal, the same propose call re-files",
+            },
         ],
     },
     {
@@ -1224,7 +1360,20 @@ const VERBS = [
                 requested_ts: STRING,
                 seq: INTEGER,
                 ttl_remaining_ms: nullable(INTEGER),
-            }, ["action_key", "task", "class", "est_cost_usd", "requested_ts", "seq", "ttl_remaining_ms"])),
+                // APRV-423: the whole window `ttl_remaining_ms` counts down from,
+                // which is the policy's TTL narrowed by the requesting hook's
+                // harness cap; null only when nothing bounds the request.
+                ttl_ms: nullable(INTEGER),
+            }, [
+                "action_key",
+                "task",
+                "class",
+                "est_cost_usd",
+                "requested_ts",
+                "seq",
+                "ttl_remaining_ms",
+                "ttl_ms",
+            ])),
         }, ["ok", "pending"]),
         error: ERROR_SCHEMA,
         exit_codes: [OK, USAGE, TORN, IO],
@@ -1312,13 +1461,15 @@ const VERBS = [
     },
     {
         name: "status",
-        purpose: "System HEALTH, from the log: attestation state, the latest chain verdict, dangling executions, indeterminate executions, budget headroom from a zero-cost probe, loop escalations, and the payload store's size. Exit 1 when any of those needs attention. `dangling` is executions the runtime meant to watch and did not, and never harness executions, which are terminal by design and gain no outcome; `indeterminate` is side effects that were attempted and whose fate nobody has established, and it appears only when there are some. This is what an operator must fix; `queue` is what a human must answer, and neither carries the other's content. Writes nothing.",
+        purpose: "System HEALTH, from the log: attestation state, the latest chain verdict, dangling executions, indeterminate executions, budget headroom from a zero-cost probe, loop escalations, and the payload store's size. Exit 1 when any of those needs attention. `dangling` is executions the runtime meant to watch and did not, and never harness executions, which are terminal by design and gain no outcome; `indeterminate` is side effects that were attempted and whose fate nobody has established, and it appears only when there are some. `refusals` counts the decisions and the gestures a decision surface would not take, with the newest few of each, and it appears only when the log carries one: it is informational, like `coverage`, because a refusal is the gate having worked. This is what an operator must fix; `queue` is what a human must answer, and neither carries the other's content. Writes nothing.",
         human_only: false,
         input: input({ flags: { ...POLICY_FLAGS, ...LOG_FLAG, ...JSON_FLAG, ...HELP_FLAGS } }),
         output: object({
             ok: { const: true },
             healthy: BOOLEAN,
-            attestation: object({ state: STRING, seq: nullable(INTEGER) }, ["state", "seq"]),
+            // APRV-449: `attested_by` is the actor of the attesting record at `seq`,
+            // read from the verified log, `null` when there is none. Always present.
+            attestation: object({ state: STRING, seq: nullable(INTEGER), attested_by: nullable(STRING) }, ["state", "seq", "attested_by"]),
             verification: object({ status: STRING, records: nullable(INTEGER) }, ["status", "records"]),
             dangling: arrayOf(OPEN_OBJECT),
             indeterminate: arrayOf(OPEN_OBJECT),
@@ -1346,10 +1497,34 @@ const VERBS = [
             reconciliation: arrayOf(OPEN_OBJECT),
             payload_store: OPEN_OBJECT,
             anomalies: arrayOf(OPEN_OBJECT),
+            // APRV-376: the two refusal families, counted, with the newest few of
+            // each. INFORMATIONAL and outside `healthy` and the exit code, exactly
+            // as `anomalies` and `coverage` are: a refusal is the gate having
+            // worked. Present only when the log carries one of either family, and
+            // each family present only when it has one, so a repository where
+            // nothing has been refused emits the object it always emitted. Neither
+            // is reported anywhere else short of `approval log tail`.
+            refusals: object({
+                decision: REFUSAL_FAMILY,
+                gesture: REFUSAL_FAMILY,
+            }, []),
             // APRV-214: present only while a window stands, so a repository with
             // none emits the object it always emitted. It counts toward `healthy`,
             // which is why it is reported here rather than only by `gate status`.
             gate_window: OPEN_OBJECT,
+            // APRV-383: the daemon identity this instance resolves — the id a daemon
+            // started HERE would write onto every record it appends, where the id
+            // came from, and the `daemons` allowlist in force for it. ALWAYS present,
+            // like `coverage`, so every consumer sees the same three keys on every
+            // log. INFORMATIONAL and outside `healthy` and the exit code: nothing
+            // here is a fact about this log's integrity. `id: null` is an
+            // `APPROVAL_DAEMON_ID` that is not an id; `allowed: null` is no
+            // restriction, which is not the same fact as an empty list.
+            daemon: object({
+                id: nullable(STRING),
+                source: nullable(STRING),
+                allowed: { anyOf: [{ type: "array", items: STRING }, { type: "null" }] },
+            }, ["id", "source", "allowed"]),
         }, [
             "ok",
             "healthy",
@@ -1362,6 +1537,7 @@ const VERBS = [
             "coverage",
             "reconciliation",
             "payload_store",
+            "daemon",
         ]),
         error: ERROR_SCHEMA,
         exit_codes: [OK, { code: 1, meaning: "something needs attention" }, USAGE, IO],
@@ -1377,7 +1553,7 @@ const VERBS = [
                 "--since": "string",
                 "--until": "string",
                 "--source": "string",
-                "--vault": "string",
+                "--vault": "path",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...JSON_FLAG,
@@ -1426,9 +1602,9 @@ const VERBS = [
             flags: {
                 ...LOG_FLAG,
                 ...POLICY_FLAGS,
-                "--tasks": "string",
+                "--tasks": "path",
                 "--api-base": "string",
-                "--root": "string",
+                "--root": "path",
                 ...JSON_FLAG,
                 ...HELP_FLAGS,
             },
@@ -1460,7 +1636,7 @@ const VERBS = [
             flags: {
                 ...LOG_FLAG,
                 "--policy-dir": "string",
-                "--policy": "string",
+                "--policy": "path",
                 "--payload-dir": "string",
                 ...AS_FLAG,
                 "--interactive": "boolean",
@@ -1539,6 +1715,28 @@ const VERBS = [
         error: ERROR_SCHEMA,
         exit_codes: [OK, { code: 1, meaning: "a credential variable is unset" }, USAGE],
     },
+    {
+        name: "channel",
+        subcommand: "relay",
+        purpose: "Serve POST /relay/gesture on loopback for an operator's control plane (APRV-455): propose, attest or decline a policy by sha256, or grant or reject a request by action key, attributed to the EdgeOS account the attested policy maps. Authenticated by APPROVAL_RELAY_SECRET from the launch environment; a post without it is refused and never logged. It holds no human identity: an unmapped account is refused sender-unmapped. The raw execution token of a grant never leaves the process.",
+        human_only: true,
+        human_only_note: "It records human decisions and attestations on the word of whoever holds a secret its launcher chose, so starting it is the operator's ceremony: no wrapper publishes it, neither serve credential reaches it, and the hook classifier holds the command line `policy.core` (human-only in the reference policy). The attribution it records is exactly as strong as control over who launches it.",
+        input: input({
+            flags: {
+                "--listen": "string",
+                "--port": "string",
+                "--allow-non-loopback": "boolean",
+                "--proposer": "string",
+                ...POLICY_FLAGS,
+                ...LOG_FLAG,
+                ...JSON_FLAG,
+                ...HELP_FLAGS,
+            },
+        }),
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: BASE_EXIT_CODES,
+    },
     {
         name: "daemon",
         subcommand: "run",
@@ -1548,8 +1746,8 @@ const VERBS = [
         input: input({
             flags: {
                 ...LOG_FLAG,
-                "--tasks": "string",
-                "--out": "string",
+                "--tasks": "path",
+                "--out": "path",
                 ...POLICY_FLAGS,
                 "--interval": "string",
                 "--debounce": "string",
@@ -1575,8 +1773,8 @@ const VERBS = [
         input: input({
             flags: {
                 ...LOG_FLAG,
-                "--tasks": "string",
-                "--out": "string",
+                "--tasks": "path",
+                "--out": "path",
                 ...POLICY_FLAGS,
                 "--interval": "string",
                 "--debounce": "string",
@@ -1616,6 +1814,33 @@ const VERBS = [
         error: ERROR_SCHEMA,
         exit_codes: READ_ONLY_EXIT_CODES,
     },
+    {
+        name: "payload",
+        subcommand: "run",
+        purpose: "Print the payload `approval run` will recompute for a command before it spawns it: the argv, the cwd, and — since APRV-401 — the size and SHA-256 of the script that argv names, so a grant over a script binds the SCRIPT'S BYTES and not its path. A script is a known interpreter (the shells, node, python3 and kin) followed by a path operand, or a path at argv[0] the kernel reads a shebang from. With --hash it prints the payload_hash instead, the value a task file's declaration carries. An argv naming no script carries no `script` key and hashes exactly as it did before the rule existed. An inline program is already in the argv; the interpreter itself, a launcher this runtime does not name, whatever the script itself reads or runs, and the window between this hash and the spawn are all outside the binding. Reads that one file and nothing else: no log, no policy, no network, no token, and it executes nothing.",
+        human_only: false,
+        human_only_note: "Agent-facing by construction: it describes a command an agent is about to ask permission for, before any approval exists, and produces no authority of any kind. The bytes it prints are checked at intake and recomputed at execution, so a wrong answer here refuses rather than widens.",
+        input: input({
+            positionals: NO_POSITIONALS,
+            flags: {
+                // Path-typed, and it matters: the value is the directory every relative
+                // argv word is resolved against, so a caller who could name any
+                // directory could ask this verb to digest any file under it.
+                "--cwd": "path",
+                "--hash": "boolean",
+                ...JSON_FLAG,
+                ...HELP_FLAGS,
+            },
+            trailing: TRAILING,
+        }),
+        // The canonical payload itself on stdout, as `agentmail-draft` does it: the
+        // bytes ARE the result, and an envelope around them would be a second thing
+        // to strip before hashing. `--hash --json` prints {ok, hash}, which is the
+        // one shape here that is a RESULT rather than the payload.
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: READ_ONLY_EXIT_CODES,
+    },
     {
         name: "payload",
         subcommand: "agentmail-draft",
@@ -1667,7 +1892,7 @@ const VERBS = [
                 "--message": "string",
                 "--task": "string",
                 "--session": "string",
-                "--journal": "string",
+                "--journal": "path",
                 ...AS_FLAG,
                 ...JSON_FLAG,
                 ...HELP_FLAGS,
@@ -1743,7 +1968,7 @@ const VERBS = [
             flags: {
                 "--limit": "string",
                 "--since": "string",
-                "--journal": "string",
+                "--journal": "path",
                 ...JSON_FLAG,
                 ...HELP_FLAGS,
             },
@@ -1919,7 +2144,7 @@ const VERBS = [
                 "--logs": "string",
                 "--env-file": "string",
                 "--exec": "string",
-                "--out": "string",
+                "--out": "path",
                 "--uninstall": "boolean",
                 ...AS_FLAG,
                 ...LOG_FLAG,
@@ -1940,7 +2165,7 @@ const VERBS = [
             positionals: positionals([{ name: "name", description: "the credential name" }], 1),
             flags: {
                 "--value-env": "string",
-                "--vault": "string",
+                "--vault": "path",
                 ...LOG_FLAG,
                 ...POLICY_FLAGS,
                 ...AS_FLAG,
@@ -1960,7 +2185,7 @@ const VERBS = [
         human_only_note: "Names are not values, but the name set is a map of the machine's reach, and all three vault verbs resolve identity exactly as `policy attest` does. Keeping the noun human-only is what stops an agent's tooling from touching the credential store in passing.",
         input: input({
             flags: {
-                "--vault": "string",
+                "--vault": "path",
                 ...LOG_FLAG,
                 ...POLICY_FLAGS,
                 ...AS_FLAG,
@@ -1986,7 +2211,7 @@ const VERBS = [
         input: input({
             positionals: positionals([{ name: "name", description: "the credential name" }], 1),
             flags: {
-                "--vault": "string",
+                "--vault": "path",
                 ...LOG_FLAG,
                 ...POLICY_FLAGS,
                 ...AS_FLAG,
@@ -2013,9 +2238,9 @@ const VERBS = [
             positionals: positionals([{ name: "action-key", description: "the action's idempotency_key" }], 1),
             flags: {
                 "--token": "string",
-                "--payload": "string",
+                "--payload": "path",
                 ...AS_FLAG,
-                "--vault": "string",
+                "--vault": "path",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 "--timeout": "string",
@@ -2070,9 +2295,9 @@ const VERBS = [
             positionals: positionals([{ name: "action-key", description: "the action's idempotency_key" }], 1),
             flags: {
                 "--token": "string",
-                "--payload": "string",
+                "--payload": "path",
                 ...AS_FLAG,
-                "--vault": "string",
+                "--vault": "path",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 "--timeout": "string",
@@ -2126,7 +2351,7 @@ const VERBS = [
         input: input({
             positionals: positionals([{ name: "action-key", description: "the action's idempotency_key" }], 1),
             flags: {
-                "--token": "string", "--payload": "string", ...AS_FLAG, "--vault": "string",
+                "--token": "string", "--payload": "path", ...AS_FLAG, "--vault": "path",
                 ...POLICY_FLAGS, ...LOG_FLAG, "--timeout": "string", ...JSON_FLAG, ...HELP_FLAGS,
             },
         }),
@@ -2150,6 +2375,7 @@ const VERBS = [
                 ...AS_FLAG,
                 "--timeout": "string",
                 "--interval": "string",
+                "--harness-cap": "string",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...HELP_FLAGS,
@@ -2173,6 +2399,7 @@ const VERBS = [
                 ...AS_FLAG,
                 "--timeout": "string",
                 "--interval": "string",
+                "--harness-cap": "string",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...HELP_FLAGS,
@@ -2197,6 +2424,7 @@ const VERBS = [
                 "--timeout": "string",
                 "--interval": "string",
                 "--retry-grace": "string",
+                "--harness-cap": "string",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...HELP_FLAGS,
@@ -2221,6 +2449,7 @@ const VERBS = [
                 "--timeout": "string",
                 "--interval": "string",
                 "--retry-grace": "string",
+                "--harness-cap": "string",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...HELP_FLAGS,
@@ -2245,6 +2474,7 @@ const VERBS = [
                 "--timeout": "string",
                 "--interval": "string",
                 "--retry-grace": "string",
+                "--harness-cap": "string",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...HELP_FLAGS,
@@ -2257,6 +2487,31 @@ const VERBS = [
             { code: 2, meaning: "the hook is misconfigured or a PostToolUse outcome was not recorded; the diagnostic is on stderr" },
         ],
     },
+    {
+        name: "hook",
+        subcommand: "hermes",
+        purpose: "Read one Hermes Agent pre_tool_call or post_tool_call event on stdin (snake_case, and the event names are its own rather than Claude Code's), classify its terminal command or its write_file and patch paths and its read paths, resolve the class against APPROVAL.md, and answer allow or deny — waiting on a real decision when the class is manual. THE VERDICT IS NEVER 'ask'. It answers in ONE dialect and nothing else, Hermes's own {action, message} object: a deny is that object AT EXIT 2, which Hermes documents as an unconditional block whose message it reads from the stdout directive first (so body and code agree by the harness's own rule, and a refusal whose body never made it out still blocks); an allow is {} at exit 0, because Hermes has no allow directive and no directive is the allow, so the allow's reason goes to stderr. The Claude-compatible {decision, reason} form is never emitted beside it, because Muse established that a refusal hedged across dialects is read as a broken hook rather than as a stronger no. execute_code is refused outright (hook-hermes-execute-code-unbound): the call carries a program and no path, no argv and no working directory, so no class can be resolved and no payload can bind what it would do. A terminal call that names no absolute workdir, and a write_file, patch, read_file or search_files call whose path is relative or absent, are refused too (hook-unsupported-execution-context, APRV-415): the live probe found that Hermes resolves both against a per-session recorded directory that a cd moves and that no field of the event carries, so the verdict would bind bytes in a directory the hook cannot see, and the refusal names the retry — an absolute path — so the session repairs itself. A per-entry fail_closed makes a hook crash, timeout or unparseable output BLOCK, which the same probe OBSERVED on Hermes main at 118984d7 in three trials of three, making this the first harness since Claude Code whose hook is a gate rather than a backstop; its default is false and v0.21.3 (build 2026.9.14) ignores the key silently, so docs/hermes-hook.md states the version floor before it states anything else and approval doctor's harness-version row reports a build below it.",
+        human_only: false,
+        human_only_note: "The agent harness surface, so agent-facing by construction: Hermes invokes it around the agent's own tool calls. It proposes and waits; it never records a decision.",
+        input: input({
+            flags: {
+                ...AS_FLAG,
+                "--timeout": "string",
+                "--interval": "string",
+                "--retry-grace": "string",
+                "--harness-cap": "string",
+                ...POLICY_FLAGS,
+                ...LOG_FLAG,
+                ...HELP_FLAGS,
+            },
+        }),
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: [
+            { code: 0, meaning: "an allow ({} on stdout, the reason on stderr), and every post_tool_call report, which exits 0 whatever it found because Hermes reads exit 2 as a block and the call has already run" },
+            { code: 2, meaning: "a deny: the {action:'block', message} object on stdout is the message and the exit code is the unconditional block under it; also a usage error before any event was read, which prints no verdict" },
+        ],
+    },
     {
         name: "hook",
         subcommand: "classify",
@@ -2278,7 +2533,7 @@ const VERBS = [
         human_only: false,
         input: input({
             positionals: positionals([{ name: "file", description: "the markdown file to parse" }], 1),
-            flags: { "--out": "string", ...JSON_FLAG, ...HELP_FLAGS },
+            flags: { "--out": "path", ...JSON_FLAG, ...HELP_FLAGS },
         }),
         output: object({
             ok: { const: true },
@@ -2459,6 +2714,49 @@ const VERBS = [
             { code: 4, meaning: "the transport did not close cleanly" },
         ],
     },
+    {
+        name: "serve",
+        purpose: "Serve the verbs of this registry over HTTP, in the foreground, for a harness in a sandbox that has no local log and no local policy. The published surface is `mcp serve`'s exactly — the registry filtered by human_only false, `--as` deleted from every schema, the launch identity appended last, no grant — plus the three things the MCP transport withheld for transport reasons: `hook/<harness>` taking the harness envelope as the request body and answering the bytes the stdin form prints, `log/follow` paged by an exclusive (seq, hash) cursor, and `export`, the store as an archive carrying the policy, the log, the payload bytes behind every payload_hash and the projections, and never the keys, the environment source map or the vault. TWO bearer credentials come 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 in order 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 and a verb added to this registry is the tenant's until somebody widens the list. Binds loopback unless an explicit flag widens it; it terminates no TLS.",
+        human_only: true,
+        human_only_note: "An OPERATOR process, for `mcp serve`'s reason and one more. It is long-lived, launched by a person, and holds the agent identity every call is recorded under; on top of that it holds BOTH credentials, and the party that decides which door an agent gets is not the agent.",
+        input: input({
+            flags: {
+                ...AS_FLAG,
+                "--port": "string",
+                "--listen": "string",
+                "--allow-non-loopback": "boolean",
+                "--hook-timeout": "string",
+                "--hook-harness-cap": "string",
+                "--hook-threads": "string",
+                "--hook-queue": "string",
+                ...POLICY_FLAGS,
+                ...LOG_FLAG,
+                ...JSON_FLAG,
+                ...HELP_FLAGS,
+            },
+        }),
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: [
+            { code: 0, meaning: "the server was interrupted and closed cleanly" },
+            USAGE,
+            { code: 4, meaning: "the listener could not bind, or did not close cleanly" },
+        ],
+    },
+    {
+        name: "muse",
+        purpose: "Start the single-tenant local Muse consumer prototype. It exposes bounded register and request proposals plus a verified pending inbox, status and canonical request detail, with distinct read and proposal launch credentials. It has no human decision, token, execution, export or generic verb route; the configured Telegram channel remains the human decision path.",
+        human_only: true,
+        human_only_note: "An operator launches this credential-holding listener and pins its tenant and store before accepting calls.",
+        input: input({ flags: { "--dir": "path", "--port": "string", ...HELP_FLAGS } }),
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: [
+            { code: 0, meaning: "the local listener was interrupted and closed cleanly" },
+            USAGE,
+            { code: 4, meaning: "the local listener could not bind" },
+        ],
+    },
     {
         name: "reindex",
         purpose: "Rebuild the SQLite index projection from the log. The database is a cache and the log is the truth: the index is rebuilt from scratch at a temporary path and renamed into place. A corrupt log is refused outright and a torn tail is refused without --force. The log is never written to.",
@@ -2466,7 +2764,7 @@ const VERBS = [
         input: input({
             flags: {
                 ...LOG_FLAG,
-                "--index": "string",
+                "--index": "path",
                 "--force": "boolean",
                 ...JSON_FLAG,
                 ...HELP_FLAGS,
@@ -2481,7 +2779,7 @@ const VERBS = [
         purpose: "Regenerate .approval/QUEUE.md, the read-only markdown queue projection of SPEC.md §9.1, whole, from the verified log. This is the screenshot and never the truth: editing the file authorizes nothing and the next render overwrites it. Writes exactly one file, atomically; a log that does not verify refuses and writes nothing.",
         human_only: false,
         input: input({
-            flags: { ...LOG_FLAG, "--out": "string", ...POLICY_FLAGS, ...JSON_FLAG, ...HELP_FLAGS },
+            flags: { ...LOG_FLAG, "--out": "path", ...POLICY_FLAGS, ...JSON_FLAG, ...HELP_FLAGS },
         }),
         output: object({
             ok: { const: true },