approval-md 0.1.0 → 0.2.0

package/dist/src/cli/channel-web.d.ts

@@ -0,0 +1,131 @@
+/**
+ * `approval channel web` — the runtime half of the local web queue channel
+ * (SPEC.md §5.1 `channels.web.port`, §9, §10.3, §10.4, §11 — APRV-25).
+ *
+ * As everywhere else in this CLI, **no logic lives here**. Rendering and the
+ * HTTP server are `channels/web.ts`; turning a submitted form into an event is
+ * `channels/contract.ts`'s `recordChannelDecision` and `channels/batch.ts`'s
+ * `recordBatchDecisions`, both of which call the human-only `decide()` in
+ * `core/gate.ts`. This file resolves configuration, supplies the live pending
+ * queue, wires the two together, and chooses an exit code.
+ *
+ * Three things it does that the channel deliberately cannot:
+ *
+ * 1. **It reads the log.** {@link buildPendingQueue} runs here, once per page
+ *    view, and the channel is handed the resulting {@link ChannelRequest}s. A
+ *    channel that read the log would be deriving the facts it is meant to be
+ *    transporting. Because that read happens per *request* rather than per
+ *    process, this channel needs no dispatch of its own (APRV-55): a request
+ *    appended while the server is running appears on the next page load, and a
+ *    decided or TTL-lapsed one disappears the same way. Pull channels get for
+ *    free what the Telegram listener has to arrange with a per-cycle send.
+ * 2. **It declares who is approving.** `--as` / `APPROVAL_HUMAN`, never
+ *    anything the browser sent — there is nothing in an unauthenticated form
+ *    post that could name a person. SPEC.md §11: identity is config-declared,
+ *    the trust boundary is the local machine, and the page says so in a banner
+ *    because the page is where the human is looking.
+ * 3. **It holds the token.** `recordChannelDecision` returns the raw execution
+ *    token to *this* handler, which hands it back to the channel as one-shot
+ *    *notice text* at render time and keeps no copy. See `channels/web.ts`'s
+ *    header for why this channel shows the token on the page while the Telegram
+ *    channel refuses to put it in a chat — that asymmetry is flagged there.
+ *
+ * ## Port precedence
+ *
+ * `--port` > `channels.web.port` in the attested policy > 4680. Nothing else:
+ * no environment variable, because a port that moves when an unrelated variable
+ * is exported is a port an operator will eventually fail to find, and no
+ * `--host` at any precedence at all (`channels/web.ts` explains).
+ *
+ * ## Identity is required at startup
+ *
+ * Unlike `approval channel cli`, which may merely *list* a queue, this verb
+ * exists to collect decisions: its only output is a page with Grant and Reject
+ * buttons on it. Starting a server whose buttons cannot record anything would
+ * spend a human's attention and then refuse their answer, so a missing or
+ * non-human identity is a usage error (2) before the socket is bound.
+ */
+import type { Server } from "node:http";
+import { type PayloadSource } from "../channels/tagging.js";
+import { WebChannel } from "../channels/web.js";
+import type { DecideOptions } from "../core/gate.js";
+import { type PolicyLoadResult } from "../core/policy-load.js";
+import type { Streams } from "./main.js";
+/**
+ * `channels.web.port` from a loaded policy, or `null`.
+ *
+ * A policy that does not load, does not declare `channels`, or declares a port
+ * that is not a usable TCP port yields `null` — which means the default, not a
+ * crash: an operator whose policy has a typo in an optional cosmetic field
+ * should still get a queue page.
+ */
+export declare function policyWebPort(load: PolicyLoadResult): number | null;
+export type PortResolution = {
+    ok: true;
+    port: number;
+} | {
+    ok: false;
+    message: string;
+};
+/** `--port` > policy `channels.web.port` > {@link WEB_DEFAULT_PORT}. */
+export declare function resolveWebPort(portFlag: string | null, fromPolicy: number | null): PortResolution;
+/**
+ * Payload material for one action key, from `--payload-dir` — the same shape
+ * `approval channel cli` uses, deliberately, so an operator's payload directory
+ * works with either channel.
+ *
+ * An override since APRV-28: with no flag the bytes come from the payload store
+ * beside the log, so the ordinary path needs no directory at all. This answers
+ * first for the keys it covers, and the store answers for the rest.
+ *
+ * The tagger re-hashes whatever this returns and refuses anything that does not
+ * match the recorded binding, so a wrong file produces a visible skip rather
+ * than a rendering of bytes the token would refuse to execute.
+ */
+export declare function payloadSource(dir: string, complain: (message: string) => void): PayloadSource;
+export interface StartWebChannelOptions {
+    /** The log to read the queue from, and to append decisions to. */
+    logPath: string;
+    /** The approver every decision is recorded against. Must be `human:<id>`. */
+    actor: string;
+    /** Where `APPROVAL.md` lives; passed to the tagger and to the gate. */
+    policy?: {
+        dir?: string;
+        file?: string;
+    };
+    /** Port to bind. `0` asks the OS for an ephemeral one (tests). */
+    port?: number;
+    /** Payload material for manual requests (SPEC.md §10.4). */
+    payload?: PayloadSource;
+    /** Where operational complaints go. Defaults to stderr. */
+    log?: (message: string) => void;
+    /** The display instant for each queue build. Injectable for tests. */
+    now?: () => string;
+    /** Extra gate options (an injected clock, a schema dir). */
+    gateOptions?: DecideOptions;
+}
+/** A running web channel. `close()` releases the socket. */
+export interface RunningWebChannel {
+    server: Server;
+    channel: WebChannel;
+    port: number;
+    close(): Promise<void>;
+}
+/**
+ * Start the server and wire it to the gate.
+ *
+ * Exported for the tests and for the M5 daemon: the verb below is a thin shell
+ * around this, and a caller that wants a queue page inside its own process
+ * should not have to spawn a CLI to get one.
+ */
+export declare function startWebChannel(options: StartWebChannelOptions): Promise<RunningWebChannel>;
+/**
+ * `approval channel web` — serve the queue until interrupted.
+ *
+ * Long-lived, like `approval channel telegram listen`: it returns a promise
+ * that settles on SIGINT/SIGTERM, which is why `main` treats `channel`
+ * specially. There is no `--once`: a page is fetched by a human whenever they
+ * choose to look, so "handle exactly one request and exit" would be a shape
+ * nobody wants. Tests drive {@link startWebChannel} directly instead.
+ */
+export declare function commandWeb(argv: string[], streams: Streams, cwd: string): number | Promise<number>;

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

