approval-md 0.1.0 → 0.3.0

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

@@ -217,7 +217,16 @@ const POLICY_RESOLUTION_OUTPUT = object({
         liveRate: nullable(NUMBER),
         approvers: nullable(arrayOf(STRING)),
         limits: nullable(OPEN_OBJECT),
-    }, ["autonomy", "declaredAutonomy", "supervision", "liveRate", "approvers", "limits"]),
+        allowIrreversible: BOOLEAN,
+    }, [
+        "autonomy",
+        "declaredAutonomy",
+        "supervision",
+        "liveRate",
+        "approvers",
+        "limits",
+        "allowIrreversible",
+    ]),
     // `inherited` since APRV-266: a `policy.edit` sub-class the policy declares
     // no rule for, decided by the `policy.edit` line it is a sub-class of.
     provenance: { enum: ["rule", "default", "inherited", "fail-closed", "floor"] },
@@ -227,6 +236,16 @@ const POLICY_RESOLUTION_OUTPUT = object({
     loadFailure: nullable(object({ code: STRING, message: STRING }, ["code", "message"])),
     matched: nullable(object({ pattern: STRING, rule: OPEN_OBJECT }, ["pattern", "rule"])),
     overridden: nullable(object({ pattern: nullable(STRING), autonomy: STRING }, ["pattern", "autonomy"])),
+    irreversibility: {
+        enum: [
+            "not-applicable",
+            "policy-allowed",
+            "floor-applied",
+            "already-manual",
+            "human-only",
+        ],
+    },
+    irreversiblePatterns: arrayOf(STRING),
     candidates: arrayOf(object({
         pattern: STRING,
         specificity: { type: "array", items: INTEGER, minItems: 3, maxItems: 3 },
@@ -244,6 +263,8 @@ const POLICY_RESOLUTION_OUTPUT = object({
     "loadFailure",
     "matched",
     "overridden",
+    "irreversibility",
+    "irreversiblePatterns",
     "candidates",
     "decisionPath",
 ]);
@@ -279,6 +300,16 @@ const VERBS = [
         error: ERROR_SCHEMA,
         exit_codes: BASE_EXIT_CODES,
     },
+    {
+        name: "quickstart",
+        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 } }),
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: BASE_EXIT_CODES,
+    },
     {
         name: "log",
         subcommand: "verify",
@@ -333,6 +364,32 @@ const VERBS = [
         error: ERROR_SCHEMA,
         exit_codes: [OK, { code: 1, meaning: "the log is corrupt; nothing was printed" }, USAGE, TORN, IO],
     },
+    {
+        name: "log",
+        subcommand: "follow",
+        purpose: "Emit one JSON event per line after an exclusive sequence cursor, then follow appends. Every batch is verified from genesis before emission; filesystem notifications only prompt another read. The optional cursor hash binds a resume to the retained prefix. This foreground stream is intentionally excluded from MCP's finite call queue.",
+        human_only: false,
+        input: input({
+            flags: {
+                ...LOG_FLAG,
+                "--from": "string",
+                "--cursor-hash": "string",
+                ...JSON_FLAG,
+                ...HELP_FLAGS,
+            },
+        }),
+        // A stream has no single finite output object for registry/MCP purposes.
+        // Each stdout line is a RECORD, pinned by the CLI end-to-end test.
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: [
+            { code: 0, meaning: "cancelled by a signal or downstream pipe closure" },
+            { code: 1, meaning: "corrupt log or cursor mismatch" },
+            USAGE,
+            TORN,
+            IO,
+        ],
+    },
     // APRV-125. The two verbs that move the log FILE. `human_only` is false on
     // both: an agent may run them, and the policy decides whether it may — they
     // classify as `log.sync` and `log.advance` rather than as the gate's own
@@ -396,6 +453,7 @@ const VERBS = [
                 "--remote": "string",
                 "--branch": "string",
                 "--pr": "boolean",
+                "--co-author": "string",
                 "--dry-run": "boolean",
                 ...JSON_FLAG,
                 ...HELP_FLAGS,
@@ -441,7 +499,7 @@ const VERBS = [
     {
         name: "policy",
         subcommand: "check",
-        purpose: "Explain what APPROVAL.md does with one action class: the resolved autonomy, the rule that matched, every candidate with its specificity, and the decision path that produced the answer. Nothing is executed, requested or logged. A policy that fails to load is not an error here: a broken policy IS a manual-everything policy, and that answer is delivered on stdout at exit 0, so branch on manualBecause and provenance rather than on the exit code.",
+        purpose: "Explain what APPROVAL.md does with one action class: the resolved autonomy, the rule that matched, every candidate with its specificity, the unanimous max-specificity allow_irreversible decision, and the decision path that produced the answer. Nothing is executed, requested or logged. A policy that fails to load is not an error here: a broken policy IS a manual-everything policy, and that answer is delivered on stdout at exit 0, so branch on manualBecause and provenance rather than on the exit code.",
         human_only: false,
         input: input({
             positionals: positionals([{ name: "class", description: "a concrete action class, e.g. vcs.push.main" }], 1),
@@ -475,12 +533,13 @@ 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.",
         human_only: true,
         input: input({
             flags: {
                 ...POLICY_FLAGS,
                 "--organ": "string",
+                "--path": "string",
                 ...AS_FLAG,
                 ...LOG_FLAG,
                 ...JSON_FLAG,
@@ -496,6 +555,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,
@@ -548,6 +611,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.",
@@ -823,11 +917,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,
             },
@@ -1672,7 +1767,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({
@@ -1752,6 +1847,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",
@@ -1898,9 +2006,9 @@ const VERBS = [
     {
         name: "adapter",
         subcommand: "email",
-        purpose: "Execute one approved action through the email adapter: send a single RFC 5322 message over SMTP for a communicate.email.external action. The runtime — not the adapter — recomputes the payload hash, spends the token, and writes both execution events around the send, and the credentials leave the vault only inside that verified-token window. This is the hard boundary of SPEC.md §10.4.",
+        purpose: "Execute one action through the email adapter: send a single RFC 5322 message over SMTP for a communicate.email.external action. The runtime recomputes the payload hash, applies attested policy, and writes both execution events around the send. Manual and selected-live paths spend a grant token; an explicitly policy-authorized supervised or autonomous path has no token. Credentials leave the vault only inside the execution window. This is the hard boundary of SPEC.md §10.4.",
         human_only: false,
-        human_only_note: "Agent-facing on purpose. It executes inside the token window with a token a human granted for these exact bytes, which is the authority an executing agent is meant to hold; the adapter refuses everything else. Making it human-only would move the send back to a human and leave the token doing nothing.",
+        human_only_note: "Agent-facing on purpose. Manual and selected-live execution uses a token a human granted for these exact bytes. Explicitly opted-in supervised and autonomous execution follows attested policy without minting a token. The adapter refuses every path the core does not admit.",
         input: input({
             positionals: positionals([{ name: "action-key", description: "the action's idempotency_key" }], 1),
             flags: {
@@ -1949,15 +2057,15 @@ const VERBS = [
             USAGE,
             TORN,
             IO,
-            { code: 5, meaning: "no valid execution token; nothing was appended and nothing was sent" },
+            { code: 5, meaning: "the effective manual path needs a valid execution token; nothing was appended and nothing was sent" },
         ],
     },
     {
         name: "adapter",
         subcommand: "agentmail",
-        purpose: "Execute one approved action through the AgentMail adapter: a direct send over the AgentMail API, or the send of a draft the agent already composed. The draft mode re-reads the draft and refuses `agentmail-draft-drifted` when any approved field changed, because a grant is over a snapshot of the words and not over a mutable draft id. AgentMail has no per-message From — the inbox is the sender — so the approved `from` is checked against the inbox's own address before anything is sent. The runtime, not the adapter, recomputes the payload hash, spends the token and writes both execution events, and the vault's sending key leaves it only inside that window.",
+        purpose: "Execute one action through the AgentMail adapter: a direct send over the AgentMail API, or the send of a draft the agent already composed. The draft mode re-reads the draft and refuses `agentmail-draft-drifted` when any bound field changed, because authority covers a snapshot of the words and not a mutable draft id. AgentMail has no per-message From — the inbox is the sender — so the bound `from` is checked against the inbox's own address before anything is sent. The runtime recomputes the payload hash, applies attested policy and writes both execution events. Manual and selected-live paths spend a grant token; explicitly opted-in supervised and autonomous paths do not mint one.",
         human_only: false,
-        human_only_note: "Agent-facing for the reason `adapter email` is: it executes inside the token window with a token a human granted for these exact bytes. The split that makes it safe is in the keys, not in the caller — the agent's own AgentMail key cannot send, and the one that can lives in the vault.",
+        human_only_note: "Agent-facing for the reason `adapter email` is. Manual and selected-live paths use a token granted for the exact bytes; explicitly opted-in supervised and autonomous paths follow attested policy without one. The split that makes it safe is in the keys: the agent's own AgentMail key cannot send, and the one that can lives in the vault.",
         input: input({
             positionals: positionals([{ name: "action-key", description: "the action's idempotency_key" }], 1),
             flags: {
@@ -2006,9 +2114,31 @@ const VERBS = [
             USAGE,
             TORN,
             IO,
-            { code: 5, meaning: "no valid execution token; nothing was appended and nothing was sent" },
+            { code: 5, meaning: "the effective manual path needs a valid execution token; nothing was appended and nothing was sent" },
         ],
     },
+    {
+        name: "adapter",
+        subcommand: "zzz",
+        purpose: "Execute one zzz.bot create-thread or create-reply action. The tagged payload selects a fixed production or preview origin and binds the destination, body, metadata, tags and references. The runtime applies attested policy before the write-capable Bearer token leaves the vault. Manual and selected-live paths spend a grant token; explicitly opted-in supervised and autonomous paths do not mint one. The provider Idempotency-Key is derived from the action key and payload hash.",
+        human_only: false,
+        human_only_note: "Agent-facing because the shared adapter contract verifies the exact payload and applies attested policy before the vault credential can be used. It spends a token on manual and selected-live paths.",
+        input: input({
+            positionals: positionals([{ name: "action-key", description: "the action's idempotency_key" }], 1),
+            flags: {
+                "--token": "string", "--payload": "string", ...AS_FLAG, "--vault": "string",
+                ...POLICY_FLAGS, ...LOG_FLAG, "--timeout": "string", ...JSON_FLAG, ...HELP_FLAGS,
+            },
+        }),
+        output: object({
+            ok: { const: true }, adapter: { const: "zzz" }, action_key: STRING,
+            task: STRING, class: STRING, autonomy: STRING, payload_hash: SHA256,
+            started_seq: INTEGER, outcome: { enum: ["execution.completed", "execution.failed"] },
+            outcome_seq: INTEGER, exit_code: nullable(INTEGER), detail: OPEN_OBJECT, redactions: INTEGER,
+        }, ["ok", "adapter", "action_key", "task", "class", "autonomy", "payload_hash", "started_seq", "outcome", "outcome_seq", "exit_code"]),
+        error: ERROR_SCHEMA,
+        exit_codes: [OK, INTEGRITY, USAGE, TORN, IO, { code: 5, meaning: "the effective manual path needs a valid execution token; nothing was appended and nothing was sent" }],
+    },
     {
         name: "hook",
         subcommand: "claude-code",
@@ -2055,6 +2185,78 @@ const VERBS = [
             { code: 2, meaning: "the hook is misconfigured; the harness blocks and reads stderr" },
         ],
     },
+    {
+        name: "hook",
+        subcommand: "codex",
+        purpose: "Read one Codex PreToolUse or PostToolUse event on stdin and strictly validate its stable ids, tool, and visible working directory. PreToolUse denies Bash because Codex does not expose its effective per-call workdir; direct apply_patch is an experimental bounded gate surface and receives nested allow or deny JSON. Manual patch classes wait on a log-backed decision. PostToolUse records an outcome only when a native-verified closed reading exists. THE VERDICT IS NEVER 'ask'. Exit 0 carries a pre-tool verdict, while a post-tool diagnostic uses the post-hook status contract.",
+        human_only: false,
+        human_only_note: "The agent harness surface, so agent-facing by construction: Codex invokes it around the agent's own Bash and apply_patch calls. Bash is refused before gate intake; direct patches can record the agent's proposal and wait for a human. It never records a decision.",
+        input: input({
+            flags: {
+                ...AS_FLAG,
+                "--timeout": "string",
+                "--interval": "string",
+                "--retry-grace": "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: "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",
+                ...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",
+                ...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: "classify",
@@ -2099,6 +2301,137 @@ const VERBS = [
         error: ERROR_SCHEMA,
         exit_codes: BASE_EXIT_CODES,
     },
+    {
+        name: "codex",
+        subcommand: "prepare",
+        purpose: "Write a fresh inert review bundle for a constrained Codex host. It writes only --output, activates nothing, and cannot establish enforcement.",
+        human_only: true,
+        human_only_note: "Host preparation is an operator workflow and is excluded with the whole codex family from the broad agent MCP catalog.",
+        input: input({
+            flags: {
+                "--instance": "string", "--workspace": "string", "--primary": "string",
+                "--install-root": "string", "--output": "string", "--codex": "string", "--node": "string",
+                ...JSON_FLAG, ...HELP_FLAGS,
+            },
+        }),
+        output: object({ ok: { const: true }, inert: { const: true }, output: STRING, files: arrayOf(STRING), manifest: OPEN_OBJECT }, ["ok", "inert", "output", "files", "manifest"]),
+        error: ERROR_SCHEMA,
+        exit_codes: [OK, INTEGRITY, USAGE, IO],
+    },
+    {
+        name: "codex",
+        subcommand: "setup",
+        purpose: "Verify a prepared Codex bundle's exact file set, hashes, manifest, and generated bytes. Success means internally consistent and inert, never installed or ready.",
+        human_only: true,
+        human_only_note: "Setup verification belongs to the operator and is absent from the broad agent MCP catalog.",
+        input: input({ flags: { "--check": "string", ...JSON_FLAG, ...HELP_FLAGS } }),
+        output: object({
+            ok: { const: true }, inert: { const: true }, ready: { const: false },
+            bundle: STRING, files: arrayOf(STRING), reason: { const: "broker-and-runner-not-shipped" },
+        }, ["ok", "inert", "ready", "bundle", "files", "reason"]),
+        error: ERROR_SCHEMA,
+        exit_codes: [OK, INTEGRITY, USAGE, IO],
+    },
+    {
+        name: "codex",
+        subcommand: "doctor",
+        purpose: "Fail-closed inspection of the manifest, platform, pinned version declarations, principals, path separation, symlinks, ownership, modes, invocation, broker and runner. It executes no manifest binary and APRV-325.1 always reports runtime versions unchecked and not ready.",
+        human_only: true,
+        human_only_note: "Strict host custody inspection is an operator surface and is absent from the broad agent MCP catalog.",
+        input: input({ flags: { "--manifest": "string", "--strict": "boolean", ...JSON_FLAG, ...HELP_FLAGS } }),
+        output: null,
+        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: "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", "--timeout": "string", ...JSON_FLAG, ...HELP_FLAGS },
+            trailing: TRAILING,
+        }),
+        output: null,
+        error: ERROR_SCHEMA,
+        exit_codes: [OK, INTEGRITY, USAGE],
+    },
+    {
+        name: "codex",
+        subcommand: "serve",
+        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; 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, 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",
         subcommand: "serve",