approval-md 0.1.0 → 0.2.0

package/dist/src/daemon/prune.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Payload retention pruning — the enforcement half of amended SPEC.md §5.2
+ * (APRV-38's vocabulary, APRV-41's daemon).
+ *
+ * > "A payload is prunable once the action it is bound to has been in a terminal
+ * > state (`executed`, `rejected`, `expired`, `revoked`) for longer than the
+ * > duration. A payload whose action is not terminal is never prunable, at any
+ * > age […]. Orphaned payloads (bytes with no recorded binding) are prunable
+ * > regardless of the key. […] Pruning is performed by the daemon and by nothing
+ * > else, and each removal appends a `payload.pruned` event, so a log states what
+ * > its store no longer holds."
+ *
+ * ## Write-ahead, always in that order
+ *
+ * For every file this module removes, the `payload.pruned` event lands in the
+ * log **first** and the `unlink` follows. The ordering is the whole design: a
+ * crash between the two leaves a file on disk that the log already says is gone,
+ * which the next tick completes by unlinking it and appending nothing further
+ * ({@link PrunePlan.completions}). The opposite order would leave the other
+ * failure — bytes deleted with no record of the deletion — which is the one
+ * outcome a store holding the material evidence of what a human approved cannot
+ * afford. Deleting evidence is acceptable; deleting it silently is not.
+ *
+ * Idempotence needs no remembered state: a hash that already carries a
+ * `payload.pruned` event is never given a second one, and the plan is re-derived
+ * from the verified log on every tick.
+ *
+ * ## Terminal time comes from the log, never from the filesystem
+ *
+ * The clock that decides whether retention has elapsed reads the timestamp of the
+ * event that made the action terminal (`execution.completed`, `approval.rejected`,
+ * `approval.revoked`, `approval.expired`). File mtimes are not evidence: they are
+ * rewritten by a copy, a checkout, a backup restore, or an `rsync`, and pruning on
+ * them would let a routine filesystem operation decide when approval evidence
+ * disappears.
+ *
+ * A **lazily** expired request (the TTL has arithmetically lapsed but no
+ * `approval.expired` record exists) is deliberately not terminal here. The
+ * daemon's own TTL sweep appends that event on the same tick; the payload becomes
+ * prunable once the log says so, and retention is then measured from the recorded
+ * moment rather than from one this module computed for itself.
+ *
+ * `execution.failed` is likewise not terminal: a failed action may be retried
+ * against the very bytes in question, and loop escalation (SPEC.md §10.2) exists
+ * precisely because failures recur.
+ *
+ * ## The orphan rule, resolved conservatively (flagged for review)
+ *
+ * §5.2 says orphaned payloads are "prunable regardless of the key", which reads
+ * as though orphans could be swept even with `payload_retention` absent. APRV-41's
+ * acceptance criteria say the absent key means no pruning at all. This module
+ * takes the strictest reading that satisfies both:
+ *
+ * - **`payload_retention` absent: the pruning subsystem does not run.** Nothing is
+ *   deleted, orphan or not, and no `payload.pruned` is appended. Retention is an
+ *   operator's explicit choice to forget, and an operator who never made it never
+ *   asked this runtime to delete anything.
+ * - **`payload_retention` present: orphans are prunable at any age**, which is
+ *   what "regardless of the key" then means — the duration governs bound payloads
+ *   and does not gate residue nothing ever bound.
+ *
+ * An orphan is a file whose hash appears in **no** log record other than a
+ * `payload.pruned` (head-moved residue: the gate stored the bytes, its append was
+ * refused, and no request ever declared them). A hash mentioned by any other
+ * record is bound, and a binding this module cannot attribute to an action key is
+ * treated as live rather than as an orphan — fail closed in both directions.
+ *
+ * ## Nothing else here decides anything
+ *
+ * Which hashes the log already binds, and which it already says are pruned, is
+ * `core/payload-census.ts`'s — the same computation the reporting surfaces read,
+ * so what a reader is shown and what this module would delete can never drift
+ * apart. Approval state per action is `core/state.ts`'s `requestState`; the append is
+ * `core/log.ts`'s `appendEvent` with `expectedHead` (compare-and-append, SPEC.md
+ * §11.1 invariant 5); the unlink is `core/payload-store.ts`'s. The timestamp on
+ * every `payload.pruned` is the runtime's, read from the injected clock at the
+ * write boundary, and the actor is `system:daemon` — a party under oversight must
+ * never be able to author either.
+ */
+import { type Clock } from "../core/clock.js";
+import { type EventRecord } from "../core/log.js";
+/**
+ * SPEC.md §8 and `event.schema.json`: `payload.pruned` carries a `system:` actor.
+ * Declared here rather than imported from `daemon.ts` so the pruner has no
+ * dependency on the loop that calls it.
+ */
+export declare const PRUNE_ACTOR = "system:daemon";
+/** The terminal states of amended SPEC.md §5.2, and nothing beyond them. */
+export type TerminalState = "executed" | "rejected" | "revoked" | "expired";
+/** Why a payload is prunable. Mirrors `payload.pruned`'s `reason`. */
+export type PruneReason = "payload_retention" | "orphaned";
+/** One file the plan says may go, and the evidence for saying so. */
+export interface PruneCandidate {
+    hash: string;
+    reason: PruneReason;
+    /** The action whose terminal state released the bytes; `null` for an orphan. */
+    actionKey: string | null;
+    task: string | null;
+    terminalState: TerminalState | null;
+    /** The `ts` of the event that made it terminal; retention is measured from it. */
+    terminalTs: string | null;
+}
+/**
+ * What one tick would do.
+ *
+ * `completions` are hashes whose `payload.pruned` is already in the log while the
+ * file is still on disk — a crash between the append and the unlink, or a store
+ * that was restored from a backup taken before the prune. They are unlinked and
+ * **no second event is appended**: the log already states the fact.
+ */
+export interface PrunePlan {
+    candidates: PruneCandidate[];
+    completions: string[];
+}
+/**
+ * What may be pruned right now. Pure: no I/O, no clock, no policy loading.
+ *
+ * `retentionMs` is `null` when the policy declares no `payload_retention` — or
+ * when the policy could not be loaded at all, which fails closed to the same
+ * answer. Either way the plan is empty: the subsystem does not run.
+ *
+ * `nowIso` is the evaluation moment, injected. A pruner that read the clock
+ * itself could not be replayed, and retention arithmetic that cannot be replayed
+ * cannot be audited.
+ */
+export declare function planPrune(records: EventRecord[], presentHashes: string[], nowIso: string, retentionMs: number | null): PrunePlan;
+/** Why a prune pass complained. Reported to the caller; never thrown. */
+export type PruneWarningCode = 
+/** The verified read refused, so nothing was planned this pass. */
+"log-unreadable"
+/** A `payload.pruned` append was refused; the file stays, untouched. */
+ | "append-refused"
+/** The event landed but the file could not be removed. The next tick retries. */
+ | "unlink-failed";
+export interface PruneWarning {
+    code: PruneWarningCode;
+    message: string;
+}
+/**
+ * One prune that completed: the event landed AND the bytes went (APRV-57).
+ *
+ * Reported separately from {@link PruneReport.appended} because only these carry
+ * a `seq` and only these are finished. A candidate whose append landed and whose
+ * unlink FAILED appears in `appended` and in `warnings`, never here: the store
+ * still holds the bytes, and a success line for it would say otherwise.
+ *
+ * Crash-window completions ({@link PrunePlan.completions}) are absent for the
+ * opposite reason: they append nothing, so there is no record for a `seq` to
+ * name, and the log said the file was gone on some earlier tick already.
+ */
+export interface PrunedRecord {
+    candidate: PruneCandidate;
+    /** `seq` of the appended `payload.pruned` record. */
+    seq: number;
+}
+export interface PruneReport {
+    /** `payload_retention` in milliseconds, or `null` when the subsystem is off. */
+    retentionMs: number | null;
+    /** Hashes for which a `payload.pruned` was appended this pass. */
+    appended: PruneCandidate[];
+    /** Appended-and-unlinked prunes, with the seq of each event (APRV-57). */
+    pruned: PrunedRecord[];
+    /** Hashes whose file was removed (appended-then-unlinked, plus completions). */
+    removed: string[];
+    /** Crash-window files finished without a second event. */
+    completed: string[];
+    warnings: PruneWarning[];
+}
+export interface PruneOptions {
+    /** The append-only log. Re-read before every append. */
+    logPath: string;
+    /** The payload store. Defaults to the store beside `logPath`. */
+    storeDir?: string;
+    /** Policy location, with `loadPolicy`'s semantics. */
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    schemaDir?: string;
+    /** The write-boundary clock (amended SPEC.md §8). Tests inject; production does not. */
+    clock?: Clock;
+}
+/**
+ * Read `payload_retention` from the policy in force right now.
+ *
+ * Fails closed to `null` exactly as the daemon's TTL read does: a policy that
+ * cannot be loaded declares no retention, so nothing is pruned on its behalf. An
+ * unparseable duration is likewise `null` — the schema's duration pattern makes
+ * that unreachable through a validated policy, and a retention rule this module
+ * cannot read is not one it may guess at.
+ */
+export declare function retentionMsOf(policy: {
+    dir?: string;
+    file?: string;
+}, schemaDir?: string): number | null;
+/**
+ * One pruning pass: plan, append, unlink, repeat.
+ *
+ * The log is re-read before each append rather than once for the pass, because
+ * each append moves the head the next one is compared against and because a CLI
+ * verb may have appended in between. `expectedHead` therefore always names the
+ * head the decision was made from; a `head-moved` refusal drops the candidate and
+ * the next tick re-derives it.
+ *
+ * Nothing is retried in place, and no state survives the call.
+ */
+export declare function prunePayloads(options: PruneOptions): PruneReport;