@@ -0,0 +1,71 @@
+/**
+ * `approval channel cli` (APRV-23) — the zero-config channel, driven over the
+ * plugin contract rather than around it.
+ *
+ * There is no second decision path in this codebase and this verb is not one.
+ * It builds the pending queue with `channels/tagging.ts`, hands each request to
+ * `channels/cli.ts` for rendering, and registers a decision handler whose entire
+ * body is a call to `recordChannelDecision` — which calls the human-only
+ * `decide()` in `core/gate.ts`. Every gate rule (human actor, TTL, budgets,
+ * attestation, idempotency, compare-and-append) applies here unchanged, because
+ * nothing here reimplements any of them.
+ *
+ * ## Interactive, and deliberately not by default
+ *
+ * A prompt that blocks is a prompt that hangs a pipeline. So the verb is
+ * interactive only when stdin is a TTY, or when `--interactive` says so
+ * explicitly; `--json` is never interactive. Anything else lists the queue and
+ * exits 0. That rule is in `--help` because an agent that shells out to this
+ * verb must be able to predict, before it spawns anything, whether the child
+ * will return.
+ *
+ * ## The reading aids (APRV-197)
+ *
+ * Two of them, and they are different in kind. The deterministic one is the
+ * `command_breakdown` line: derived by the classifier from the bound bytes,
+ * marked `[computed] (classifier)`, free, and always present for a command this
+ * runtime's own tokenizer can read. The other is the model gloss, which costs a
+ * subprocess and 10-15 seconds and is marked `(model, unverified)` on the line
+ * itself. Until APRV-197 only the Telegram listener attached the second, so an
+ * operator deciding here read the agent's raw summary and nothing else; the two
+ * surfaces now share `cli/gloss-attach.ts`. See {@link glossRunner} for when a
+ * model is asked at all — only under `--gloss`, and never on the `--json` path,
+ * which is not interactive and has nobody waiting at it.
+ *
+ * ## Identity is declared, not proved
+ *
+ * `--as human:<id>`, else `APPROVAL_HUMAN`. The trust boundary is the local
+ * machine: anyone who can set that variable and write to the log is inside it,
+ * so a decision recorded here proves that *someone with local control* answered,
+ * not *who*. Stated in `--help` rather than implied, because a reader who
+ * believes this authenticates anybody would be wrong in a way that matters. The
+ * identity is required only when a decision could be recorded — listing the
+ * queue asks nothing of anyone.
+ *
+ * ## Where the payload comes from
+ *
+ * v0.1's log records `payload_hash`, never the payload bytes, so the material to
+ * render comes from the payload store beside the log — `.approval/payloads/`,
+ * written by `approval request --payload` (APRV-28) — which is why this verb
+ * needs no flag at all in the ordinary case. `--payload-dir` remains as an
+ * override for an operator whose bytes live elsewhere: one JSON file per action
+ * key, consulted first. `channels/tagging.ts` hashes whatever it is given and refuses
+ * anything that does not match the recorded binding, so a wrong file is a
+ * refusal and never a rendering. A manual request with no material is *skipped*
+ * and reported — visibly, never silently, because a request missing from a queue
+ * is a request nobody will approve.
+ *
+ * ## The asynchronous exit code
+ *
+ * `main()` is synchronous by contract: `cli.js` assigns its return value to
+ * `process.exitCode`. The prompt loop is asynchronous (readline), so the
+ * interactive path returns {@link EXIT_OK} to `main` and assigns the real code
+ * to `process.exitCode` when the loop settles. Node exits with the last value
+ * assigned, so a refusal still exits 1. Every synchronous path — `--json`, a
+ * non-TTY listing, a usage error, an I/O fact — returns its code the ordinary
+ * way.
+ */
+import type { Streams } from "./main.js";
+export declare function commandChannelCli(argv: string[], streams: Streams, cwd: string): number;
+/** `approval channel <subcommand>` — `cli`, `web` (APRV-25), `telegram`. */
+export declare function commandChannel(argv: string[], streams: Streams, cwd: string): number | Promise<number>;

