approval-md 0.0.1 → 0.2.0

package/dist/src/cli/gloss.js

@@ -0,0 +1,362 @@
+/**
+ * The model gloss: one sentence saying what a payload does, attached to a
+ * prompt at render time and to nothing else (APRV-144, APRV-164).
+ *
+ * The observed complaint (Carter, 2026-08-25): "the claimed isn't very useful —
+ * I mostly see the path, not a readable claim of what is happening". The
+ * deterministic half of the answer is `channels/payload-view.ts`'s command
+ * breakdown, which is derived from the classifier's own parse and is COMPUTED.
+ * This is the other half, and it is the opposite kind of thing: a sentence from
+ * a language model, which no party vouches for and which the runtime must
+ * therefore treat as decoration.
+ *
+ * Four properties hold the design together, and every one of them is about
+ * keeping a model out of the decision.
+ *
+ * **The gate never sees it.** This runs in the LISTENER, at the moment a
+ * message is about to be sent, on a `ChannelRequest` the tagger has already
+ * finished building. The payload hash covers the bytes and not this; the log
+ * records the approval lifecycle and not this; a restart forgets it. Nothing
+ * here writes anything anywhere.
+ *
+ * **It is never load-bearing.** No code path branches on the content of a
+ * gloss. The only thing that turns on it at all is whether one more line
+ * appears in the CLAIMED block, which is why every failure mode below resolves
+ * to ABSENCE rather than to a placeholder, an error line, or a retry: a prompt
+ * with no gloss is the prompt approval.md shipped for its whole life so far,
+ * and a listener that waited on a model would have made a language model part
+ * of the availability of the gate.
+ *
+ * **It fails toward absence, fast.** A hard timeout (default
+ * {@link GLOSS_TIMEOUT_MS}), a non-zero exit, empty output, a binary that is
+ * not installed, a spawn that throws: all `null`. The timeout is bounded on
+ * purpose — this sits in a dispatch cycle that an approver is waiting on — and
+ * since APRV-197 it is bounded by a MEASUREMENT rather than by a guess, because
+ * a ceiling the model cannot meet is not a fast failure, it is a feature that
+ * never runs. See {@link GLOSS_TIMEOUT_MS}. Absences are counted and reported
+ * by the caller (`cli/gloss-attach.ts`), so a ceiling that is wrong again
+ * announces itself instead of looking like silence.
+ *
+ * **Its output is untrusted text.** Whatever comes back is collapsed to a
+ * single line, capped at {@link GLOSS_MAX_CHARS}, and handed to the channel as
+ * a CLAIMED field, which means it goes through the same `escapeHtml` every
+ * other claimed value does. It is treated exactly like a summary an agent
+ * wrote, because that is precisely what it is a cousin of.
+ *
+ * The subprocess is injectable ({@link GlossRunner}) so the tests drive both
+ * branches without a model ever being invoked: the suite never spawns
+ * anything, and the default runner below is exercised only in production.
+ */
+import { spawnSync } from "node:child_process";
+import { childEnvironment } from "../core/child-env.js";
+/**
+ * How long the subprocess gets before it is killed and the gloss is dropped.
+ *
+ * **Measured, not guessed (APRV-197).** APRV-144 chose 2s on the reasoning that
+ * "a slow reading aid is worse than no reading aid", which is true and was the
+ * wrong number: five fresh `claude -p --model haiku` spawns of this module's
+ * own command instruction, timed on the author's machine on 2026-09-01, came
+ * back in 10.2s, 11.3s, 13.5s, 14.6s and 14.9s. Every one of them would have
+ * been killed. The gloss was therefore not "occasionally absent"; it was
+ * absent every single time, and because absence is silent by design that was
+ * indistinguishable from the feature never having shipped — which is exactly
+ * how it was reported (Carter, 2026-09-01: "i thought we implemented a change
+ * so that the claim would be an llm summary").
+ *
+ * A pre-warm was the other option on the table and the measurement rules it
+ * out: the runs above were consecutive, so runs two through five were warm in
+ * every sense a second process can be (page cache, module cache), and they took
+ * 10s to 15s all the same. What is being waited on is inference, not start-up,
+ * and nothing a listener does once at boot shortens it.
+ *
+ * So the ceiling is set above the slowest observed run with headroom, and the
+ * price of that honesty is made explicit rather than hidden. A gloss is now
+ * asked for only under `--gloss` (on `channel cli`, `channel telegram listen`
+ * and `up` alike): an operator who wants the sentence spends the seconds
+ * knowingly, one who does not is never made to wait, and the reading aid that
+ * is always present is the deterministic `command_breakdown` the classifier
+ * derives from the same bytes for free.
+ */
+export const GLOSS_TIMEOUT_MS = 20_000;
+/** The most characters a gloss may occupy on the prompt. */
+export const GLOSS_MAX_CHARS = 200;
+/** Maximum length of an exact provider-supplied model identifier. */
+export const GLOSS_MODEL_ID_MAX_CHARS = 100;
+/**
+ * The model tier this spends: the cheap one.
+ *
+ * CLAUDE.md's model tiers put "cheap classification" on a `claude -p` haiku
+ * subprocess, and a one-sentence paraphrase of a command line is the cheapest
+ * kind of language task there is. Nothing about the prompt or the gate changes
+ * if the flag is unrecognised by the installed CLI: an unusable invocation
+ * exits non-zero and the gloss is absent.
+ */
+export const GLOSS_MODEL = "haiku";
+/**
+ * The historical author label for legacy string-valued test runners.
+ *
+ * Production runners return explicit provenance. Keeping this constant is a
+ * compatibility bridge for callers whose injected seam predates APRV-253; it
+ * must never be used to guess the provenance of a typed production result.
+ */
+export const GLOSS_AUTHOR = `model:${GLOSS_MODEL}`;
+/**
+ * The instruction the model is given.
+ *
+ * Deliberately narrow: describe, do not judge. A model asked whether a command
+ * is safe would produce a sentence an approver could read as a recommendation,
+ * and a recommendation from an unverified party sitting beside an Approve
+ * button is the failure this whole codebase is arranged to prevent. It is
+ * asked what the command DOES, and the answer is labelled as a model's on the
+ * line where it appears.
+ */
+export const GLOSS_INSTRUCTION = [
+    "Describe, in one plain sentence under 25 words, what this shell command does.",
+    "Do not judge whether it is safe, do not recommend approving or rejecting it,",
+    "and do not add any preamble, quotes or formatting. Output the sentence only.",
+].join(" ");
+/**
+ * The same instruction for a file change (APRV-164).
+ *
+ * A payload kind gets its own wording because "what this shell command does" is
+ * the wrong question to ask about a diff, and a model handed the wrong question
+ * answers a question nobody asked. The discipline is identical: describe the
+ * change, do not rate it, and above all do not say whether the edit looks
+ * correct — a judgement of a diff sitting beside an Approve button is the same
+ * failure as a judgement of a command.
+ */
+export const GLOSS_EDIT_INSTRUCTION = [
+    "Describe, in one plain sentence under 25 words, what this file edit changes.",
+    "Do not judge whether it is safe or correct, do not recommend approving or rejecting it,",
+    "and do not add any preamble, quotes or formatting. Output the sentence only.",
+].join(" ");
+/** The same instruction for an email (APRV-164): what it says, and to whom. */
+export const GLOSS_EMAIL_INSTRUCTION = [
+    "Describe, in one plain sentence under 25 words, what this email says and to whom.",
+    "Do not judge whether it is safe, do not recommend approving or rejecting it,",
+    "and do not add any preamble, quotes or formatting. Output the sentence only.",
+].join(" ");
+/**
+ * The most material a gloss may hand the subprocess.
+ *
+ * A whole-file `Write` payload is megabytes, and a reading aid must not turn a
+ * dispatch cycle into a megabyte of argv and a model reading it. The cap is on
+ * the INPUT only: {@link GLOSS_MAX_CHARS} still bounds what comes back.
+ */
+export const GLOSS_MAX_INPUT_CHARS = 8_192;
+/**
+ * What the model is told when the cap bit.
+ *
+ * Announced rather than silent, for the reason every other fold in this
+ * codebase is announced: a model describing a prefix as if it were the whole
+ * would produce a confident sentence about a change the approver is not being
+ * shown. The line is for the model; the approver's own evidence is the PAYLOAD
+ * block, which is never folded.
+ */
+export const GLOSS_TRUNCATION_NOTE = "(input truncated; describe what is shown)";
+/**
+ * One line, capped, or `null`.
+ *
+ * Newlines are stripped rather than escaped because the prompt renders this as
+ * a single bullet, and a multi-line value would break the one-fact-per-line
+ * shape the whole COMPUTED/CLAIMED split relies on to stay legible. Truncation
+ * is marked, for the same reason every other fold in this codebase is.
+ */
+export function tidyGloss(raw) {
+    if (raw === null)
+        return null;
+    const collapsed = raw.replace(/\s+/gu, " ").trim();
+    if (collapsed.length === 0)
+        return null;
+    return collapsed.length <= GLOSS_MAX_CHARS
+        ? collapsed
+        : `${collapsed.slice(0, GLOSS_MAX_CHARS - 1)}…`;
+}
+/**
+ * Normalize a runner answer without inventing provenance.
+ *
+ * Objects with incomplete metadata fail toward absence. Raw strings take the
+ * one narrowly documented legacy path and retain the historical Haiku label.
+ */
+export function tidyGlossResult(raw) {
+    if (typeof raw === "string" || raw === null) {
+        const text = tidyGloss(raw);
+        return text === null
+            ? null
+            : {
+                text,
+                provenance: { provider: "claude", requestedModel: GLOSS_MODEL },
+                legacy: true,
+            };
+    }
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const candidate = raw;
+    if (typeof candidate["text"] !== "string")
+        return null;
+    const provenanceValue = candidate["provenance"];
+    if (typeof provenanceValue !== "object" || provenanceValue === null)
+        return null;
+    const provenance = provenanceValue;
+    const requestedModel = normalizeGlossModelId(provenance["requestedModel"]);
+    const confirmedModel = provenance["confirmedModel"] === undefined
+        ? undefined
+        : normalizeGlossModelId(provenance["confirmedModel"]);
+    if ((provenance.provider !== "claude" && provenance.provider !== "codex") ||
+        requestedModel === null ||
+        (provenance["confirmedModel"] !== undefined && confirmedModel === null)) {
+        return null;
+    }
+    const text = tidyGloss(candidate["text"]);
+    if (text === null)
+        return null;
+    const normalizedProvenance = {
+        provider: provenance.provider,
+        requestedModel,
+    };
+    if (typeof confirmedModel === "string")
+        normalizedProvenance.confirmedModel = confirmedModel;
+    return { text, provenance: normalizedProvenance };
+}
+/** A bounded, single-line identifier, or `null` rather than a misleading fold. */
+export function normalizeGlossModelId(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0 ||
+        trimmed.length > GLOSS_MODEL_ID_MAX_CHARS ||
+        !/^[\p{L}\p{N}][\p{L}\p{N}._:/+-]*$/u.test(trimmed)) {
+        return null;
+    }
+    return trimmed;
+}
+/**
+ * The claimed author rendered beside one gloss.
+ *
+ * Requested and confirmed identities are deliberately distinct. The default
+ * subprocess knows what it asked Claude for, but its plain stdout does not
+ * prove which model served the request, so it renders as requested.
+ */
+export function glossAuthor(result) {
+    if (result.legacy === true)
+        return GLOSS_AUTHOR;
+    const { provider, requestedModel, confirmedModel } = result.provenance;
+    if (confirmedModel === undefined) {
+        return `model:${provider}/${requestedModel} (requested)`;
+    }
+    return confirmedModel === requestedModel
+        ? `model:${provider}/${confirmedModel} (confirmed)`
+        : `model:${provider}/${confirmedModel} (confirmed; requested:${requestedModel})`;
+}
+/**
+ * The production runner: `claude -p --model haiku`, with a hard timeout.
+ *
+ * `spawnSync` with no shell, in the manner of `cli/hook.ts`'s git calls: the
+ * prompt is an argument and never a string a shell re-parses. Every failure is
+ * a value rather than an exception — `spawnSync` reports a missing binary and a
+ * timeout kill on the result object, and both are simply "no gloss".
+ *
+ * **Starved, like a granted child (APRV-207).** The environment is built by
+ * APRV-205's scrub rather than inherited: this is a third-party CLI that talks
+ * to the network on every prompt render, spawned by the listener, which is the
+ * process holding the Telegram bot token and the vault passphrase. It has no
+ * use for either, and a gate that hands its own credentials to a convenience is
+ * a gate whose custody claim is decorative. No credential is DECLARED here,
+ * because a gloss is not a granted action and no adapter asked for one.
+ *
+ * What passes is what the scrub does not take: the model's own auth
+ * (`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`,
+ * `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL` and kin), `PATH`, `HOME`, `TMPDIR`
+ * and the locale. None of them is under the gate's credential-bearing prefixes,
+ * so none of them needs a list of its own: a second list here is a second list
+ * to drift, and the CLI's ability to reach its own model is not this gate's
+ * secret to keep.
+ *
+ * `passphraseEnv` is the name the policy's `vault.passphrase_env` gives, for
+ * the deployment that renamed it out from under the prefixes. Omitted, the
+ * default (`APPROVAL_VAULT_PASSPHRASE`) is removed by the prefix rule anyway.
+ */
+export function spawnGloss(prompt, passphraseEnv = null, model = GLOSS_MODEL) {
+    const requestedModel = normalizeGlossModelId(model);
+    if (requestedModel === null)
+        return null;
+    let result;
+    try {
+        result = spawnSync("claude", ["-p", "--model", requestedModel, prompt], {
+            encoding: "utf8",
+            env: childEnvironment({ passphraseEnv }).env,
+            timeout: GLOSS_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+            // A sentence is a few hundred bytes. A model that decides to emit a
+            // megabyte is a model whose answer is dropped rather than buffered.
+            maxBuffer: 64 * 1024,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (result.error !== undefined || result.status !== 0)
+        return null;
+    return typeof result.stdout === "string"
+        ? {
+            text: result.stdout,
+            provenance: { provider: "claude", requestedModel },
+        }
+        : null;
+}
+/**
+ * {@link spawnGloss} bound to one policy's passphrase variable (APRV-207).
+ *
+ * The verbs that wire a runner (`channel cli`, `channel telegram listen`, `up`)
+ * have a policy load in hand already, and this is the only thing the scrub
+ * needs from it. A runner is still a `(prompt) => string | null`, so nothing
+ * downstream learns that a policy exists.
+ */
+export function glossRunnerFor(passphraseEnv, model = GLOSS_MODEL) {
+    return (prompt) => spawnGloss(prompt, passphraseEnv, model);
+}
+/**
+ * `material`, capped at {@link GLOSS_MAX_INPUT_CHARS} and marked when it was.
+ *
+ * The marker precedes the material rather than trailing it, so a model reading
+ * a long prefix meets the caveat before the text it is about to describe.
+ */
+export function glossPrompt(instruction, material) {
+    return material.length <= GLOSS_MAX_INPUT_CHARS
+        ? `${instruction}\n\n${material}`
+        : `${instruction}\n\n${GLOSS_TRUNCATION_NOTE}\n\n${material.slice(0, GLOSS_MAX_INPUT_CHARS)}`;
+}
+/**
+ * A gloss for one payload's material, or `null`.
+ *
+ * The material is passed to the model as data inside the prompt. It is
+ * agent-authored text, and it is worth being explicit about what that does and
+ * does not mean here: a command (or a diff, or a body) crafted to talk the
+ * model into writing "harmless cleanup" gets that sentence onto the prompt,
+ * labelled `(model, unverified)`, next to a COMPUTED breakdown derived from the
+ * same bytes by code and a PAYLOAD block carrying the canonical rendering verbatim. It
+ * cannot change the class, the autonomy, the budget verdicts or the payload
+ * hash, because nothing downstream reads it. That is the whole reason this is
+ * allowed to exist on the prompt at all.
+ *
+ * The caller chooses the instruction, which is the only thing that varies by
+ * payload kind: the bounds, the failure modes and the author label are one
+ * pipeline for every kind (APRV-164).
+ */
+export function glossFor(instruction, material, run = spawnGloss) {
+    if (material.trim().length === 0)
+        return null;
+    let raw;
+    try {
+        raw = run(glossPrompt(instruction, material));
+        return tidyGlossResult(raw);
+    }
+    catch {
+        // A runner is contracted not to throw; if one does anyway, the contract
+        // that matters (a gloss never breaks a dispatch cycle) is upheld here. The
+        // normalization stays inside this boundary because an injected object can
+        // throw from a property getter just as readily as the runner can throw.
+        return null;
+    }
+}
+//# sourceMappingURL=gloss.js.map

package/dist/src/cli/gloss.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gloss.js","sourceRoot":"","sources":["../../../src/cli/gloss.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/help.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Help text. SPEC.md §10.1 makes `--help` part of the interface rather than a
+ * courtesy: the CLI is how agents use this system, and an agent that has to
+ * guess an exit code or a JSON key is an agent that will guess wrong on the one
+ * invocation that mattered. Every command therefore documents its flags, its
+ * refusal codes and its exact `--json` shape.
+ *
+ * WHAT A PER-VERB HELP IS (APRV-91): the usage forms, a short paragraph of
+ * intent, the flags, the machine-facing contract (`--json` shape, refusal
+ * codes), and a two-line footer. What it is NOT is an essay. The frozen
+ * exit-code table is printed by `approval --help` and nowhere else, the
+ * cross-cutting stances (identity is declared not proved, a refusal is exit 1,
+ * a token is shown once, a channel is transport) are stated once at the root,
+ * and the long design rationale lives in `docs/cli-reference.md`, which every
+ * trimmed help points at by anchor. The prose was moved, not rewritten.
+ */
+export declare const ROOT_HELP = "approval \u2014 human approval for agent actions (pre-release)\n\nUsage:\n  approval log verify [--log <path>] [--json]\n  approval log tail   [--log <path>] [-n <count>] [--json]\n  approval log export [--log <path>] [--json]\n  approval log follow [--log <path>] [--from <seq>] [--cursor-hash <64hex>] --json\n  approval instructions [--schemas] [--json]\n  approval init       [--dir <path>] [--json]\n  approval quickstart [--dir <path>] [--api-base <url>]      (interactive; no --json)\n  approval policy check|test <class> [--reversible true|false] [--policy <path>] [--dir <path>] [--json]\n  approval policy attest [--policy <path>] [--dir <path>] [--as human:<id>] [--json]\n  approval policy amend  [--policy <path>] [--dir <path>] [--log <path>]\n                      [--as human:<id>] [--require-load] [--dry-run] [--commit]\n                      [--yes] [--json]\n  approval register   <task-file> [--as <id>] [--log <path>] [--json]\n  approval request    <task> --action <key> [--as <id>] [--json]\n  approval grant|reject|revoke <action-key> [--note <text>] [--as human:<id>] [--json]\n  approval expire     <action-key> [--json]\n  approval token      <action-key> [--policy <path>] [--dir <path>] [--json]\n  approval consume    <action-key> --token <t> [--payload-hash <64hex>]\n                      [--as <id>] [--json]                            (internal)\n  approval run        <action-key> [--token <t>] [--payload-hash <64hex>]\n                      [--as <id>] [--no-sandbox] [--json] -- <cmd\u2026>\n  approval sandbox    [--allow-loopback] [--log <path>] -- <cmd\u2026>\n  approval adapter email <action-key> [--token <t>] --payload <file|->\n                      [--as <id>] [--vault <path>] [--timeout <ms>] [--json]\n  approval adapter agentmail <action-key> [--token <t>] --payload <file|->\n                      [--as <id>] [--vault <path>] [--timeout <ms>] [--json]\n  approval adapter zzz <action-key> [--token <t>] --payload <file|->\n                      [--as <id>] [--vault <path>] [--timeout <ms>] [--json]\n  approval execution resolve <action-key> --outcome completed|failed\n                      --note \"<text>\" [--as human:<id>] [--json]\n  approval execution reconcile <action-key>\n                      --resolution executed|not-executed\n                      --note \"<evidence>\" [--as human:<id>] [--json]\n  approval audit list|review [<seq|action-key>] [--note \"<text>\"]\n                      [--as human:<id>] [--all] [--json]\n  approval wait       <task> --timeout <duration> [--interval <d>]\n                      [--withdraw-on-timeout] [--json]\n  approval withdraw   <task> --action <key> [--reason <r>] [--note \"<text>\"]\n                      [--as <id>] [--json]\n  approval queue      [--policy <path>] [--dir <path>] [--json]\n  approval coverage   [--base <ref>] [--head <ref>] [--since <duration>]\n                      [--source git,gh,agentmail] [--json]\n  approval channel cli [--policy-dir <path>] [--payload-dir <path>]\n                      [--as human:<id>] [--interactive] [--json]\n  approval channel web [--port <n>] [--payload-dir <path>] [--as human:<id>]\n                      [--policy <path>] [--dir <path>] [--log <path>] [--json]\n  approval channel telegram listen|health [--once] [--as human:<id>] [--json]\n  approval daemon run [--tasks <dir>] [--out <path>] [--interval <duration>]\n                      [--debounce <duration>] [--once] [--with-channels] [--json]\n  approval up         [--as human:<id>] [--port <n>] [--no-telegram] [--no-web]\n                      [--restart-backoff <d>] (plus every daemon run flag)\n  approval setup service [--platform launchd|systemd] [--uninstall]\n                      [--label <name>] [--logs <dir>] [--env-file <path>]\n  approval gate open|close|status [--for <d>] [--reason \"<t>\"] [--note \"<t>\"]\n                      [--as human:<id>] [--log <path>] [--json]\n                                              (open: terminal only, no --json)\n  approval status     [--policy <path>] [--dir <path>] [--json]\n  approval doctor     [--log <path>] [--policy <path>] [--dir <path>]\n                      [--api-base <url>] [--json]\n  approval payload hash <file|-> [--json]\n  approval payload agentmail-draft <inbox-id> <draft-id> [--api-base <url>]\n                      [--json]\n  approval journal write --message \"<text>\" | - [--task <id>] [--session <id>]\n                      [--as <id>] [--journal <dir>] [--json]\n  approval journal read [--limit <n>] [--since <YYYY-MM-DD>] [--journal <dir>]\n                      [--json]\n  approval values     [--policy <path>] [--dir <path>] [--json]\n  approval feedback   [--task <id>] [--actor <agent id>] [--reaction <word>]\n                      [--source review|decision] [--since <YYYY-MM-DD>]\n                      [--limit <n>] [--log <path>] [--json]\n  approval env        [--check] [--policy <path>] [--dir <path>] [--log <path>]\n                      [--json]\n  approval setup      identity|vault|sampling|channel <name>|adapter <name>\n                      [--as human:<id>] [--api-base <url>] [--policy <path>]\n                      [--dir <path>] [--log <path>]        (interactive; no --json)\n  approval vault set <name> [--value-env <VAR>] [--as human:<id>] [--json]\n  approval vault list|remove [<name>] [--as human:<id>] [--json]\n  approval hook claude-code [--as agent:<id>] [--timeout <duration>]\n                      [--interval <d>] [--policy <path>] [--dir <path>]\n                      [--log <path>]                    (reads PreToolUse JSON)\n  approval hook cursor [--as agent:<id>] [--timeout <duration>]\n                      [--interval <d>] [--policy <path>] [--dir <path>]\n                      [--log <path>]                    (reads preToolUse JSON)\n  approval hook classify [--json] [--policy <path>] [--dir <path>] -- <command\u2026>\n  approval import agents-md <file> [--out <path>] [--json]\n  approval codex      prepare|setup|doctor|start|serve (strict host workflow)\n  approval mcp serve  --as agent:<id> [--dir <path>] [--log <path>]\n                      [--policy <path>]              (MCP over stdio; foreground)\n  approval reindex    [--log <path>] [--index <path>] [--force] [--json]\n  approval render     [--log <path>] [--out <path>] [--policy <path>]\n                      [--dir <path>] [--json]\n  approval --help\n\nSet up \u2014 make this directory and this machine ready:\n  init      scaffold a working directory: APPROVAL.md (SPEC.md \u00A75.1's canonical\n            policy, to be read and edited), the empty .approval/log/ directory,\n            .approval/QUEUE.md in its empty state, and the .gitignore lines for\n            the index, the vault, the environment source map and the\n            atomic-write temp files. Appends\n            nothing, attests nothing, overwrites nothing; a re-run writes\n            nothing and reports what already exists\n  quickstart ask three decisions, write a solo policy with the named human as\n            its sole approver, configure identity and an optional Telegram\n            channel, show the exact bytes, then require typed `understood`\n            before attesting. HUMAN-ONLY and INTERACTIVE ONLY\n  setup     the WRITER for that file: \"setup identity|vault|sampling\" and\n            \"setup channel <name>\" store each secret in the OS keystore and\n            record where it lives, and \"setup adapter <name>\" fills the VAULT\n            from the credential manifest the adapter itself declares, then\n            proves it against the service without sending anything. The two\n            nouns are SPEC.md \u00A74's: a channel holds no state and needs a\n            transport credential, an adapter holds the credentials a side\n            effect spends. INTERACTIVE ONLY \u2014 it refuses a\n            non-terminal stdin and --json, and prints the exact commands to run\n            instead, because a setup a pipe could drive would let a CI job\n            declare a human identity. It appends nothing to the log, attests\n            nothing, and never edits APPROVAL.md\n  vault     the encrypted credential store adapters read from (SPEC.md \u00A710.4).\n            \"vault set|list|remove\" are HUMAN-ONLY; list shows NAMES and never\n            values, and there is no \"vault get\" \u2014 a credential's only sanctioned\n            journey is from .approval/vault.enc into an adapter, inside the\n            verified execution window. The passphrase comes from the environment\n            variable the policy NAMES (vault.passphrase_env), never from a flag\n  env       resolve .approval/env \u2014 the environment SOURCE MAP \u2014 and print an\n            export block for your shell to evaluate. THE ONLY VERB THAT READS\n            THAT FILE: no command loads it implicitly, because human identity is\n            one of the variables it carries and a working-tree file any process\n            read on its own would let anything able to write it act as you. The\n            default output carries secrets by design; \"env --check\" prints a\n            table with no values on any path\n  policy    explain what APPROVAL.md does with an action class (check | test),\n            record a human's sign-off on the policy file (attest), or run the\n            whole amendment ceremony \u2014 semantic diff, load advisory,\n            attestation, and the two-file git commit \u2014 as one verb (amend)\n  import    \"import agents-md\" parses an AGENTS.md-style permissions section\n            into DRAFT policy classes for a human to confirm (SPEC.md \u00A712). It\n            prints; it never writes APPROVAL.md, never logs, never attests\n\nAsk \u2014 an agent declares an action and acts on the answer:\n  instructions\n            the full AGENT-FACING usage guide: what to declare before acting,\n            the register -> request -> wait -> run sequence, what a refusal\n            means, and the invariants an agent must not route around. With\n            --schemas it prints the verb registry as JSON \u2014 purpose, input and\n            output schemas, exit codes and the human-only marker for every verb\n            \u2014 which is the same source the optional MCP wrapper (SPEC.md \u00A710.5)\n            builds its tools from. Reads nothing, writes nothing\n  register  validate a task envelope and append task.registered\n  request   ask the gate to admit a declared action (manual classes append\n            approval.requested; supervised/autonomous append nothing and\n            proceed straight to execution, per amended SPEC.md \u00A76.3)\n  token     report whether a live single-use execution token exists for an\n            action (the RAW token is printed once, by grant, and stored nowhere)\n  consume   spend a token and append execution.started (internal plumbing;\n            \"approval run\" wraps it)\n  run       execute a command behind the gate: appends execution.started before\n            spawning it, execution.completed/failed with the child's exit code\n            after, and exits with that same code\n  adapter   execute an action through a side-effect adapter, the hard\n            boundary of SPEC.md \u00A710.4. \"adapter email\" sends one RFC 5322\n            message over SMTP for a communicate.email.external action: the\n            credentials come from the vault inside the execution window, the\n            payload is the bytes the declaration or grant bound to, and the\n            runtime recomputes the hash, applies policy, and writes both\n            execution events around the send. Manual and selected-live paths\n            require --token; policy-authorized supervised/autonomous paths do\n            not mint one. \"adapter agentmail\" serves the\n            same class over the AgentMail API: a direct send, or the send of a\n            draft the agent composed, refused if the draft changed after the\n            snapshot a human approved\n  wait      block until a task's requests are decided; the exit code IS the\n            decision (0 granted, 1 rejected/revoked/withdrawn, 3 expired, 6 timeout)\n  withdraw  take back your OWN pending request (timeout, cancelled, superseded);\n            terminal, requester-only, and a late grant then authorizes nothing\n  hook      put the gate in front of an agent HARNESS. \"hook claude-code\" and\n            \"hook cursor\" each read their harness's pre-tool event on stdin,\n            classify the command or protected-path edit it is about to run,\n            resolve the class against APPROVAL.md, and answer allow or deny \u2014\n            waiting on a real approval decision when the class is manual. They\n            never answer \"ask\": a decision taken outside the log is a decision\n            nothing can audit. \"hook classify\" prints what the classifier makes\n            of a command and touches nothing\n  journal   the one channel the gate does NOT stand in front of. \"journal write\"\n            appends free text to a local file \u2014 ungated, unclassified, never\n            approvable and never deniable, with no event in the log \u2014 so an\n            agent can say \"I am complying and I think this is wrong\", \"this\n            reads as odd to me\", or \"I am stuck\" even when it is complying\n            perfectly. \"journal read\" is the human side, and it labels every\n            entry as agent-authored DATA. Nothing written there changes any\n            verdict, sampling probability or budget; it is signal for the\n            operator, not a decision surface\n  values    the mirror of \"journal\", running the other way: the operator's own\n            words, in the optional values block of APPROVAL.md. What they value\n            in the work, what they want from an agent, and how they read and\n            answer. It is GUIDANCE and never policy: it grants nothing, forbids\n            nothing, and no enforcement path reads it. A file with no block says\n            so in words, because \"nothing was declared\" and \"I did not look\" are\n            different facts\n  feedback  the same channel in the other direction: what the OPERATOR said\n            about the work. Lists the reactions and notes a person wrote on a\n            grant or on a retrospective review, joined to the class, the task,\n            the action key and the agent it was about. HUMAN-AUTHORED GUIDANCE\n            and never policy \u2014 it grants nothing, forbids nothing, and changes\n            no verdict, sampling probability or budget. Reads a verified log\n            and writes nothing\n  mcp       \"mcp serve\" is the optional MCP wrapper of SPEC.md \u00A710.5: the same\n            verbs as tools, over stdio, sharing the CLI's code paths. It is\n            AGENT-FACING ONLY \u2014 grant, reject, revoke, attest, amend, vault,\n            setup, audit review, expire, execution resolve|reconcile and the\n            channels are not published, because an MCP client is an agent's\n            harness and SPEC.md \u00A711 makes the agent the untrusted policy. It\n            runs as ONE agent identity, fixed at startup, that nothing changes\n\nDecide \u2014 a human answers, and only a human can:\n  queue     the pending-decision INBOX: requests awaiting a human, inside their\n            TTL. Nothing else \u2014 exit 0 always when the log could be read\n  grant     record a human approval          (HUMAN-ONLY)\n  reject    record a human refusal           (HUMAN-ONLY)\n  revoke    withdraw an unexecuted approval  (HUMAN-ONLY)\n  expire    lapse a request whose TTL passed (system verb, actor system:gate)\n  execution recovery verbs for executions the runtime could not close itself.\n            \"execution resolve\" records the outcome a HUMAN OBSERVED for a\n            dangling execution: mandatory --note, human-only, exit_code null,\n            attested_by_human true. \"execution reconcile\" records what a human\n            ESTABLISHED about an INDETERMINATE one \u2014 a side effect that was\n            attempted and whose outcome nobody knows \u2014 from the relying party's\n            evidence, naming the record it resolves and rewriting nothing.\n            Neither requires attestation: both record a fact a human observed\n            and exercise no policy authority\n  audit     \"audit list\" is the open sampled-audit backlog and \"audit review\" is\n            the HUMAN-ONLY verb that closes one item of it. Sampling itself has\n            no verb: the daemon selects supervised actions with an operator-held\n            secret, because a caller who could sample could also decline to\n            sample itself\n  channel   put pending requests in front of a human over the channel contract.\n            \"channel cli\" renders the queue with [computed]/[claimed] markers and\n            the full payload in delimiters, and with a terminal collects\n            decisions through the same human-only gate as grant/reject.\n            \"channel telegram listen\" delivers the queue to a Telegram chat on\n            every poll cycle (including requests that arrive while it runs) and\n            long-polls for Approve/Reject taps; config is environment-only\n            (APPROVAL_TG_TOKEN, APPROVAL_TG_CHAT)\n\nInspect \u2014 what the log says, and whether anything needs repair:\n  log       inspect the append-only event log (verify | tail | export)\n  status    system HEALTH: attestation, dangling executions, budget headroom,\n            the latest chain verdict, loop escalations. Exit 1 when any of\n            those needs attention. queue is what a human must answer; status is\n            what an operator must fix, and neither carries the other's content\n  coverage  what the witnesses this project does NOT write (git, gh, a\n            provider's own record) say happened, joined to the verified log:\n            per effect, the evidence seq or none. INFORMATIONAL \u2014 exit 0 with\n            or without gaps, because a coverage measurement is not a verdict\n  doctor    is this ENVIRONMENT sane? build freshness, declared identity, policy\n            attestation, chain health, the Telegram token, the web port \u2014 each\n            with a concrete repair. status asks whether the SYSTEM needs\n            attention; doctor asks whether the machine you are typing on can run\n            the system at all. Appends nothing, sends nothing, repairs nothing\n  render    regenerate .approval/QUEUE.md, the READ-ONLY markdown queue\n            projection (SPEC.md \u00A79.1): pending requests and the sampled-audit\n            backlog, computed and claimed fields visibly distinguished. The\n            screenshot, never the truth \u2014 editing it authorizes nothing\n  reindex   rebuild the SQLite index projection from the log\n  payload   \"payload hash\" prints the payload_hash of a JSON document (SHA-256\n            over its RFC 8785 canonical serialization), the value a declaration\n            carries and a grant binds to. Most flows never need it: \"request\n            --payload\" hashes, verifies and stores the bytes in one step.\n            \"payload agentmail-draft\" snapshots one AgentMail draft with the\n            AGENT's key, so a human approves the words and not a draft id\n  daemon    \"daemon run\" is the watch loop of SPEC.md \u00A710.2, in the FOREGROUND:\n            it records envelope.drift when a task file's state: contradicts the\n            log, appends approval.expired for lapsed requests, writes the log's\n            state back into the task files, regenerates QUEUE.md, and surfaces\n            loop escalations. It holds no lock; backgrounding is the operator's\n            business in v0.1\n  up        the AMBIENT RUNTIME: that same daemon loop plus every channel the\n            policy configures, in ONE supervised foreground process. A channel\n            whose credential is unset is not started and says so in doctor's\n            vocabulary; a channel that falls over is restarted with a doubling\n            backoff and the daemon loop carries on. \"approval setup service\"\n            writes the launchd or systemd user unit that runs it at login\n\nDefaults:\n  log    .approval/log/events.jsonl   (relative to the working directory)\n  index  .approval/index.sqlite\n  queue  .approval/QUEUE.md\n  payloads .approval/payloads/<payload_hash>.json  (the bytes a request bound\n           to, written by request --payload; read by render and every channel,\n           and re-hashed on every read)\n  env    .approval/env  (the environment SOURCE MAP: KEY=keychain:<service> /\n         secret-service:<label> / env: / a plaintext literal. Mode 0600, and read\n         by exactly one command, \"approval env\". GITIGNORED by init)\n  journal .approval-journal/YYYY-MM-DD.jsonl  (the ungated free-text channel of\n         \"journal write\". OUTSIDE the approval home on purpose: everything under\n         .approval/ is the gate's own, and an outlet the gate could close is not\n         an outlet. Nothing the runtime reads is ever stored there. Gitignored)\n  vault  .approval/vault.enc  (AES-256-GCM over the named credentials; written\n         only by \"vault set|remove\", read only by an adapter inside a verified\n         token window. GITIGNORE IT \u2014 doctor fails if you have not)\n\nExit codes (frozen public API):\n  0  success\n  1  integrity failure (corrupt log)\n  2  usage error\n  3  torn tail\n  4  I/O error (unreadable/unwritable path; never reported as corruption)\n\nTwo codes are ADDITIONS to the table above, each emitted by exactly one verb:\n5 by \"approval run\" when no valid execution token was presented (nothing is\nappended), and 6 by \"approval wait\" on timeout. Nothing in 0\u20134 changed meaning.\nThis table is printed HERE and nowhere else; a verb's own --help names only the\ncodes that are peculiar to it.\n\nMachine-readable output: every command accepts --json and prints exactly one\nJSON object per invocation. Run \"approval <command> --help\" for that command's\nexact shape.\nWith --json, usage and I/O failures print {\"error\":{\"code\",\"message\"}} to\nstderr and nothing to stdout.\n\nThe stances every verb inherits, stated once:\n\n  THE LOG IS APPEND-ONLY. \"policy attest\" and the gate verbs (register, request,\n  grant, reject, revoke, expire) each append at most one event per invocation; a\n  torn tail is reported, never repaired, and nothing ever rewrites a line.\n\n  A GATE REFUSAL exits 1, NOT 2 \u2014 an illegal transition, an expired request, an\n  unattested policy, a failed budget. The command was well-formed; the answer is\n  no. With --json, error.code names the refusal, and retrying with different\n  flags is the wrong repair.\n\n  IDENTITY IS CONFIG-DECLARED (SPEC.md \u00A711). The actor comes from --as or\n  APPROVAL_HUMAN and nothing authenticates it; the trust boundary is the local\n  machine. What the log proves is that someone with local control acted, not\n  who. grant, reject, revoke and every human-only verb require human:<id>;\n  expire is the system verb and takes no identity.\n\n  APPROVAL EVENTS ARE EXCLUSIVE TO THE MANUAL PATH (amended SPEC.md \u00A76.3). An\n  action resolving to supervised or autonomous emits no approval.requested and\n  no approval.granted: \"approval request\" appends nothing and reports\n  proceed:true, and its authorization is the execution.started event. Do not\n  wait for a grant that will never come.\n\n  THE RAW EXECUTION TOKEN IS SHOWN ONCE, BY \"approval grant\". The log records\n  only its SHA-256, so nothing can recover it \u2014 not \"approval token\", not the\n  log, not the index. If it is lost, revoke the grant and request again.\n\n  A CHANNEL IS TRANSPORT. It renders what the runtime derived and reports the\n  gesture a human made; it decides nothing, holds no state, writes no log line\n  and never sees a token. Every field it shows is marked [computed] (the runtime\n  derived it) or [claimed] (the party under oversight wrote it), per SPEC.md \u00A79.\n\nThe reasoning behind each verb \u2014 threat models, the design points that surprise\npeople, the alternatives that were rejected \u2014 is in docs/cli-reference.md.";
+export declare const INSTRUCTIONS_HELP: string;
+export declare const LOG_HELP: string;
+export declare const FOLLOW_HELP: string;
+export declare const LOG_SYNC_HELP: string;
+export declare const LOG_ADVANCE_HELP: string;
+export declare const VERIFY_HELP: string;
+export declare const LOG_CHECKPOINT_HELP: string;
+export declare const TAIL_HELP: string;
+export declare const EXPORT_HELP: string;
+export declare const POLICY_HELP: string;
+export declare const POLICY_CHECK_HELP: string;
+export declare const POLICY_TEST_HELP: string;
+export declare const POLICY_ATTEST_HELP: string;
+export declare const POLICY_AMEND_HELP: string;
+export declare const REGISTER_HELP: string;
+export declare const REQUEST_HELP: string;
+export declare const GRANT_HELP: string;
+export declare const REJECT_HELP: string;
+export declare const REVOKE_HELP: string;
+export declare const WITHDRAW_HELP: string;
+export declare const EXPIRE_HELP: string;
+export declare const GATE_WINDOW_HELP: string;
+export declare const REINDEX_HELP: string;
+export declare const TOKEN_HELP: string;
+export declare const CONSUME_HELP: string;
+export declare const RUN_HELP: string;
+export declare const SANDBOX_HELP: string;
+export declare const WAIT_HELP: string;
+export declare const QUEUE_HELP: string;
+export declare const STATUS_HELP: string;
+export declare const COVERAGE_HELP: string;
+export declare const DOCTOR_HELP: string;
+export declare const AUDIT_HELP: string;
+export declare const AUDIT_LIST_HELP: string;
+export declare const AUDIT_REVIEW_HELP: string;
+export declare const AUDIT_OBLIGATIONS_HELP: string;
+export declare const AUDIT_RECONCILE_HELP: string;
+export declare const EXECUTION_HELP: string;
+export declare const RESOLVE_HELP: string;
+export declare const RECONCILE_HELP: string;
+export declare const CHANNEL_HELP: string;
+export declare const CHANNEL_CLI_HELP: string;
+export declare const WEB_HELP: string;
+export declare const INIT_HELP: string;
+export declare const QUICKSTART_HELP: string;
+export declare const HOOK_HELP: string;
+export declare const IMPORT_HELP: string;
+export declare const IMPORT_AGENTS_MD_HELP: string;
+export declare const PAYLOAD_HELP: string;
+export declare const PAYLOAD_HASH_HELP: string;
+export declare const PAYLOAD_AGENTMAIL_DRAFT_HELP: string;
+export declare const JOURNAL_HELP: string;
+export declare const JOURNAL_WRITE_HELP: string;
+export declare const JOURNAL_READ_HELP: string;
+export declare const VALUES_HELP: string;
+export declare const FEEDBACK_HELP: string;
+export declare const RENDER_HELP: string;
+export declare const TELEGRAM_HELP: string;
+export declare const TELEGRAM_LISTEN_HELP: string;
+export declare const TELEGRAM_HEALTH_HELP: string;
+export declare const DAEMON_HELP: string;
+export declare const DAEMON_RUN_HELP: string;
+export declare const UP_HELP: string;
+export declare const VAULT_HELP: string;
+export declare const VAULT_SET_HELP: string;
+export declare const VAULT_LIST_HELP: string;
+export declare const VAULT_REMOVE_HELP: string;
+export declare const ADAPTER_HELP: string;
+export declare const ADAPTER_EMAIL_HELP: string;
+export declare const ADAPTER_AGENTMAIL_HELP: string;
+export declare const ADAPTER_ZZZ_HELP: string;
+export declare const ENV_HELP: string;
+export declare const SETUP_HELP: string;
+export declare const SETUP_IDENTITY_HELP: string;
+export declare const SETUP_VAULT_HELP: string;
+export declare const SETUP_SAMPLING_HELP: string;
+export declare const SETUP_CHECKPOINT_HELP: string;
+export declare const SETUP_ADAPTER_HELP: string;
+export declare const SETUP_ADAPTER_EMAIL_HELP: string;
+export declare const SETUP_ADAPTER_AGENTMAIL_HELP: string;
+export declare const SETUP_ADAPTER_ZZZ_HELP: string;
+export declare const SETUP_CHANNEL_HELP: string;
+export declare const SETUP_CHANNEL_TELEGRAM_HELP: string;
+export declare const SETUP_SERVICE_HELP: string;
+export declare const CODEX_HELP = "approval codex \u2014 prepare and inspect a constrained Codex host bundle (INERT)\n\nUsage:\n  approval codex prepare --instance <id> --workspace <abs> --primary <abs>\n      --install-root <abs> --output <new-dir> --codex <abs> --node <abs> [--json]\n  approval codex setup --check <bundle-dir> [--json]\n  approval codex doctor --strict --manifest <abs> [--json]\n  approval codex start|serve --manifest <abs> [--json]\n\nprepare writes a fresh review bundle only. setup --check verifies its closed file\nset, hashes, manifest and generated templates. Neither installs a package, edits\nCodex configuration, creates principals, loads services, reads credentials, or\nchanges policy. doctor fails closed on unknown custody, executes no manifest\nbinary in this slice, and reports runtime versions as unchecked.\n\nstart and serve currently refuse with codex-not-ready. The policy-bound broker\nand confined runner arrive in APRV-325.2 and APRV-325.3. An npm or project\ninstallation alone is never reported as enforcement.\n\nexit codes: approval --help (1 means the strict boundary is absent or invalid)\nWith --json, usage and I/O failures print {\"error\":{\"code\",\"message\"}} to\nstderr and nothing to stdout.\nwhy: docs/cli-reference.md#constrained-codex-preparation";
+export declare const MCP_HELP: string;