approval-md 0.2.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,12 +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).",
+        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,
@@ -554,6 +613,10 @@ const VERBS = [
             // repository-relative spelling the record carries, which is the
             // identity the guard matches on and is not derivable from `path`.
             organ_path: STRING,
+            // The same fact for the --path route, under its own name so that a
+            // reader of one object can never take a sign-off for an organ
+            // attestation: the two records are different claims (APRV-338).
+            signed_path: STRING,
         }, ["ok", "seq", "sha256", "path"]),
         error: ERROR_SCHEMA,
         exit_codes: BASE_EXIT_CODES,
@@ -606,6 +669,37 @@ const VERBS = [
         error: ERROR_SCHEMA,
         exit_codes: BASE_EXIT_CODES,
     },
+    {
+        name: "policy",
+        subcommand: "apply",
+        purpose: "Apply a proposal document's quoted Current/Replace-with pairs to APPROVAL.md and then run the amendment, so the edit and its attestation stay one act. It PUBLISHES by default (APRV-360): the amendment runs with --pr, so the branch is created on the remote by refspec, the pull request is opened and auto-merge is armed, and the checkout never moves; --no-publish stops at the commit and --pr is accepted as a no-op. HUMAN-ONLY twice over: an agent identity refuses `apply-agent-actor`, and the verb classifies `policy.core`, which the reference policy holds human-only. Every pair is resolved against an in-memory copy before a byte is written, so a stale proposal writes nothing at all; a whole-file replacement is not accepted, because every byte written is anchored to a byte proved present in the live file. Fences are read by their backtick run, so a wrapper fence around a block is the wrapper it is (APRV-273).",
+        human_only: true,
+        input: input({
+            positionals: positionals([{ name: "proposal", description: "the proposal document to apply" }], 1),
+            flags: {
+                ...POLICY_FLAGS,
+                ...LOG_FLAG,
+                ...AS_FLAG,
+                "--dry-run": "boolean",
+                "--no-amend": "boolean",
+                "--pr": "boolean",
+                "--no-publish": "boolean",
+                "--yes": "boolean",
+                ...JSON_FLAG,
+                ...HELP_FLAGS,
+            },
+        }),
+        output: object({
+            ok: { const: true },
+            policy: STRING,
+            proposal: STRING,
+            pairs: INTEGER,
+            noop: BOOLEAN,
+            dryRun: BOOLEAN,
+        }, ["ok", "policy", "proposal", "pairs", "noop", "dryRun"]),
+        error: ERROR_SCHEMA,
+        exit_codes: BASE_EXIT_CODES,
+    },
     {
         name: "register",
         purpose: "Validate a task file's `approval:` envelope against envelope.schema.json and append one task.registered event carrying the declared actions. FAIL CLOSED: an invalid envelope appends nothing. The file is read only. Registration is a proposal rather than a decision, so an agent may perform it, and it is the step that makes every later question about an action ('what class is this key?') answerable from the log.",
@@ -632,7 +726,7 @@ const VERBS = [
             flags: {
                 "--action": "string",
                 ...AS_FLAG,
-                "--payload": "string",
+                "--payload": "path",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...JSON_FLAG,
@@ -652,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.",
@@ -881,11 +1035,12 @@ const VERBS = [
     },
     {
         name: "sandbox",
-        purpose: "Run a command with outbound network denied by the operating system (macOS sandbox-exec), with the credential-bearing variables scrubbed out of its environment and the credential material beside the log unreadable to it. It exits with the child's own exit code and appends NOTHING: it removes a capability rather than authorizing anything, so there is no record to write and the gate stays reachable because its IPC is a file rather than a socket. This is what the hook cannot do for the commands it merely ALLOWS: `npm test` runs whatever an agent wrote a minute ago, so the command's name stopped describing its effect, and this is how such a command runs where its effects cannot leave. The classifier reads `approval sandbox -- <cmd>` as the class of <cmd>, so wrapping a command neither hides it from the gate nor is punished by it. Refuses with 127 on a machine with no sandbox primitive: it makes one promise and will not run a command it cannot keep that promise for. An agent HARNESS cannot run under this, because a harness needs the model API and that is exactly what is denied.",
+        purpose: "Run a command with outbound network denied by the operating system (macOS sandbox-exec), with the credential-bearing variables scrubbed out of its environment and the credential material beside the log unreadable to it. It exits with the child's own exit code and appends NOTHING: it removes a capability rather than authorizing anything, so there is no record to write and the gate stays reachable because its IPC is a file rather than a socket. This is what the hook cannot do for the commands it merely ALLOWS: `npm test` runs whatever an agent wrote a minute ago, so the command's name stopped describing its effect, and this is how such a command runs where its effects cannot leave. The classifier reads `approval sandbox -- <cmd>` as the class of <cmd>, so wrapping a command neither hides it from the gate nor is punished by it. Refuses with 127 on a machine with no sandbox primitive: it makes one promise and will not run a command it cannot keep that promise for. An agent HARNESS cannot run under this, because a harness needs the model API and that is exactly what is denied. Since APRV-347 it also confines what the child may READ: a policy declaring a `read_scope` block turns the profile deny-default for file reads and opens the gate root and whatever that block adds, and `--read-jail` applies the same confinement to one command whether the policy declares a block or not. There is no flag that turns the jail off where a policy asked for it.",
         human_only: false,
         input: input({
             flags: {
                 "--allow-loopback": "boolean",
+                "--read-jail": "boolean",
                 ...LOG_FLAG,
                 ...HELP_FLAGS,
             },
@@ -1126,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),
@@ -1144,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,
@@ -1158,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" },
@@ -1170,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",
+            },
         ],
     },
     {
@@ -1187,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],
@@ -1275,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),
@@ -1309,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",
@@ -1325,6 +1537,7 @@ const VERBS = [
             "coverage",
             "reconciliation",
             "payload_store",
+            "daemon",
         ]),
         error: ERROR_SCHEMA,
         exit_codes: [OK, { code: 1, meaning: "something needs attention" }, USAGE, IO],