package/dist/src/cli/checkpoint-tap.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The checkpoint tap: custody, the offer, the prompt text, the signature
+ * (APRV-257, the delivery half of APRV-220).
+ *
+ * APRV-220 built the record and gave a human exactly one way to sign one:
+ * `approval log checkpoint` at a terminal, remembered. This file is what makes
+ * it happen without the remembering, and it is deliberately the ONLY file
+ * between a channel and a signature.
+ *
+ * ## Why custody lives here now
+ *
+ * `core/checkpoint.ts` takes the private key as a value and reads it from
+ * nowhere, so that one file decides where a checkpoint key may come from. Until
+ * this task that file was `cli/log-checkpoint.ts`, because the terminal verb was
+ * the only caller. It is not any more: the Telegram listener and the CLI channel
+ * both sign now. So the decision moved here rather than being copied, and
+ * `cli/log-checkpoint.ts` calls {@link resolveCheckpointKey} like everyone else.
+ * There is still exactly one place to read to learn every way a key can reach a
+ * signature, which was the whole property.
+ *
+ * Two sources, in this order, unchanged from APRV-220:
+ *
+ * 1. `--key-file <path>`, for a key an operator keeps outside the vault.
+ * 2. The credential vault, under `approval.checkpoint.key`. Encrypted at rest
+ *    under the passphrase `vault.passphrase_env` names, which
+ *    `core/child-env.ts` strips from every child this runtime spawns
+ *    (APRV-205), behind a file whose reading classifies `account.credential`.
+ *
+ * There is no `--key` flag and no environment variable holding the key.
+ *
+ * ## Why an agent-launched process cannot reach any of this
+ *
+ * Three independent locks, and the tap adds none of its own — it inherits all
+ * three, which is why the tap can be built at all:
+ *
+ * 1. **Classification.** `approval log checkpoint` and `approval setup
+ *    checkpoint` classify `policy.core` in `core/command-class.ts`, which the
+ *    reference policy holds `human-only`, so the Claude Code hook denies both
+ *    with `hook-class-human-only` before a process starts.
+ * 2. **The passphrase.** `core/child-env.ts` strips `vault.passphrase_env` from
+ *    every child this runtime spawns, so a process an agent launched cannot
+ *    open the vault even if it ran this code.
+ * 3. **The launch.** The listener holds the passphrase because a HUMAN
+ *    exported it into the shell they started `approval up` in. Nothing an agent
+ *    can do puts it into a process the agent controls.
+ *
+ * `tests/checkpoint-tap.test.ts` proves the first two and proves the third
+ * structurally: the hook's module graph never reaches this file.
+ *
+ * ## What the human is shown is what gets signed
+ *
+ * The offer carries a `(seq, hash)`; the prompt prints it; the signature covers
+ * it. The head may have moved several times over between the prompt and the tap
+ * — a phone is in a pocket and a daemon is not — and
+ * {@link ../core/checkpoint.js appendCheckpointAt} signs the head that was on
+ * the screen, checking first that this chain still carries those bytes at that
+ * seq. APRV-220's verify rule (a checkpoint signs any seq below its own) exists
+ * precisely so this is a legal record rather than a clever one.
+ */
+import { type CheckpointOffer } from "../core/checkpoint.js";
+/** Where a policy is, spelled the way every CLI verb spells it. */
+export interface PolicyWhere {
+    file?: string;
+    dir?: string;
+}
+/** Everything a surface needs to offer and take a checkpoint. */
+export interface CheckpointTap {
+    logPath: string;
+    policy: PolicyWhere;
+    /** `--key-file`, absolute, or `null` for the vault. */
+    keyFile: string | null;
+    /** An explicit vault path, or `null` for the one beside the log. */
+    vault: string | null;
+    schemaDir?: string;
+}
+/** Why no key could be had. One code: the repair is the message, not a branch. */
+export declare const CHECKPOINT_KEY_REFUSAL = "checkpoint-key-unreadable";
+export type KeyResolution = {
+    ok: true;
+    privateKey: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * The private key, or a refusal naming which source failed and how to fix it.
+ *
+ * Moved verbatim from `cli/log-checkpoint.ts` (APRV-257) so that the terminal
+ * verb, the Telegram listener and the CLI channel share one answer to "where
+ * may a checkpoint key come from". The sentences are unchanged: an operator who
+ * has seen this refusal once should not meet it in new words on another
+ * surface.
+ */
+export declare function resolveCheckpointKey(keyFile: string | null, logPath: string, vaultFlag: string | null, policyWhere: PolicyWhere, cwd: string, 
+/**
+ * Where the passphrase is read from. `process.env` in production.
+ *
+ * A seam and not a back door, and the same one `setup adapter` carries: it
+ * goes through {@link passphraseFrom}, which is the function `approval vault
+ * set` uses, and it never resolves `.approval/env` (SPEC.md §11.1 invariant
+ * 7). Injectable so a suite can prove the vault path without mutating an
+ * environment every other test in the process shares.
+ */
+env?: NodeJS.ProcessEnv): KeyResolution;
+/**
+ * The checkpoint this log is owed, or `null`.
+ *
+ * Reads the policy first and gives up the moment it names no cadence, so a
+ * dispatch cycle on a gate that has never turned checkpoints on pays one policy
+ * load and no log walk. Everything after that is
+ * {@link ../core/checkpoint.js checkpointDue} over verified records, which is
+ * the same call the daemon's warning and doctor's row make: three surfaces,
+ * one rule, no arrangement in which they disagree.
+ *
+ * A log that does not verify produces no offer and no complaint. A chain that
+ * is not fit to be read is not fit to be signed either, and the surfaces that
+ * exist to shout about a bad chain — `approval log verify`, the daemon's
+ * re-proof, doctor's `log` row — are already shouting.
+ */
+export declare function checkpointOfferFor(tap: CheckpointTap, now?: number): CheckpointOffer | null;
+/**
+ * What a human reads before they tap, on every channel.
+ *
+ * One text for every surface, because the thing being consented to is identical
+ * and a phone that phrased it differently from a terminal would be two claims
+ * about one gesture. The `(seq, hash)` is first and whole: it is the entire
+ * content of the signature, and an approver who cannot see what they are
+ * signing is not approving anything.
+ *
+ * The last line is the one that keeps this honest. Declining costs nothing —
+ * there is no path in this runtime from a checkpoint that is due to a refusal
+ * of anything — and a prompt that implied otherwise would be manufacturing
+ * pressure for a signature.
+ */
+export declare function checkpointPromptLines(offer: CheckpointOffer): string[];
+export type CheckpointTapResult = {
+    ok: true;
+    seq: number;
+    signed: {
+        seq: number;
+        hash: string;
+    };
+    fingerprint: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Sign one head and append the record, on the machine the channel runs on.
+ *
+ * `head` is the `(seq, hash)` that was on the screen, handed back by the
+ * channel unchanged. It is a head rather than the whole offer on purpose: by
+ * tap time the offer's cadence arithmetic is hours stale and nothing should be
+ * tempted to read it, while the head is the one part that must survive
+ * verbatim.
+ *
+ * The key is resolved at TAP time and not at offer time, and that ordering is
+ * the point: a prompt sitting on a phone for an hour holds no key material
+ * anywhere, and a listener whose vault the operator has since re-keyed refuses
+ * the tap with a sentence rather than signing with something stale.
+ */
+export declare function signCheckpointOffer(tap: CheckpointTap, head: {
+    seq: number;
+    hash: string;
+}, actor: string, channel: string, cwd: string): CheckpointTapResult;
+/** What a channel says on the message it just edited, once a tap has landed. */
+export declare function checkpointSignedLines(result: CheckpointTapResult): string[];

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

@@ -0,0 +1,2 @@
+import type { Streams } from "./main.js";
+export declare function commandCodex(argv: string[], streams: Streams, cwd: string): number;

package/dist/src/cli/codex.js

@@ -0,0 +1,172 @@
+import { resolve } from "node:path";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import { CODEX_HELP } from "./help.js";
+import { usageErrorText } from "./usage.js";
+import { strictDoctor } from "../codex/doctor.js";
+import { checkBundle, prepareBundle } from "../codex/templates.js";
+function emitError(streams, json, code, message) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code, message } })}\n`);
+    else
+        streams.err(`approval: ${message}\n`);
+}
+function usage(streams, json, message) {
+    if (json)
+        emitError(streams, true, "usage", message);
+    else
+        streams.err(usageErrorText(message, CODEX_HELP));
+    return EXIT_USAGE;
+}
+function required(flags, name) {
+    const value = stringFlag(flags, name);
+    return value === null || value.length === 0 ? null : value;
+}
+export function commandCodex(argv, streams, cwd) {
+    const json = argv.includes("--json");
+    const subcommand = argv[0];
+    const rest = argv.slice(1);
+    if (subcommand === undefined || subcommand === "--help" || subcommand === "-h") {
+        streams.out(`${CODEX_HELP}\n`);
+        return subcommand === undefined ? EXIT_USAGE : EXIT_OK;
+    }
+    if (subcommand === "prepare") {
+        const parsed = parseFlags(rest, {
+            "--instance": "string",
+            "--workspace": "string",
+            "--primary": "string",
+            "--install-root": "string",
+            "--output": "string",
+            "--codex": "string",
+            "--node": "string",
+            "--json": "boolean",
+            "--help": "boolean",
+            "-h": "boolean",
+        });
+        if (!parsed.ok)
+            return usage(streams, json, parsed.message);
+        if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+            streams.out(`${CODEX_HELP}\n`);
+            return EXIT_OK;
+        }
+        if (parsed.positionals.length > 0)
+            return usage(streams, json, "prepare takes flags only");
+        const names = ["--instance", "--workspace", "--primary", "--install-root", "--output", "--codex", "--node"];
+        const values = Object.fromEntries(names.map((name) => [name, required(parsed.flags, name)]));
+        const missing = names.find((name) => values[name] === null);
+        if (missing !== undefined)
+            return usage(streams, json, `prepare requires ${missing}`);
+        const result = prepareBundle({
+            instanceId: values["--instance"],
+            workspace: resolve(cwd, values["--workspace"]),
+            primary: resolve(cwd, values["--primary"]),
+            installRoot: resolve(cwd, values["--install-root"]),
+            output: resolve(cwd, values["--output"]),
+            codexExecutable: resolve(cwd, values["--codex"]),
+            nodeExecutable: resolve(cwd, values["--node"]),
+        });
+        if (!result.ok) {
+            emitError(streams, json, result.code, result.message);
+            return result.code === "manifest-invalid" || result.code === "output-overlap" ? EXIT_INTEGRITY : EXIT_IO;
+        }
+        if (json)
+            streams.out(`${JSON.stringify({ ok: true, inert: true, output: result.output, files: result.files, manifest: result.manifest })}\n`);
+        else
+            streams.out(`Prepared inert Codex host bundle at ${result.output}. Review it; no host configuration changed.\n`);
+        return EXIT_OK;
+    }
+    if (subcommand === "setup") {
+        const parsed = parseFlags(rest, {
+            "--check": "string",
+            "--json": "boolean",
+            "--help": "boolean",
+            "-h": "boolean",
+        });
+        if (!parsed.ok)
+            return usage(streams, json, parsed.message);
+        if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+            streams.out(`${CODEX_HELP}\n`);
+            return EXIT_OK;
+        }
+        if (parsed.positionals.length > 0)
+            return usage(streams, json, "setup takes flags only");
+        const directory = required(parsed.flags, "--check");
+        if (directory === null)
+            return usage(streams, json, "setup requires --check <bundle>");
+        const result = checkBundle(resolve(cwd, directory));
+        if (!result.ok) {
+            emitError(streams, json, result.code, result.message);
+            return EXIT_INTEGRITY;
+        }
+        const response = {
+            ok: true,
+            inert: true,
+            ready: false,
+            bundle: resolve(cwd, directory),
+            files: result.files,
+            reason: "broker-and-runner-not-shipped",
+        };
+        if (json)
+            streams.out(`${JSON.stringify(response)}\n`);
+        else
+            streams.out("Bundle is internally consistent and inert. Broker and runner are not shipped; do not activate it.\n");
+        return EXIT_OK;
+    }
+    if (subcommand === "doctor") {
+        const parsed = parseFlags(rest, {
+            "--manifest": "string",
+            "--strict": "boolean",
+            "--json": "boolean",
+            "--help": "boolean",
+            "-h": "boolean",
+        });
+        if (!parsed.ok)
+            return usage(streams, json, parsed.message);
+        if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+            streams.out(`${CODEX_HELP}\n`);
+            return EXIT_OK;
+        }
+        if (parsed.positionals.length > 0)
+            return usage(streams, json, "doctor takes flags only");
+        if (!boolFlag(parsed.flags, "--strict"))
+            return usage(streams, json, "doctor requires --strict");
+        const manifest = required(parsed.flags, "--manifest");
+        if (manifest === null)
+            return usage(streams, json, "doctor requires --manifest <path>");
+        const result = strictDoctor(resolve(cwd, manifest));
+        if (!result.ok) {
+            if (json)
+                streams.err(`${JSON.stringify({ ok: false, ready: false, error: { code: result.code, message: result.message }, findings: result.report?.findings ?? [] })}\n`);
+            else {
+                streams.err(`approval: ${result.message}\n`);
+                for (const finding of result.report?.findings ?? []) {
+                    streams.err(`  ${finding.code}${finding.path === undefined ? "" : ` ${finding.path}`}: ${finding.message}\n`);
+                }
+            }
+            return EXIT_INTEGRITY;
+        }
+        return EXIT_OK;
+    }
+    if (subcommand === "start" || subcommand === "serve") {
+        const parsed = parseFlags(rest, {
+            "--manifest": "string",
+            "--json": "boolean",
+            "--help": "boolean",
+            "-h": "boolean",
+        });
+        if (!parsed.ok)
+            return usage(streams, json, parsed.message);
+        if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+            streams.out(`${CODEX_HELP}\n`);
+            return EXIT_OK;
+        }
+        if (parsed.positionals.length > 0)
+            return usage(streams, json, `${subcommand} takes flags only`);
+        if (required(parsed.flags, "--manifest") === null)
+            return usage(streams, json, `${subcommand} requires --manifest <path>`);
+        emitError(streams, json, "codex-not-ready", `codex ${subcommand} is not implemented until APRV-325.2 and APRV-325.3 provide the broker and runner`);
+        return EXIT_INTEGRITY;
+    }
+    return usage(streams, json, `unknown codex subcommand ${JSON.stringify(subcommand)}`);
+}
+//# sourceMappingURL=codex.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../../src/cli/codex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEnE,SAAS,SAAS,CAAC,OAAgB,EAAE,IAAa,EAAE,IAAY,EAAE,OAAe;IAC/E,IAAI,IAAI;QAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;;QACtE,OAAO,CAAC,GAAG,CAAC,aAAa,OAAO,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,KAAK,CAAC,OAAgB,EAAE,IAAa,EAAE,OAAe;IAC7D,IAAI,IAAI;QAAE,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;;QAChD,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;IACtD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,QAAQ,CAAC,KAAuC,EAAE,IAAY;IACrE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACtC,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,OAAgB,EAAE,GAAW;IACxE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QAC/E,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,IAAI,CAAC,CAAC;QAC/B,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;IACzD,CAAC;IAED,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE;YAC9B,YAAY,EAAE,QAAQ;YACtB,aAAa,EAAE,QAAQ;YACvB,WAAW,EAAE,QAAQ;YACrB,gBAAgB,EAAE,QAAQ;YAC1B,UAAU,EAAE,QAAQ;YACpB,SAAS,EAAE,QAAQ;YACnB,QAAQ,EAAE,QAAQ;YAClB,QAAQ,EAAE,SAAS;YACnB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5D,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;YACrE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,IAAI,CAAC,CAAC;YAC/B,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,0BAA0B,CAAC,CAAC;QAC3F,MAAM,KAAK,GAAG,CAAC,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;QACrH,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7F,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAC5D,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,oBAAoB,OAAO,EAAE,CAAC,CAAC;QACtF,MAAM,MAAM,GAAG,aAAa,CAAC;YAC3B,UAAU,EAAE,MAAM,CAAC,YAAY,CAAW;YAC1C,SAAS,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,aAAa,CAAW,CAAC;YACxD,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,WAAW,CAAW,CAAC;YACpD,WAAW,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,gBAAgB,CAAW,CAAC;YAC7D,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAW,CAAC;YAClD,eAAe,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,CAAW,CAAC;YAC1D,cAAc,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAW,CAAC;SACzD,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YACtD,OAAO,MAAM,CAAC,IAAI,KAAK,kBAAkB,IAAI,MAAM,CAAC,IAAI,KAAK,gBAAgB,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC;QAC3G,CAAC;QACD,IAAI,IAAI;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC;;YAC1I,OAAO,CAAC,GAAG,CAAC,uCAAuC,MAAM,CAAC,MAAM,+CAA+C,CAAC,CAAC;QACtH,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE;YAC9B,SAAS,EAAE,QAAQ;YACnB,QAAQ,EAAE,SAAS;YACnB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5D,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;YACrE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,IAAI,CAAC,CAAC;YAC/B,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,wBAAwB,CAAC,CAAC;QACzF,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACpD,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,iCAAiC,CAAC,CAAC;QACvF,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YACtD,OAAO,cAAc,CAAC;QACxB,CAAC;QACD,MAAM,QAAQ,GAAG;YACf,EAAE,EAAE,IAAI;YACR,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC;YAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,+BAA+B;SACxC,CAAC;QACF,IAAI,IAAI;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;;YAClD,OAAO,CAAC,GAAG,CAAC,qGAAqG,CAAC,CAAC;QACxH,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE;YAC9B,YAAY,EAAE,QAAQ;YACtB,UAAU,EAAE,SAAS;YACrB,QAAQ,EAAE,SAAS;YACnB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5D,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;YACrE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,IAAI,CAAC,CAAC;YAC/B,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,yBAAyB,CAAC,CAAC;QAC1F,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,0BAA0B,CAAC,CAAC;QACjG,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QACtD,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,mCAAmC,CAAC,CAAC;QACxF,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,IAAI,IAAI;gBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;iBACrK,CAAC;gBACJ,OAAO,CAAC,GAAG,CAAC,aAAa,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;gBAC7C,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;oBACpD,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;gBAChH,CAAC;YACH,CAAC;YACD,OAAO,cAAc,CAAC;QACxB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE;YAC9B,YAAY,EAAE,QAAQ;YACtB,QAAQ,EAAE,SAAS;YACnB,QAAQ,EAAE,SAAS;YACnB,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5D,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;YACrE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,IAAI,CAAC,CAAC;YAC/B,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,UAAU,mBAAmB,CAAC,CAAC;QACjG,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,UAAU,6BAA6B,CAAC,CAAC;QAC3H,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,SAAS,UAAU,mFAAmF,CAAC,CAAC;QACpJ,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,4BAA4B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;AACxF,CAAC"}

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

@@ -0,0 +1,61 @@
+/**
+ * `approval coverage` — observed side effects, joined to the verified log
+ * (APRV-245, SPEC.md §10.1).
+ *
+ * ## What it answers
+ *
+ * "Here is everything the witnesses outside this runtime say happened, and here
+ * is what the log says about each one." Nothing more: the join is
+ * `core/coverage.ts`, the witnesses are `core/coverage-sources/`, and this file
+ * is argument parsing, source selection, and the rendering of a table.
+ *
+ * ## Why it exits 0 with gaps
+ *
+ * Because it is INFORMATIONAL, on exactly SPEC.md §10.1's rule for the APRV-145
+ * harness-start coverage in `approval status`: a coverage measurement is not an
+ * integrity verdict, and a control an operator learns to silence is worse than
+ * one that reports beside the verdict. A gap here is a question ("was this
+ * effect ever declared?"), and questions with legitimate answers must not fail
+ * a build. The two codes it can still emit are the filesystem's: 2 for a usage
+ * error and 4 for a log this process could not read, plus 3 for a torn tail,
+ * because a log it could not read is a report it did not make.
+ *
+ * ## Why a source that cannot be reached is not a gap
+ *
+ * A source reports `available: false` with a reason, and its effects are absent
+ * rather than uncovered. "`gh` is not on PATH" and "`gh` saw nothing" are
+ * different facts, and a report that flattened them would let a broken tool read
+ * as a clean bill of health. Every unavailable source prints its reason on its
+ * own line.
+ *
+ * ## Writes nothing, reads only verified records
+ *
+ * The log is read through `readVerifiedRecords` (SPEC.md §11.1 invariant 1) and
+ * nothing here appends, renders, or caches. Running it changes no state any
+ * later verdict depends on, which is what lets it be safe to run on a timer.
+ */
+import { type CoverageEntry } from "../core/coverage.js";
+import type { Streams } from "./main.js";
+/** One source's contribution to the report, ready to print or serialize. */
+interface RenderedSource {
+    name: string;
+    available: boolean;
+    reason: string | null;
+    entries: CoverageEntry[];
+    observed: number;
+    covered: number;
+}
+/**
+ * The evidence column, as one short string a reader can act on.
+ *
+ * The qualifier says how the record was found, so that a weaker match is never
+ * read as a stronger one and the strongest is not read as the ordinary one.
+ * `(id)` is APRV-251's: the record names this exact effect by the provider's own
+ * identifier, which is a different claim from "a record of this class sits in
+ * this effect's window" and prints as one.
+ */
+export declare function evidenceText(entry: CoverageEntry): string;
+/** The coverage line one source prints, in the shape the help promises. */
+export declare function coverageLine(source: RenderedSource): string;
+export declare function commandCoverage(argv: string[], streams: Streams, cwd: string): Promise<number>;
+export {};