approval-md 0.1.0 → 0.2.0

package/dist/src/channels/web.d.ts

@@ -0,0 +1,341 @@
+/**
+ * The local web queue channel (SPEC.md §5.1 `channels.web.port`, §9, §10.3,
+ * §10.4, §11 — APRV-25).
+ *
+ * The third reference channel, and the only *pull* one. `cli` asks a question
+ * and waits for an answer; `telegram` pushes a message at a human who is
+ * elsewhere. This one serves a page: the queue sits at
+ * `http://127.0.0.1:4680/` and a human looks at it when they choose to. That
+ * difference is the design, not an accident of the transport — see "notify is a
+ * no-op" below.
+ *
+ * Everything the contract says about a channel still holds:
+ *
+ * - **It decides nothing.** A submitted form becomes a {@link ChannelDecision}
+ *   handed to the handler the runtime registered, and that handler calls
+ *   `recordChannelDecision` / `recordBatchDecisions`, which call the human-only
+ *   `decide()` in `core/gate.ts`. TTL lapse, budget re-check, attestation,
+ *   idempotency and compare-and-append apply to a button on a web page exactly
+ *   as they apply to `approval grant`.
+ * - **It writes no log line and holds no decision state.** The only memory here
+ *   is the map from action key to delivery id, which is delivery bookkeeping.
+ *   It dies with the process; the approvals live in the log.
+ * - **It renders the computed/claimed split** (§9) and the full payload for
+ *   manual actions (§10.4), and reports what it rendered through
+ *   {@link WebChannel.lastRendered} so `channels/conformance.ts` can check it.
+ *
+ * ## 127.0.0.1 ONLY, and there is deliberately no --host
+ *
+ * {@link WebChannel.start} calls `listen(port, "127.0.0.1")` with the host
+ * **hard-coded**. There is no option, no flag and no environment variable that
+ * widens it, and adding one would be a SPEC.md amendment rather than a feature:
+ * this server has **no authentication at all** (see below), so the loopback
+ * interface is the entire access-control mechanism. A `--host 0.0.0.0` would
+ * turn "anyone with local access can approve" into "anyone on the coffee shop
+ * wifi can approve", silently, from a flag that reads like a convenience. The
+ * bound address is asserted by `tests/channels-web.test.ts`.
+ *
+ * ## No auth in v0.1 — the trust boundary, stated twice
+ *
+ * SPEC.md §11: *"Human identity in v0.1 is config-declared (an environment
+ * variable or flag); the trust boundary is the local machine, and anyone who
+ * can set that configuration and write to the log is inside it."*
+ *
+ * This channel authenticates nobody. Every decision it collects is recorded
+ * against the human actor the **runtime** was started with (`--as` /
+ * `APPROVAL_HUMAN`), so the guarantee is "someone with access to this machine
+ * approved", never "that specific person approved". Because the page *is* the
+ * decision surface, that caveat is printed on the page itself
+ * ({@link TRUST_BANNER}) as well as in `--help` and here: a human reading a
+ * queue in a browser tab should not have to have read the source to know what
+ * their click proves.
+ *
+ * ## CSRF — inside the stated boundary, with cheap hardening. FLAGGED.
+ *
+ * There is no CSRF token in v0.1, and the reasoning is worth writing down
+ * because it is a deliberate omission rather than an oversight. A CSRF token
+ * defends a *session* — it stops a page on another origin from acting as an
+ * authenticated user. Here there is no session and no authentication: anything
+ * that can open a socket to 127.0.0.1:4680 can already POST directly, token or
+ * no token, because the trust boundary is the whole local machine. A token
+ * would defend against exactly one attacker: a web page, in a browser on this
+ * machine, that the human visited, that guessed the port. That attacker is
+ * inside the §11 boundary as written — and is also the most realistic one, so:
+ *
+ * - A same-origin **soft check** rejects (403) any POST whose `Origin` (or
+ *   failing that, `Referer`) names something other than this server's own
+ *   loopback origins. It is best effort: a request with neither header is
+ *   allowed, because `curl`, `fetch` in a test, and a form POST from an older
+ *   browser all send neither, and refusing them would break the documented
+ *   scripting path to buy nothing (an attacker can omit a header too).
+ * - **Flagged for human review**: if v0.2 puts this server behind anything
+ *   resembling a session, or widens the bind address, this stance must be
+ *   revisited and a real anti-CSRF token added. The soft check is a speed bump,
+ *   not a control.
+ *
+ * ## The token IS shown on the page — FLAGGED, and it differs from telegram
+ *
+ * `channels/telegram.ts` refuses to put an execution token in the chat, and
+ * prints it on the listener's stdout instead: a chat transcript lives on
+ * someone else's servers and is readable by anyone later added to the chat.
+ * This channel does the opposite and shows the raw token **once**, in the
+ * response page for the grant that minted it. The asymmetry is the point:
+ *
+ * - the page is served over loopback to the human who is deciding, right now;
+ * - the response is generated per request and persisted nowhere — no file, no
+ *   log line, no `lastRendered()` entry (the notice is rendered and dropped);
+ * - the alternative is worse. On telegram the approver and the terminal are
+ *   often the same person one room apart; here the browser *is* the surface the
+ *   human is looking at, and sending them to hunt for a token on a daemon's
+ *   stdout would push them toward copying tokens out of log files.
+ *
+ * The token is never written to the log (which holds only its SHA-256), never
+ * put in a URL (a query string lands in history), and never repeated: reload
+ * the response and it is gone. The channel itself does not even hold it — the
+ * runtime returns the notice text through {@link WebChannelOptions.decisionNotice}
+ * at render time, so a channel that logged its own outcomes would log nothing
+ * sensitive. **Flagged for human review** all the same: it is the one place in
+ * this codebase where a credential is rendered into a document a browser
+ * handles, and browsers cache, autofill and sync more than one expects.
+ *
+ * ## notify() is a no-op — pull, not push
+ *
+ * The queue *is* the notification surface. `notify()` records the request as
+ * deliverable (so a decision can be routed back to it), returns a synthetic
+ * delivery id, and sends nothing anywhere: there is nowhere to send it, since a
+ * web page is fetched rather than delivered. Everything the human sees is
+ * produced by `GET /`, which re-renders from the runtime's live queue
+ * ({@link WebChannelOptions.refresh}) whenever one is supplied. This is why
+ * `lastRendered()` reflects the most recent *render* — a GET when there has
+ * been one, the last `notify()` otherwise — and why both go through the same
+ * {@link renderWebRequest}: the conformance suite must be inspecting the thing a
+ * browser was actually served.
+ *
+ * ## Zero JavaScript required
+ *
+ * Every flow — grant, reject with a note, select-and-batch — is plain
+ * `<form method="post" enctype="application/x-www-form-urlencoded">`. The batch
+ * checkboxes live outside the batch form and are attached to it with the HTML5
+ * `form=` attribute (nested forms are illegal), so one page can carry per-request
+ * forms *and* a batch gesture with no script at all. A four-line inline script
+ * offers "select all" as a convenience; disable scripting and every flow still
+ * works, which is checked by the tests driving the server with `fetch` alone.
+ */
+import { type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { type PromptLayout } from "../core/prompt-layout.js";
+import type { ChannelBatch, ChannelDecision, ChannelHealth, ChannelRequest, DecisionOutcome, DeliveryId, RenderedRequest, TestableChannel } from "./contract.js";
+/** SPEC.md §5.1 `channels.web.port`. Used when policy and flags say nothing. */
+export declare const WEB_DEFAULT_PORT = 4680;
+/**
+ * The only address this server ever binds. Hard-coded; see the module header.
+ *
+ * Exported so the tests can assert the bound address against a constant rather
+ * than a literal they could drift from — not so a caller can substitute one.
+ */
+export declare const WEB_LOOPBACK_HOST = "127.0.0.1";
+/** The largest form body accepted. A queue page's POST is a few hundred bytes. */
+export declare const WEB_MAX_BODY_BYTES: number;
+/** The §11 caveat, rendered at the top of every page. */
+export declare const TRUST_BANNER: string;
+/** The full-payload delimiters (SPEC.md §10.4). Pinned by tests. */
+export declare const PAYLOAD_BEGIN = "--- BEGIN FULL PAYLOAD";
+export declare const PAYLOAD_END = "--- END FULL PAYLOAD ---";
+/** Section headings. The computed/claimed split a reader must not have to infer. */
+export declare const COMPUTED_HEADING = "COMPUTED \u2014 derived by the runtime from the verified log, the attested policy, the budget evaluator, the payload bytes and the clock";
+export declare const CLAIMED_HEADING_PREFIX = "CLAIMED \u2014 authored by";
+export declare const CLAIMED_HEADING_SUFFIX = "NOT verified by the runtime";
+/** Badge markers, mirroring `channels/cli.ts` so the two channels read alike. */
+export declare const COMPUTED_MARKER = "[computed]";
+export declare const CLAIMED_MARKER = "[claimed]";
+/**
+ * Escape every character that could change the structure of the document.
+ *
+ * A superset of `channels/telegram.ts`'s three: this channel interpolates into
+ * HTML **attribute** positions (checkbox values carry action keys, form ids
+ * carry them too), where a bare quote is as dangerous as a bare `<`. Applied
+ * uniformly to every interpolated value without exception — the claimed fields
+ * and the payload are authored by the party under oversight, and they are the
+ * entire injection surface of this page.
+ */
+export declare function escapeHtml(text: string): string;
+/**
+ * One field's value as display text. Deliberately total: an unrecognized shape
+ * is JSON-stringified rather than dropped, because a field the runtime tagged
+ * and the channel silently omitted is a field the approver did not see.
+ */
+export declare function formatValue(field: string, value: unknown): string;
+/** One rendered line, and the request member it came from. */
+export interface WebLine {
+    field: string;
+    kind: "computed" | "claimed";
+    text: string;
+    origin: string;
+}
+/** The rendering split for one request; the HTML below is built from exactly this. */
+export interface WebRendering {
+    actionKey: string;
+    computed: WebLine[];
+    claimed: WebLine[];
+    /** The claimed author, for the section heading. */
+    author: string;
+    /** The delimited payload region, or `null` when the request carries none. */
+    payloadText: string | null;
+}
+/** Build the split. Pure: no I/O, no clock, no HTML. */
+export declare function renderWebRequest(request: ChannelRequest, layout?: PromptLayout): WebRendering;
+/**
+ * The runtime's per-decision notice: text shown ONCE on the response page and
+ * kept nowhere.
+ *
+ * This is how a grant's raw execution token reaches the human without the
+ * channel ever holding it: `recordChannelDecision` returns the token to the
+ * *runtime*, the runtime returns this string at render time, the channel
+ * escapes it into one response and forgets it. It is not stored, not repeated
+ * on the next GET, and never included in {@link WebChannel.lastRendered}.
+ */
+export type WebDecisionNotice = (decision: ChannelDecision, outcome: DecisionOutcome) => string | null | undefined;
+/** One batch member's result, as the runtime reports it back to the channel. */
+export interface WebBatchOutcome {
+    action_key: string;
+    outcome: DecisionOutcome;
+    /** Shown once on the response page (the token). Never stored. */
+    notice?: string;
+}
+/**
+ * The runtime's batch recorder. Registered with
+ * {@link WebChannel.onBatchDecision}; its body is a call to
+ * `channels/batch.ts`'s `recordBatchDecisions`, which is one `decide()` per
+ * member. When no batch handler is registered the channel falls back to the
+ * unit handler once per member with `batchDeliveryId` set — identical
+ * semantics, since `recordChannelDecision` encodes the id the same way.
+ */
+export type WebBatchHandler = (decisions: ChannelDecision[], batchDeliveryId: DeliveryId) => WebBatchOutcome[] | Promise<WebBatchOutcome[]>;
+export interface WebChannelOptions {
+    /** Port to bind. `0` asks the OS for an ephemeral one (tests). */
+    port?: number;
+    /** Channel name recorded for audit. Defaults to `web`. */
+    name?: string;
+    /**
+     * Which rows the page shows (APRV-218), from `channels.web.prompt`.
+     *
+     * Resolved by the verb, which has already loaded the policy; this channel
+     * neither reads a policy file nor holds an opinion about what an operator
+     * should see. Defaults to {@link WEB_PROMPT_LAYOUT}, so a channel constructed
+     * without one renders exactly what it rendered before the key existed.
+     */
+    layout?: PromptLayout;
+    /**
+     * The runtime's live pending queue, re-read on every GET.
+     *
+     * Optional: without it the page shows whatever was `notify`d. With it the
+     * page is a projection of the log as of the moment it was fetched, which is
+     * what makes a decided request disappear from the queue on the next reload.
+     * The channel never reads the log itself — this function belongs to the
+     * runtime, which is the only thing allowed to.
+     */
+    refresh?: () => ChannelRequest[];
+    /** Per-decision one-shot notice (the execution token). See {@link WebDecisionNotice}. */
+    decisionNotice?: WebDecisionNotice;
+    /** The configured approver, for display only. Never used to authorize. */
+    actorLabel?: string;
+    /** Where operational complaints go. Defaults to stderr. */
+    log?: (message: string) => void;
+}
+/** Delivery and traffic counters. Never decision state. */
+export interface WebStats {
+    /** Requests registered by `notify`. */
+    notified: number;
+    /** `GET /` renders served. */
+    views: number;
+    /** Gestures handed to the runtime's handler. */
+    decisions: number;
+    /** POSTs refused before the handler: bad form, missing note, cross-origin. */
+    refused: number;
+}
+export declare class WebChannel implements TestableChannel {
+    readonly name: string;
+    private readonly configuredPort;
+    private readonly refresh;
+    private readonly notice;
+    private readonly actorLabel;
+    private readonly complain;
+    private handler;
+    private batchHandler;
+    /** Everything ever delivered, by action key. Delivery bookkeeping only. */
+    private readonly deliveries;
+    /** What the last render showed, in order. */
+    private pending;
+    private rendered;
+    private httpServer;
+    private counter;
+    private readonly counters;
+    /** The policy's row layout for this channel (APRV-218). Pure input to the rendering. */
+    private readonly layout;
+    constructor(options?: WebChannelOptions);
+    /**
+     * Register a request (or a batch) as deliverable and return its delivery id.
+     *
+     * Sends nothing: the queue page is pulled, not pushed (see the module
+     * header). The rendering split is computed here anyway, so `lastRendered()`
+     * is meaningful before anyone has opened a browser — and it is computed by
+     * the same {@link renderWebRequest} that produces the served HTML.
+     */
+    notify(target: ChannelRequest | ChannelBatch): DeliveryId;
+    onDecision(handler: (decision: ChannelDecision) => DecisionOutcome): void;
+    /** Register the runtime's batch recorder. Optional; see {@link WebBatchHandler}. */
+    onBatchDecision(handler: WebBatchHandler): void;
+    health(): ChannelHealth;
+    /** The most recent rendering — a GET when there has been one, else `notify`. */
+    lastRendered(): RenderedRequest[];
+    stats(): WebStats;
+    /** The bound address, or `null` when the server is not listening. */
+    address(): AddressInfo | null;
+    /** The bound port, or the configured one before {@link start}. */
+    get port(): number;
+    /** The underlying server, for tests that assert on the socket itself. */
+    get server(): Server | null;
+    /** The page's own origin, as a browser would send it. */
+    get origin(): string;
+    /**
+     * Bind and serve — on `127.0.0.1` and nowhere else.
+     *
+     * The host argument is a constant. See the module header for why there is
+     * deliberately no option to widen it.
+     */
+    start(): Promise<AddressInfo>;
+    /** Stop listening. Safe when never started. */
+    close(): Promise<void>;
+    private handle;
+    /**
+     * The best-effort same-origin check. Returns the offending origin, or `null`
+     * when the POST is acceptable.
+     *
+     * A request with neither `Origin` nor `Referer` is accepted: `curl`, a test's
+     * `fetch` and some browsers' form posts all send neither, and an attacker can
+     * omit a header as easily as anyone else — refusing them would cost the
+     * documented scripting path and buy nothing. See the module header's CSRF
+     * section, which is flagged for review.
+     */
+    private checkOrigin;
+    private readBody;
+    /** The live pending set: the runtime's queue when one is supplied. */
+    private currentRequests;
+    /**
+     * Render the queue. The `lastRendered()` report is built here, from the same
+     * values the HTML is built from — not from a parallel description of it.
+     */
+    private queuePage;
+    private decide;
+    private decideBatch;
+    /**
+     * The response page for a gesture.
+     *
+     * Not a redirect. A redirect-after-POST would either drop the one-shot notice
+     * or put an execution token in a URL, and a URL is exactly the place a
+     * credential must never be: it lands in history, in referrers, and in every
+     * proxy log between here and nowhere.
+     */
+    private outcomePage;
+    private send;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * `approval adapter <name>` — execute an action through the adapter
+ * contract (SPEC.md §10.4; APRV-69, generalized in APRV-221).
+ *
+ * This is the CLI face of the adapters in {@link ADAPTER_CLIS} (`email` at
+ * v0.1), and it is deliberately the thinnest one in the repository. The name is
+ * a table lookup and the body below it is adapter-agnostic: a second adapter is
+ * an entry in the table and nothing else in this file.
+ *
+ * It resolves paths and identity, reads the
+ * payload bytes at the edge, builds the vault-backed credential provider, calls
+ * {@link executeThroughAdapter} once, and maps the result onto the frozen exit
+ * table. It does not verify a token, hash a payload, append an event, or open a
+ * socket: every one of those belongs to a layer that already owns it, and a verb
+ * that reimplemented any of them would be a second implementation of the rule.
+ *
+ * **Why the payload is a file (or stdin) and never a flag.** The bytes are the
+ * thing the grant or registered declaration bound, they routinely contain newlines, quotes and a
+ * £-sign, and a message body on a command line is a message body in the shell
+ * history and in `ps` output. `approval payload hash <file|->` and
+ * `approval request --payload <file>` take the same argument in the same form,
+ * so the same file travels from declaration to request to execution.
+ *
+ * **What `--json` prints is the contract's own result shape**, unmodified:
+ * `AdapterExecuteSuccess` on stdout for a completed send,
+ * `AdapterRefusal` on stderr for anything else. There is no CLI-flavoured
+ * summary, because a caller parsing this is a caller who wants to know
+ * `started_seq`, `outcome_seq` and `adapter_code` — and inventing a second
+ * vocabulary for them here would be a second thing to keep in step with
+ * `contract.ts`.
+ *
+ * ## Exit codes
+ *
+ * The `approval run` table, unchanged and shared with it through
+ * {@link executeRefusalExitCode}:
+ *
+ * | Situation | Code |
+ * |---|---|
+ * | the message was accepted by the far side | 0 |
+ * | usage: a missing required flag, a bad identity, an unparseable payload | 2 |
+ * | I/O: the payload file or the log could not be read | 4 |
+ * | `token-required` — no token was presented | 5 |
+ * | `log-torn-tail`, or an append that hit a torn tail | 3 |
+ * | anything else the runtime decided: `token-mismatch`, `token-consumed`, `payload-mismatch`, `adapter-class-mismatch`, `adapter-precheck-refused` (a drifted draft), `adapter-failed` (an SMTP refusal), `adapter-act-threw` | 1 |
+ *
+ * A refused SEND is exit 1 and not 5: the command was well-formed and the
+ * answer from the world was no. Exit 5 is the manual-path redirection to obtain
+ * a grant token, which is the distinction `run` already draws and the one an
+ * agent's retry logic keys on.
+ */
+import { type Adapter } from "../adapters/contract.js";
+import type { Streams } from "./main.js";
+/** One adapter, as `approval adapter <name>` needs to see it. */
+export interface AdapterCliEntry {
+    /** The verb's own help: printed for --help, and beside every usage error. */
+    help: string;
+    /**
+     * The adapter instance to execute through, built per invocation because
+     * `--timeout` is per invocation. Nothing else about the adapter is this
+     * verb's business: the contract routes, hashes, spends and appends.
+     */
+    build(options: {
+        timeoutMs?: number;
+    }): Adapter;
+}
+/**
+ * Every adapter this verb can execute, keyed by the `adapter <name>` name.
+ *
+ * The table IS the dispatch (APRV-221): a second adapter is a second entry
+ * here, and no line below this one names an adapter. `cli/setup-adapter.ts`
+ * holds the matching table for the credential side and `adapters/registry.ts`
+ * the roster the credential scrub reads. An adapter that ships is an entry in
+ * all three, which is three small tables rather than one import cycle between
+ * the CLI and the adapters.
+ */
+export declare const ADAPTER_CLIS: Record<string, AdapterCliEntry>;
+/** The known names, sorted, for a usage error and for the help text. */
+export declare function knownAdapterNames(): string[];
+/**
+ * `approval adapter <name> <action-key> [--token <t>] --payload <file|->`.
+ *
+ * One implementation for every entry in {@link ADAPTER_CLIS}: the name and the
+ * entry are arguments, and everything this function does (the flags, the
+ * payload read, the identity check, the vault, the exit table) is the same
+ * whichever adapter is on the other end. What differs between adapters is the
+ * contract's business, and the contract is not here.
+ */
+export declare function commandAdapterExecute(name: string, entry: AdapterCliEntry, argv: string[], streams: Streams, cwd: string): Promise<number>;
+/** `approval adapter <name>` — resolve the name through {@link ADAPTER_CLIS}. */
+export declare function commandAdapter(argv: string[], streams: Streams, cwd: string): Promise<number>;

package/dist/src/cli/adapter.js

@@ -1,5 +1,5 @@
 /**
- * `approval adapter <name>` — execute an approved action through the adapter
+ * `approval adapter <name>` — execute an action through the adapter
  * contract (SPEC.md §10.4; APRV-69, generalized in APRV-221).
  *
  * This is the CLI face of the adapters in {@link ADAPTER_CLIS} (`email` at
@@ -15,7 +15,7 @@
  * that reimplemented any of them would be a second implementation of the rule.
  *
  * **Why the payload is a file (or stdin) and never a flag.** The bytes are the
- * thing the grant approved, they routinely contain newlines, quotes and a
+ * thing the grant or registered declaration bound, they routinely contain newlines, quotes and a
  * £-sign, and a message body on a command line is a message body in the shell
  * history and in `ps` output. `approval payload hash <file|->` and
  * `approval request --payload <file>` take the same argument in the same form,
@@ -37,21 +37,22 @@
  * | Situation | Code |
  * |---|---|
  * | the message was accepted by the far side | 0 |
- * | usage: a missing flag, a bad identity, an unparseable payload | 2 |
+ * | usage: a missing required flag, a bad identity, an unparseable payload | 2 |
  * | I/O: the payload file or the log could not be read | 4 |
  * | `token-required` — no token was presented | 5 |
  * | `log-torn-tail`, or an append that hit a torn tail | 3 |
  * | anything else the runtime decided: `token-mismatch`, `token-consumed`, `payload-mismatch`, `adapter-class-mismatch`, `adapter-precheck-refused` (a drifted draft), `adapter-failed` (an SMTP refusal), `adapter-act-threw` | 1 |
  *
- * A refused SEND is exit 1 and not 5: the command was well-formed, the token was
- * good, and the answer from the world was no. Only the absence of a valid token
- * earns 5, which is the distinction `run` already draws and the one an agent's
- * retry logic keys on.
+ * A refused SEND is exit 1 and not 5: the command was well-formed and the
+ * answer from the world was no. Exit 5 is the manual-path redirection to obtain
+ * a grant token, which is the distinction `run` already draws and the one an
+ * agent's retry logic keys on.
  */
 import { readFileSync } from "node:fs";
 import { isAbsolute, resolve as resolvePathSegments } from "node:path";
 import { agentmailAdapter } from "../adapters/agentmail.js";
 import { emailAdapter } from "../adapters/email.js";
+import { zzzAdapter } from "../adapters/zzz.js";
 import { vaultCredentialProvider } from "../adapters/vault-provider.js";
 import { executeThroughAdapter, } from "../adapters/contract.js";
 import { HUMAN_ACTOR_ENV, resolveHumanActor } from "../core/attest.js";
@@ -61,7 +62,7 @@ import { passphraseEnvFor, vaultPathFor } from "../core/vault.js";
 import { boolFlag, parseFlags, stringFlag } from "./args.js";
 import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
 import { executeRefusalExitCode } from "./execute.js";
-import { ADAPTER_AGENTMAIL_HELP, ADAPTER_EMAIL_HELP, ADAPTER_HELP } from "./help.js";
+import { ADAPTER_AGENTMAIL_HELP, ADAPTER_EMAIL_HELP, ADAPTER_HELP, ADAPTER_ZZZ_HELP } from "./help.js";
 import { DEFAULT_LOG_PATH, resolvePath } from "./paths.js";
 import { refusal as renderRefusal, style } from "./style.js";
 import { usageErrorText } from "./usage.js";
@@ -84,6 +85,10 @@ export const ADAPTER_CLIS = {
         help: ADAPTER_AGENTMAIL_HELP,
         build: (options) => agentmailAdapter(options),
     },
+    zzz: {
+        help: ADAPTER_ZZZ_HELP,
+        build: (options) => zzzAdapter(options),
+    },
 };
 /** The known names, sorted, for a usage error and for the help text. */
 export function knownAdapterNames() {
@@ -93,7 +98,7 @@ export function knownAdapterNames() {
 const PRINCIPAL_ACTOR = /^(human|agent):.+/u;
 /**
  * The flags every adapter verb takes. One set and not one per adapter: what the
- * runtime needs in order to execute an approved action (the token, the bytes,
+ * runtime needs in order to execute an action (the optional token, the bytes,
  * the identity, the log, the vault) is the same question whoever answers it,
  * and a per-adapter flag table would be a per-adapter way to drift from
  * `approval run`. An adapter with a flag of its own adds it here, beside these.
@@ -143,7 +148,7 @@ function refusalExit(result) {
     return result.execute === undefined ? EXIT_INTEGRITY : executeRefusalExitCode(result.execute);
 }
 /**
- * `approval adapter <name> <action-key> --token <t> --payload <file|->`.
+ * `approval adapter <name> <action-key> [--token <t>] --payload <file|->`.
  *
  * One implementation for every entry in {@link ADAPTER_CLIS}: the name and the
  * entry are arguments, and everything this function does (the flags, the
@@ -170,13 +175,14 @@ export async function commandAdapterExecute(name, entry, argv, streams, cwd) {
     if (extra !== undefined) {
         return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`, help);
     }
+    // Optional for the same reason it is optional on `approval run`: the core
+    // admits an explicitly policy-authorized supervised/autonomous execution
+    // without minting a grant. Manual and selected-live paths still reach
+    // `startExecution` and refuse `token-required`; this CLI never invents one.
     const token = stringFlag(flags, "--token");
-    if (token === null) {
-        return usageError(streams, json, "missing --token <t>: an adapter executes only against the single-use token `approval grant` printed", help);
-    }
     const payloadFlag = stringFlag(flags, "--payload");
     if (payloadFlag === null) {
-        return usageError(streams, json, "missing --payload <file|->: the bytes the grant approved. There is no flag that takes the message inline — a body on a command line is a body in the shell history", help);
+        return usageError(streams, json, "missing --payload <file|->: the bytes the grant or registered declaration bound. There is no flag that takes the message inline — a body on a command line is a body in the shell history", help);
     }
     const asFlag = stringFlag(flags, "--as");
     const actor = asFlag === null ? resolveHumanActor() : asFlag;
@@ -233,7 +239,11 @@ export async function commandAdapterExecute(name, entry, argv, streams, cwd) {
         // this and keeps the old behaviour exactly.
         envFilePath: envFilePathFor(logPath),
     });
-    const result = await executeThroughAdapter(entry.build(timeoutMs === null ? {} : { timeoutMs }), { logPath, actionKey, payload, actor }, { token, policy: policyLocation, credentials });
+    const result = await executeThroughAdapter(entry.build(timeoutMs === null ? {} : { timeoutMs }), { logPath, actionKey, payload, actor }, {
+        ...(token === null ? {} : { token }),
+        policy: policyLocation,
+        credentials,
+    });
     if (!result.ok) {
         if (json)
             streams.err(`${JSON.stringify(result)}\n`);

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

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

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

@@ -0,0 +1,59 @@
+/**
+ * `approval policy amend` (APRV-30) — the one verb that owns the whole
+ * amendment ceremony: diff, advise, confirm, attest, commit.
+ *
+ * ## The two incidents this verb exists to prevent
+ *
+ * **seq 2 of this repository's own log — the seven-minute amendment.** A
+ * policy edit was attested and superseded seven minutes later (seq 2 at
+ * 11:56:07Z, seq 3 at 12:03:35Z), because the
+ * edit broke a pinned dogfood assertion and nobody found out until the test
+ * suite ran. The operator attested bytes whose *consequences* had never been
+ * shown to them. `amend` shows the semantic diff and the load advisory BEFORE
+ * asking for the sign-off, so the failure that superseded seq 2 would have been
+ * on screen while the human was deciding — and with `--require-load` it would
+ * have refused to attest at all.
+ *
+ * **The unsigned interregnum — commit `f829e6c` and its attestation.** The
+ * policy-editing commit and the attestation that made the edit operative landed
+ * as two separate commits. In between, the repository carried an inoperative
+ * policy: `checkAttestation` said `hash-mismatch` and every gate operation
+ * refused. `amend` closes that window by making the attestation and the git
+ * commit one ceremony — it prints, or with `--commit` runs, the exact two-file
+ * `git add` + `git commit` that lands the policy edit and its attestation
+ * together, and it validates the `--commit` preconditions BEFORE it attests, so
+ * a refusal can never leave a half-finished amendment behind.
+ *
+ * ## The baseline problem, stated plainly (FLAGGED FOR HUMAN REVIEW)
+ *
+ * A semantic diff needs the previously-attested policy *text*. The log does not
+ * have it. An attestation records only the SHA-256 of the bytes — deliberately,
+ * since the log is meant to be exported and copied and a policy body in it
+ * would be a second source of truth. So the attested bytes are **not
+ * recoverable from the log**, and this verb does not pretend otherwise.
+ *
+ * What it does instead, at v0.1: when the policy file lives in a git
+ * repository, it recovers `HEAD:<path>` and hashes it. **Only if that blob's
+ * hash equals the attested hash** is it used as the diff baseline — the point
+ * being that we can then prove the text we are diffing against is exactly the
+ * text that was signed for. Anything else (not a git repo, no such blob, or a
+ * blob whose hash differs from the attestation) drops to **hash-only mode**: a
+ * loud notice that the semantic diff is unavailable, followed by the load
+ * advisory and the attestation, which still work. No `--baseline` flag is
+ * offered; a baseline the operator supplies by hand is a baseline nobody can
+ * verify, which is exactly the assurance this design refuses to fake.
+ *
+ * The limitation is real and worth a human's judgment: an amendment made
+ * outside git, or one made on top of an unattested working-tree edit, gets no
+ * semantic diff. Flagged rather than smoothed over.
+ *
+ * ## What this file does and does not decide
+ *
+ * As everywhere else in the CLI: the diff is `core/policy-diff.ts`, loading is
+ * `core/policy-load.ts`, matching is `core/policy-match.ts`, hashing and the
+ * append are `core/attest.ts`. This file resolves paths and identity, shells out
+ * to git, decides exit codes, and formats output.
+ */
+import type { Streams } from "./main.js";
+/** `approval policy amend …` — the whole ceremony, in one verb. */
+export declare function commandPolicyAmend(argv: string[], streams: Streams, cwd: string): number;