@@ -1340,7 +1553,7 @@ const VERBS = [
                 "--since": "string",
                 "--until": "string",
                 "--source": "string",
-                "--vault": "string",
+                "--vault": "path",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...JSON_FLAG,
@@ -1389,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,
             },
@@ -1423,7 +1636,7 @@ const VERBS = [
             flags: {
                 ...LOG_FLAG,
                 "--policy-dir": "string",
-                "--policy": "string",
+                "--policy": "path",
                 "--payload-dir": "string",
                 ...AS_FLAG,
                 "--interactive": "boolean",
@@ -1502,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",
@@ -1511,8 +1746,8 @@ const VERBS = [
         input: input({
             flags: {
                 ...LOG_FLAG,
-                "--tasks": "string",
-                "--out": "string",
+                "--tasks": "path",
+                "--out": "path",
                 ...POLICY_FLAGS,
                 "--interval": "string",
                 "--debounce": "string",
@@ -1538,8 +1773,8 @@ const VERBS = [
         input: input({
             flags: {
                 ...LOG_FLAG,
-                "--tasks": "string",
-                "--out": "string",
+                "--tasks": "path",
+                "--out": "path",
                 ...POLICY_FLAGS,
                 "--interval": "string",
                 "--debounce": "string",
@@ -1579,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",
@@ -1630,7 +1892,7 @@ const VERBS = [
                 "--message": "string",
                 "--task": "string",
                 "--session": "string",
-                "--journal": "string",
+                "--journal": "path",
                 ...AS_FLAG,
                 ...JSON_FLAG,
                 ...HELP_FLAGS,
@@ -1706,7 +1968,7 @@ const VERBS = [
             flags: {
                 "--limit": "string",
                 "--since": "string",
-                "--journal": "string",
+                "--journal": "path",
                 ...JSON_FLAG,
                 ...HELP_FLAGS,
             },
@@ -1730,7 +1992,7 @@ const VERBS = [
     },
     {
         name: "values",
-        purpose: "Print the OPTIONAL values block of APPROVAL.md: what the operator loves, likes and dislikes, what they want from an agent as behaviour, and how they read and answer. It is HUMAN-AUTHORED GUIDANCE and it is never policy: it grants nothing, forbids nothing and changes no verdict, and no routing, class match, sampling draw, budget, token or execution decision reads it. Read it at the start of a session and weigh it in HOW you work; what you MAY do is the policy block, answered by `policy check`. A file with no values block exits 0 and says in words that the operator declared no values, which keeps a declared absence distinguishable from not having looked. A block that is present and unreadable exits 1 with its load code and is to be treated as absent. Resolves no policy rule, reads no log, writes nothing.",
+        purpose: "Print the OPTIONAL values block of APPROVAL.md: what the operator loves, likes (which is also where what they ask of an agent as behaviour lives) and dislikes, and how they read and answer. It is HUMAN-AUTHORED GUIDANCE and it is never policy: it grants nothing, forbids nothing and changes no verdict, and no routing, class match, sampling draw, budget, token or execution decision reads it. Read it at the start of a session and weigh it in HOW you work; what you MAY do is the policy block, answered by `policy check`. A file with no values block exits 0 and says in words that the operator declared no values, which keeps a declared absence distinguishable from not having looked. A block that is present and unreadable exits 1 with its load code and is to be treated as absent. Resolves no policy rule, reads no log, writes nothing.",
         human_only: false,
         human_only_note: "Human-AUTHORED and agent-FACING, which is the whole point: the block is the operator writing to the agent, so a surface that withheld it from agents would leave the words with no reader. It carries no authority in either direction. Nothing in it can widen what an agent may do, because no enforcement path reads it (SPEC.md §11.1 invariant 10), and an agent cannot write it: the block lives inside APPROVAL.md, which is `policy.core` and rides the whole-file attestation.",
         input: input({
@@ -1810,6 +2072,19 @@ const VERBS = [
         error: ERROR_SCHEMA,
         exit_codes: BASE_EXIT_CODES,
     },
+    {
+        name: "setup",
+        subcommand: "sender-key",
+        purpose: "Mint the operator-held key that turns a channel account id into the value an `approvers[id].senders` mapping carries (APRV-370), store it, and record where it lives. A published policy and a published log disclose the account otherwise, and a plain unkeyed digest would not fix that: a Telegram id is a short decimal number and the whole space is enumerable. It does not edit an attested policy. INTERACTIVE ONLY — except `--id <account-id>`, which mints and stores nothing and prints the `hmac-sha256:<hex>` mapping line for one account under the key already in the environment, so it runs anywhere.",
+        human_only: true,
+        human_only_note: "Minting it is minting the value every sender mapping is then written against, and an agent that could mint one could re-key the mapping and make every account in the policy unresolvable. The verb classifies policy.core. `--id` is a computation over a key the caller already holds and prints a value designed to be published, so it is not the human-only half.",
+        input: input({
+            flags: { "--id": "string", ...AS_FLAG, ...LOG_FLAG, ...POLICY_FLAGS, ...HELP_FLAGS },
+        }),
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: BASE_EXIT_CODES,
+    },
     {
         name: "setup",
         subcommand: "checkpoint",
@@ -1869,7 +2144,7 @@ const VERBS = [
                 "--logs": "string",
                 "--env-file": "string",
                 "--exec": "string",
-                "--out": "string",
+                "--out": "path",
                 "--uninstall": "boolean",
                 ...AS_FLAG,
                 ...LOG_FLAG,
@@ -1890,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,
@@ -1910,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,
@@ -1936,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,
@@ -1963,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",
@@ -2020,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",
@@ -2076,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,
             },
         }),
@@ -2100,6 +2375,7 @@ const VERBS = [
                 ...AS_FLAG,
                 "--timeout": "string",
                 "--interval": "string",
+                "--harness-cap": "string",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...HELP_FLAGS,
@@ -2123,6 +2399,7 @@ const VERBS = [
                 ...AS_FLAG,
                 "--timeout": "string",
                 "--interval": "string",
+                "--harness-cap": "string",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...HELP_FLAGS,
@@ -2147,6 +2424,7 @@ const VERBS = [
                 "--timeout": "string",
                 "--interval": "string",
                 "--retry-grace": "string",
+                "--harness-cap": "string",
                 ...POLICY_FLAGS,
                 ...LOG_FLAG,
                 ...HELP_FLAGS,
@@ -2159,6 +2437,81 @@ const VERBS = [
             { code: 2, meaning: "the hook is misconfigured or a PostToolUse outcome was not recorded; the diagnostic is on stderr" },
         ],
     },
+    {
+        name: "hook",
+        subcommand: "grok",
+        purpose: "Read one Grok Build PreToolUse event on stdin (camelCase keys), classify its Bash command and its Edit, Write, MultiEdit and NotebookEdit paths, resolve the class against APPROVAL.md, and answer {decision, reason} on stdout — waiting on a real decision when the class is manual. THE VERDICT IS NEVER 'ask'. A DENY IS EXIT 2, not exit 0 with a body: Grok reads the exit code, so the Claude dialect's exit-0 deny would be read as an allow, and Grok states that it reads .claude/settings.json for compatibility, which is how that dialect can fire under a Grok session in the first place. Exit 0 is an allow whatever stdout said.",
+        human_only: false,
+        human_only_note: "The agent harness surface, so agent-facing by construction: Grok Build invokes it around the agent's own tool calls. It records the agent's proposal and waits for a human; 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: "the tool call is allowed; the {decision, reason} object is on stdout" },
+            { code: 2, meaning: "the tool call is DENIED, or the hook is misconfigured; either way Grok blocks and reads the reason" },
+        ],
+    },
+    {
+        name: "hook",
+        subcommand: "muse",
+        purpose: "Read one Meta Muse Code PreToolUse or PostToolUse event on stdin (snake_case), classify its bash command or its write_file, read_file and search 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, the nested permissionDecision object at exit 0, because Muse treats output carrying any unsupported key as a failed hook and a failed hook FAILS OPEN. A Contributor-tier model is refused for every tool call regardless of policy (hook-muse-contributor-model): Meta trains on that tier's prompts and completions, so every read is a disclosure. Muse fails open on hook crash, timeout and malformed output, so this is enforcement only while the hook is healthy and answers inside the timeout the human commits.",
+        human_only: false,
+        human_only_note: "The agent harness surface, so agent-facing by construction: Muse 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: "the PreToolUse verdict (allow OR deny) is the JSON object on stdout, or a reported PostToolUse counterpart landed" },
+            { 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",
@@ -2180,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 },
@@ -2245,13 +2598,56 @@ const VERBS = [
         error: ERROR_SCHEMA,
         exit_codes: [OK, INTEGRITY, USAGE, IO],
     },
+    {
+        name: "codex",
+        subcommand: "apply",
+        purpose: "Apply one bounded typed workspace proposal through the gate (APRV-325.2). The manifest supplies the actor, workspace root, policy and log, and the proposal file supplies only operations and the policy digest it was built against; an unknown key is refused rather than ignored. One action is registered per distinct path class and never collapsed, every leg is authorized and started before any byte moves, and the change is staged, journaled and applied under a workspace lock. The outcome reported is what reading the workspace back proved: applied, not applied, or honestly unknown.",
+        human_only: true,
+        human_only_note: "The broker is reached by a constrained Codex session through `codex serve`, which publishes exactly one tool. Publishing this verb on the broad agent MCP catalog would put a second door beside that one, and the whole point of the strict server is that there is only the one.",
+        input: input({
+            flags: {
+                "--manifest": "string",
+                "--proposal": "string",
+                "--token": "string",
+                "--require-exclusive-custody": "boolean",
+                ...JSON_FLAG,
+                ...HELP_FLAGS,
+            },
+        }),
+        output: object({
+            ok: { const: true },
+            version: { const: "approval.codex.broker.v1" },
+            task: STRING,
+            payload_hash: SHA256,
+            policy_sha256: SHA256,
+            legs: arrayOf(object({ class: STRING, actionKey: STRING, mode: { enum: ["policy", "token"] } }, ["class", "actionKey", "mode"])),
+            custody: object({ kind: { enum: ["os-exclusive", "advisory"] }, findings: arrayOf(STRING) }, ["kind", "findings"]),
+            state: { const: "after" },
+        }, ["ok", "version", "task", "payload_hash", "policy_sha256", "legs", "custody", "state"]),
+        error: ERROR_SCHEMA,
+        exit_codes: [OK, INTEGRITY, USAGE, IO],
+    },
+    {
+        name: "codex",
+        subcommand: "recover",
+        purpose: "Read a workspace's retained transaction journal and report whether the workspace is in the approved before-state, the approved after-state, or neither. It changes nothing: a mixed workspace is a person's to reconcile, and a recovery that rolled one either way would be guessing which half was approved. Exits 1 on mixed.",
+        human_only: true,
+        human_only_note: "Reading a half-applied workspace is an operator's diagnosis and belongs beside the reconcile verb, which is human-only for the same reason.",
+        input: input({ flags: { "--manifest": "string", ...JSON_FLAG, ...HELP_FLAGS } }),
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: [OK, INTEGRITY, USAGE, IO],
+    },
     {
         name: "codex",
         subcommand: "start",
-        purpose: "Reserved constrained-session launcher. It refuses codex-not-ready until the policy-bound broker and confined runner ship.",
+        purpose: "Prepare a confined Codex session and, with `-- <command>`, run something inside it (APRV-325.3). The shell gets a disposable workspace that is the ONLY path it may write; the canonical workspace is readable and never writable; reads are jailed to exactly those two roots, so the gate home and everything else the host holds are unreadable; the environment is an allow-list rather than a filtered copy of the operator's; and outbound network is denied with loopback. There is no opt-out flag and no unwrapped fallback: a host with no sandbox mechanism refuses rather than running the shell and calling it confined. With no `-- <command>` it reports the room and runs nothing. Its exit code is the child's.",
         human_only: true,
         human_only_note: "Starting a constrained host session is an operator action and is absent from broad MCP.",
-        input: input({ flags: { "--manifest": "string", ...JSON_FLAG, ...HELP_FLAGS } }),
+        input: input({
+            flags: { "--manifest": "string", "--timeout": "string", ...JSON_FLAG, ...HELP_FLAGS },
+            trailing: TRAILING,
+        }),
         output: null,
         error: ERROR_SCHEMA,
         exit_codes: [OK, INTEGRITY, USAGE],
@@ -2259,13 +2655,37 @@ const VERBS = [
     {
         name: "codex",
         subcommand: "serve",
-        purpose: "Reserved strict MCP shim. It refuses codex-not-ready until the policy-bound broker and confined runner ship.",
+        purpose: "Serve the workspace broker over stdio as EXACTLY ONE MCP tool, `codex_workspace_apply`, with a positive server-side allowlist checked at call time as well as at list time. Distinct from `mcp serve`, whose catalog is this whole registry: a constrained session must reach one door and the same door next month. The published input schema carries no identity, path, class, token or sandbox argument, because none exists to remove.",
         human_only: true,
-        human_only_note: "The strict server is separate from and never published by the broad MCP server.",
-        input: input({ flags: { "--manifest": "string", ...JSON_FLAG, ...HELP_FLAGS } }),
+        human_only_note: "The strict server is separate from and never published by the broad MCP server; starting one is an operator's act, as `mcp serve` is.",
+        input: input({ flags: { "--manifest": "string", "--require-exclusive-custody": "boolean", ...JSON_FLAG, ...HELP_FLAGS } }),
         output: null,
         error: ERROR_SCHEMA,
-        exit_codes: [OK, INTEGRITY, USAGE],
+        exit_codes: [OK, INTEGRITY, USAGE, IO],
+    },
+    {
+        name: "codex",
+        subcommand: "bridge",
+        purpose: "Start `codex app-server` and answer every approval request it raises through the policy and the log (APRV-361). Each exec request carries `command` and `cwd` on one frame, minted by the harness runtime, which is the pair the native hook lacks and refuses for want of; the request goes through the hook's own decision path — classify, the human-only refusal, the loop floor, register, request, wait on the verified view — and the answer is `{id, result: {decision}}` on the connection. Accept or decline only, in the vocabulary the request advertised, never `acceptForSession`, `cancel` or `abort`. The deadline is the policy's `approval_ttl`, because this transport has no timeout. An ADVISORY checkpoint and never a boundary: see docs/codex-app-server-bridge.md.",
+        human_only: true,
+        human_only_note: "An OPERATOR process, like `codex serve`: it launches a long-lived server, holds the acting identity every answer is recorded under, and decides questions on a connection this transport owns. An agent that could start one would gain a second writer against the log nobody supervises.",
+        input: input({
+            flags: {
+                "--prompt": "string",
+                "--workspace": "string",
+                ...AS_FLAG,
+                ...POLICY_FLAGS,
+                ...LOG_FLAG,
+                "--wait": "string",
+                "--interval": "string",
+                ...JSON_FLAG,
+                ...HELP_FLAGS,
+            },
+            trailing: TRAILING,
+        }),
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: [OK, USAGE, IO],
     },
     {
         name: "mcp",
@@ -2294,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.",
@@ -2301,7 +2764,7 @@ const VERBS = [
         input: input({
             flags: {
                 ...LOG_FLAG,
-                "--index": "string",
+                "--index": "path",
                 "--force": "boolean",
                 ...JSON_FLAG,
                 ...HELP_FLAGS,
@@ -2316,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 },