package/dist/src/mcp/http.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `approval mcp serve --http` — the §10.5 wrapper over the MCP streamable-HTTP
+ * transport, one session per connection (APRV-174).
+ *
+ * The stdio server of `./server.ts` serves ONE client through the pipe the
+ * operator handed it: one process, one connection, one identity. This module
+ * changes exactly one thing about that picture, the transport, and it changes it
+ * so that several clients can be served at once. Everything else is the same
+ * code: the tool list is still {@link createApprovalMcpServer}'s, a tool call
+ * still builds an argv and calls the function the CLI dispatches to, and a
+ * refusal is still the CLI's refusal.
+ *
+ * ## One `Server` + one transport per session
+ *
+ * The SDK's `StreamableHTTPServerTransport` is stateful per session: it mints an
+ * `mcp-session-id` at `initialize`, stamps it on every response, and expects the
+ * client to send it back. This module owns one `node:http` listener and a map
+ * from that id to the `{ Server, transport, actor }` triple it belongs to. An
+ * initialize POST with no session header opens a triple; every later request is
+ * routed by the header; the triple is dropped when its transport closes (a
+ * DELETE, or the socket going away).
+ *
+ * ## Identity is minted BEFORE the transport exists, per session
+ *
+ * `cli/mcp.ts` settles identity before it constructs the stdio transport,
+ * because "a server that connected first and refused later would be a server a
+ * client had already spoken to". That property is preserved verbatim here, once
+ * per session: {@link mintSessionActor} runs before the `Server`/transport pair
+ * is built, and its result is the `actor` that pair closes over for its whole
+ * life.
+ *
+ * **Nothing a client sends reaches that actor.** There is no code path from a
+ * header, a URL, an `initialize` payload's `clientInfo`, or a tool argument into
+ * the identity a session runs as. `clientInfo.name` is a label a client chose
+ * for itself, and SPEC.md §11 says a self-reported field never reduces scrutiny;
+ * an identity a caller could name would be an identity a caller could escalate,
+ * so the server names it:
+ *
+ * - plain `--http`: every session runs as the operator's own `--as` /
+ *   `APPROVAL_AGENT` actor, which is the stdio behavior with more connections;
+ * - `--guest`: every session mints its own `agent:guest-<6 hex>`, so the log,
+ *   the budgets and the refusals see one stranger per connection rather than one
+ *   crowd. That is the whole reason this scheme exists — an actor a limit can be
+ *   keyed on.
+ *
+ * ## Loopback, caps, and no authentication whatsoever
+ *
+ * This listener authenticates nobody, exactly like `channels/web.ts`. It binds
+ * `127.0.0.1` unless the operator writes another host out in full, and the CLI
+ * prints a loud banner when they do; the deployment this was built for
+ * (SPEC.md §10.5, the crowd demo) is a tunnel in front of a loopback bind, where
+ * the tunnel is the thing that faces the network.
+ *
+ * Two caps bound what a stranger can spend: {@link MAX_CONCURRENT_SESSIONS} live
+ * at once and {@link MAX_LIFETIME_SESSIONS} over the process's life. Over either
+ * one, an initialize is refused with a plain HTTP 503 naming the reason, before
+ * a session exists.
+ */
+import { type ServerPaths } from "./server.js";
+/** Live sessions this listener will hold at once. */
+export declare const MAX_CONCURRENT_SESSIONS = 20;
+/** Sessions this listener will open over the life of the process. */
+export declare const MAX_LIFETIME_SESSIONS = 200;
+/** Largest request body accepted, in bytes. A tool call is small. */
+export declare const MAX_BODY_BYTES: number;
+/** The prefix every guest session's actor carries. */
+export declare const GUEST_ACTOR_PREFIX = "agent:guest-";
+/**
+ * Mint one session's actor.
+ *
+ * `used` is the set of actors this listener has already handed out, for the life
+ * of the process rather than of the live map: two sessions that shared an actor
+ * would share a budget and a refusal history, which is the one thing this scheme
+ * exists to keep apart. Six hex digits is short enough to read out loud in a
+ * demo, so the collision check is not decoration.
+ */
+export declare function mintSessionActor(used: ReadonlySet<string>): string;
+export interface HttpServeOptions extends ServerPaths {
+    /**
+     * The actor every session runs as, or `null` under {@link guest}, where each
+     * session mints its own. Already validated by `resolveAgentActor`.
+     */
+    actor: string | null;
+    /**
+     * Guest mode: per-session identity (APRV-174), plus the narrowed tool list,
+     * the `mcp-guest-restricted` call-time refusal and the `wait` clamp that
+     * `./server.ts` applies (APRV-175).
+     */
+    guest: boolean;
+    /** Interface to bind. Defaults to `127.0.0.1`; the CLI owns the widening decision. */
+    host?: string;
+    /** TCP port. `0` asks the kernel for an ephemeral one, which is what tests use. */
+    port: number;
+    /** Session lifecycle lines. The CLI passes stderr; stdout is never written to. */
+    notice?: (text: string) => void;
+}
+export interface McpHttpServer {
+    /** The interface actually bound. */
+    readonly host: string;
+    /** The port actually bound, resolved after an ephemeral request. */
+    readonly port: number;
+    /** Actors of the live sessions, in open order. Diagnostics and tests. */
+    sessionActors(): string[];
+    /** How many sessions this listener has opened, ever. */
+    lifetimeSessions(): number;
+    /** Close every session and the listener. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Start the HTTP MCP listener. Resolves once it is bound and its real port is
+ * known; rejects when the bind fails, so the CLI can report it and exit.
+ */
+export declare function serveApprovalMcpHttp(options: HttpServeOptions): Promise<McpHttpServer>;

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The MCP wrapper of SPEC.md §10.5 — the same verbs as tools, over the CLI's
+ * own code paths (APRV-87).
+ *
+ * §10.5 asks for "a thin MCP server exposing the same verbs as tools … for
+ * clients where MCP is more ergonomic than shelling out", and says plainly that
+ * "it shares the CLI's code paths". Both halves of that sentence are load-
+ * bearing here, and the second one is the whole design: **there is no second
+ * implementation of any verb in this file.** A tool call builds an argv, hands
+ * it to the function `src/cli/main.ts` dispatches to, captures the `--json`
+ * object the CLI would have printed, and returns it. A refusal is the refusal
+ * the CLI prints, with the same machine-readable `error.code`.
+ *
+ * ## The scoping decision: agent-facing only
+ *
+ * SPEC.md §11 names the agent the **untrusted policy** and the human the
+ * **trusted, expensive overseer**. An MCP client is an agent's harness. Offering
+ * `grant` to it hands the untrusted policy the overseer's pen, and no amount of
+ * care inside the tool implementation would undo that. So the tool list is
+ * exactly {@link VERB_REGISTRY} filtered by `human_only === false`, minus the
+ * transport exclusions in {@link EXCLUDED_VERBS}, and the registry's `human_only`
+ * marker — not a list kept here — is what decides. `verb-registry.ts` says it in
+ * its own header: the marker "exists so a wrapper does not offer an agent a door
+ * the runtime will only slam".
+ *
+ * The runtime would slam it anyway (the CLI layer refuses, core refuses again,
+ * and the event schema refuses a third time). Publishing the door would still be
+ * wrong: a tool list is a statement about what this surface is for.
+ *
+ * ## Identity is the server's, and a tool call cannot change it
+ *
+ * The server runs AS one agent identity, fixed when the operator starts it
+ * (`--as agent:<id>`, or `APPROVAL_AGENT`). `human:` and `system:` are refused at
+ * startup. Every tool whose verb accepts `--as` gets the server's identity
+ * appended LAST, after anything the caller supplied, and `--as` is removed from
+ * every published input schema so that a client sending it is refused by the
+ * schema rather than quietly ignored. Two mechanisms for one rule, because the
+ * rule is the reason this server is safe to run at all.
+ *
+ * ## Guest mode narrows, and never widens (APRV-175)
+ *
+ * A server built with `guest: true` publishes {@link GUEST_VERBS} INTERSECTED
+ * with the list above, refuses anything else at call time with
+ * `mcp-guest-restricted` even when a client crafted the name itself, clamps
+ * `wait` to {@link GUEST_WAIT_TIMEOUT_MS}, and says all of that in
+ * {@link GUEST_INSTRUCTIONS}. Two properties are worth stating plainly: the
+ * intersection means guest mode can only ever take tools away, so no name the
+ * full server withholds becomes reachable by turning it on; and the refusal
+ * lives at CALL time, so `tools/list` describes the boundary rather than being
+ * it. The human-only arm is unchanged and is checked first, because "no session
+ * on any transport may do this" outranks "this session may not".
+ *
+ * ## What this server does NOT do
+ *
+ * - It reads no `.approval/env` (SPEC.md §11.1 invariant 7). The environment a
+ *   gate operation runs under is the one the operator launched this process
+ *   with, exactly as for any other `approval` invocation.
+ * - It maps nothing onto the MCP tasks/elicitation extension. §10.5 says the
+ *   tasks extension MAY be mapped onto `awaiting` "when client support
+ *   stabilizes"; that is post-v1, and until then `wait` blocks and answers.
+ * - It appends nothing of its own. `tools/list` touches no file.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { type CallToolResult, type Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type JsonSchema, type VerbSpec } from "../cli/verb-registry.js";
+/**
+ * Agent-facing verbs that are still not tools, each for a reason that is about
+ * the TRANSPORT or the verb's role rather than about authority. Anything
+ * excluded for authority reasons is `human_only` in the registry instead, which
+ * is where that judgment belongs.
+ */
+export declare const EXCLUDED_VERBS: ReadonlyMap<string, string>;
+/**
+ * The verbs a GUEST session may call (APRV-175), as registry labels.
+ *
+ * A POSITIVE allowlist, and the direction is the whole point. Guest mode exists
+ * so strangers can drive a gate over the network without executing anything on
+ * the host, and the two verbs that make that dangerous are not the only ones:
+ * `run` spawns argv on the server machine, an `adapter <name>` spends vault
+ * credentials, `token` hands out spend material, `journal write` writes a local
+ * file the operator reads. A deny list would have to name each of those and
+ * every one that lands next; this list names what a guest MAY do, so a verb
+ * added tomorrow is absent until someone decides otherwise. Fail closed, per
+ * SPEC.md §11.
+ *
+ * The list is the demo's shape: read the guide (`instructions`), declare and
+ * ask (`register`, `request`), watch (`wait`, `status`, `queue`), and inspect
+ * (`log verify`, `policy check`, `policy test`). Nothing here executes a side
+ * effect, and nothing here is a human's authority — those are `human_only` in
+ * the registry and were never published on any transport.
+ *
+ * This narrows and never widens: {@link publishedVerbs} intersects it with the
+ * ordinary filter, so a name the full server does not publish cannot become a
+ * tool by turning guest mode on.
+ */
+export declare const GUEST_VERBS: ReadonlySet<string>;
+/** Guest `wait` never blocks the shared queue for longer than this. */
+export declare const GUEST_WAIT_TIMEOUT_MS = 5000;
+/** `<name>_<subcommand words>` — `log_verify`, `channel_telegram_health`. */
+export declare function toolName(spec: VerbSpec): string;
+/**
+ * The verbs this server publishes, in registry order.
+ *
+ * Under `guest`, the ordinary filter is INTERSECTED with {@link GUEST_VERBS}:
+ * guest mode subtracts and can never add.
+ */
+export declare function publishedVerbs(guest?: boolean): VerbSpec[];
+/**
+ * The input schema for one tool: the registry's input schema, with the single
+ * documented deletion of `--as`.
+ *
+ * Nothing else is translated, reshaped or regenerated. The registry's schemas
+ * are already `{type:"object", properties:{positionals, flags, trailing?}}` with
+ * `additionalProperties:false` throughout, which is exactly what MCP wants a
+ * tool `inputSchema` to be, so the SDK's low-level {@link Server} is used rather
+ * than `McpServer`: `McpServer.registerTool` takes Zod, and translating JSON
+ * Schema into Zod so the SDK can translate it back would put a lossy round trip
+ * between the one source and the published contract.
+ *
+ * `additionalProperties:false` is also what refuses `{"as":"human:carter"}`:
+ * there is no such property, at any level, on any published tool.
+ */
+export declare function toolInputSchema(spec: VerbSpec): JsonSchema;
+/** The `tools/list` answer, derived entirely from the registry. */
+export declare function toolDefinitions(guest?: boolean): Tool[];
+/** The environment variable an operator may use instead of `--as`. */
+export declare const AGENT_ACTOR_ENV = "APPROVAL_AGENT";
+export type IdentityCheck = {
+    ok: true;
+    actor: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Resolve and validate the identity this server acts as.
+ *
+ * A `human:` value is refused rather than accepted-and-downgraded: an operator
+ * who typed one meant something, and the something they meant is not available
+ * here. `system:` is refused for the same reason `expire` takes no identity —
+ * the runtime's own actor is not a thing a caller supplies.
+ */
+export declare function resolveAgentActor(flag: string | null, env?: NodeJS.ProcessEnv): IdentityCheck;
+/** Pinned paths the operator chose when launching the server. */
+export interface ServerPaths {
+    /** Working directory every relative path resolves against. */
+    cwd: string;
+    /** `--log`, when the operator pinned one. */
+    log?: string;
+    /** `--policy`, when the operator pinned one. */
+    policy?: string;
+}
+export interface ServerOptions extends ServerPaths {
+    /** `agent:<id>`; already validated by {@link resolveAgentActor}. */
+    actor: string;
+    /**
+     * The invoke queue this server runs its tool calls through (APRV-174).
+     *
+     * Omitted on stdio, where one process serves one client and
+     * {@link createApprovalMcpServer} builds its own. The HTTP transport passes
+     * ONE queue shared by every session, because the reason the queue exists
+     * (`wait` blocks the event loop with `Atomics.wait`, `run` uses `spawnSync`)
+     * is a property of the process, not of the connection.
+     */
+    serialize?: <T>(work: () => Promise<T>) => Promise<T>;
+    /**
+     * Guest mode (APRV-175): the tool list narrows to {@link GUEST_VERBS}, a call
+     * to anything else is refused `mcp-guest-restricted` at CALL time, and `wait`
+     * is clamped to {@link GUEST_WAIT_TIMEOUT_MS}.
+     */
+    guest?: boolean;
+}
+/**
+ * The `--timeout` a guest's `wait` actually runs with (APRV-175).
+ *
+ * A clamp rather than an override: a caller asking for less than the ceiling
+ * gets what they asked for, and anything larger, unparseable or absent becomes
+ * {@link GUEST_WAIT_TIMEOUT_MS}. It is appended LAST, the same mechanism that
+ * pins `--as`, so the caller's own value loses without being rejected.
+ *
+ * The ceiling is not politeness. `wait` blocks the event loop (`Atomics.wait`)
+ * and every HTTP session shares one invoke queue, so an unbounded `wait` is one
+ * stranger stalling every other session and the listener with them.
+ */
+export declare function guestWaitTimeout(rawFlags: unknown): string;
+export type ArgvBuild = {
+    ok: true;
+    argv: string[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Map one tool call's arguments onto the argv the CLI would have been given.
+ *
+ * Validation here is deliberate rather than delegated: the low-level MCP
+ * {@link Server} does not validate `arguments` against a tool's `inputSchema`,
+ * and "the schema said additionalProperties:false" has to be enforced by
+ * something. So an unknown top-level key, an unknown flag, or a non-string
+ * argument is refused, which is what makes `{"as":"human:carter"}` a refusal
+ * instead of a silently dropped field.
+ */
+export declare function buildArgv(spec: VerbSpec, rawArgs: unknown, options: ServerOptions): ArgvBuild;
+/** What one verb invocation produced. */
+interface Invocation {
+    code: number;
+    stdout: string;
+    stderr: string;
+    child?: {
+        stdout: string;
+        stderr: string;
+    };
+}
+/** The `_meta` key prefix this server stamps its out-of-band facts under. */
+export declare const META_PREFIX = "approval.md/";
+/**
+ * Shape one invocation into a tool result.
+ *
+ * A gate refusal is a RESULT, never a thrown JSON-RPC error: the command was
+ * well-formed and the runtime's answer was no, which is a fact the caller must
+ * be able to read as data. It comes back as `isError: true` carrying the same
+ * `{"error":{"code","message"}}` object the CLI prints, so a client branches on
+ * `error.code` exactly as it would on the CLI's stderr.
+ *
+ * A non-zero exit that carries a SUCCESS-shaped object is not an error: `wait`
+ * exits 1 on a rejection and 6 on a timeout, `status` exits 1 when something
+ * needs attention, `log verify` exits 3 on a torn tail. Those are answers. The
+ * exit code always travels in `_meta` so nothing is lost either way.
+ */
+export declare function toolResult(result: Invocation): CallToolResult;
+/**
+ * Serialize everything.
+ *
+ * Two reasons, and only the first is about this process. In-process, several
+ * verbs are synchronous and blocking (`wait` sleeps with `Atomics.wait`, `run`
+ * uses `spawnSync`), so overlapping them buys nothing and interleaves their
+ * captured output. Across processes, an append still goes through
+ * `core/log.ts`'s lockfile and compare-and-append, so a CLI running beside this
+ * server is safe whatever this queue does — the queue is politeness, the
+ * lockfile is the guarantee.
+ *
+ * APRV-174: over HTTP one process serves many sessions, and the first reason
+ * above is about the process. `ServerOptions.serialize` therefore lets the HTTP
+ * listener hand every session the SAME queue; stdio passes nothing and gets a
+ * fresh one, exactly as before.
+ */
+export declare function serializer(): <T>(work: () => Promise<T>) => Promise<T>;
+/**
+ * What a GUEST session is told at connect time (APRV-175).
+ *
+ * Distinct from the full text because the situation is distinct, and the two
+ * facts a guest most needs are the two a full client never needs: `wait` comes
+ * back fast, and a granted request executes NOWHERE. Saying the second one
+ * plainly matters more than it looks. A stranger who saw their action granted
+ * and assumed an email went out has learned the wrong thing about this system;
+ * what they are driving is the approval flow itself.
+ */
+export declare const GUEST_INSTRUCTIONS = "approval.md gates agent actions that touch the world, and you are connected to it as a GUEST. The tools here are a narrow slice of the agent surface: read the guide (`instructions`), declare an action in a task envelope and register it (`register`), ask for it (`request`), then watch (`wait`, `status`, `queue`) and inspect (`log_verify`, `policy_check`, `policy_test`). Calling anything else is refused `mcp-guest-restricted` whether or not it is listed, because everything else executes on, or spends the credentials of, the machine hosting this gate. Two things to expect. `wait` returns FAST: a guest's timeout is clamped to five seconds server-side, so treat it as a poll and call `status` again rather than asking for a longer one. And NOTHING YOU ARE GRANTED EXECUTES ANYWHERE: there is no `run` here, no adapter, and no side effect at the end of the flow. What you are driving is the approval flow itself \u2014 a real request, a real human decision, a real hash-chained record of both. Your identity is this session's alone (`agent:guest-<id>`, chosen by the server), and everything you do is recorded under it.";
+/** Build the MCP server. Nothing is connected until {@link Server.connect}. */
+export declare function createApprovalMcpServer(options: ServerOptions): Server;
+/** Build the server and connect it to `transport`. Resolves once connected. */
+export declare function serveApprovalMcp(options: ServerOptions, transport: Transport): Promise<Server>;
+export {};

package/dist/src/mcp/server.js

@@ -18,7 +18,7 @@
  * `grant` to it hands the untrusted policy the overseer's pen, and no amount of
  * care inside the tool implementation would undo that. So the tool list is
  * exactly {@link VERB_REGISTRY} filtered by `human_only === false`, minus the
- * two exclusions in {@link EXCLUDED_VERBS}, and the registry's `human_only`
+ * transport exclusions in {@link EXCLUDED_VERBS}, and the registry's `human_only`
  * marker — not a list kept here — is what decides. `verb-registry.ts` says it in
  * its own header: the marker "exists so a wrapper does not offer an agent a door
  * the runtime will only slam".
@@ -85,6 +85,10 @@ export const EXCLUDED_VERBS = new Map([
         "consume",
         "internal plumbing: its own purpose says so. `run` wraps it and is published instead, so a client that reached for `consume` would be spending a token outside the verb that records the outcome.",
     ],
+    [
+        "log follow",
+        "it is an unbounded foreground stream. MCP tool calls share a finite request queue and return one finite result, so publishing this verb would occupy that queue indefinitely; MCP clients can poll log verify or use the CLI stream as a separate process.",
+    ],
     [
         "hook claude-code",
         "it reads one PreToolUse event from STDIN and its registry input schema has nowhere to put that event. On a stdio server, stdin is the JSON-RPC stream: a tool that read it would eat the protocol. It is also the wrong shape for MCP — a harness that can call tools calls `request` and `wait` directly.",
@@ -93,6 +97,10 @@ export const EXCLUDED_VERBS = new Map([
         "hook cursor",
         "it reads one Cursor preToolUse event from STDIN and its registry input schema has nowhere to put that event. On a stdio server, stdin is the JSON-RPC stream: a tool that read it would eat the protocol. It is also the wrong shape for MCP — a harness that can call tools calls `request` and `wait` directly.",
     ],
+    [
+        "hook codex",
+        "it reads one Codex PreToolUse or PostToolUse event from STDIN and its registry input schema has nowhere to put that event. On a stdio server, stdin is the JSON-RPC stream: a tool that read it would eat the protocol. It is also the wrong shape for MCP — a harness that can call tools calls `request` and `wait` directly.",
+    ],
 ]);
 /**
  * The verbs a GUEST session may call (APRV-175), as registry labels.