approval-md 0.3.0 → 0.4.0

package/dist/src/serve/hook-worker.js

@@ -0,0 +1,173 @@
+/**
+ * The thread a `POST /hook/<harness>` call runs on (APRV-427).
+ *
+ * A harness hook is synchronous from its first line to its verdict, and its
+ * wait sleeps with `Atomics.wait`. Run on the listener's main thread, one hook
+ * waiting on a human froze the event loop for the whole of that wait: no socket
+ * was read, so the tenant's `GET /status` and `POST /verb/queue` sat unanswered
+ * until the question was decided, and N gated calls from one sandbox queued
+ * behind each other. Scoping a lock cannot fix a thread that does not run, so
+ * the call runs here instead and the main thread stays free.
+ *
+ * This file runs the hook and nothing else. The verdict is `commandHook`'s, with
+ * the request body as the stdin it would have read, exactly as before; what is
+ * added is the {@link HookWaitSeam}, which is how this thread hands the store
+ * lock back to the listener while the hook polls and asks for it again before
+ * the hook appends.
+ *
+ * ## The handshake
+ *
+ * The lock lives on the main thread (`serve/server.ts`), because every other
+ * writer in the process takes it there. This thread holds it BY PROXY: the
+ * main thread acquires it on this thread's behalf and flips a shared flag.
+ *
+ * - A job arrives with the flag at 0. This thread first reads the verified log
+ *   ONCE, outside the lock, to warm its own read cache (below), then posts
+ *   `resume` and blocks on the flag before it runs a line of the hook, so
+ *   intake, the sweep, register and request all happen under the lock.
+ * - `enterWait` clears the flag FIRST and then posts `wait`: the main thread
+ *   releases the lock, and a later `leaveWait` cannot be satisfied by the grant
+ *   that has just ended.
+ * - `leaveWait` posts `resume` and blocks on the flag until the main thread has
+ *   re-acquired the lock and set it to 1.
+ * - `done` carries the exit code and both streams, and ends the last section.
+ *
+ * A blocked `Atomics.wait` here costs this thread and nothing else, which is
+ * the point of the thread.
+ *
+ * ## The warm read, outside the lock (APRV-427 review)
+ *
+ * A new thread's cache is empty, and its first verified read walks the whole
+ * chain: 633 ms on a mature tenant log. Taken inside the lock, five threads
+ * arriving together serialised five cold walks and held the tenant's `status`
+ * behind all of them. So the cold walk happens here, before the lock is asked
+ * for, and in parallel with every other thread's. The hook's own reads under
+ * the lock are then warm: a hash over the prefix this thread already proved,
+ * plus a walk of whatever was appended since. Nothing is decided from the warm
+ * read itself, and nothing is appended on the strength of it; every append
+ * inside the lock is still compare-and-append against a head read inside the
+ * lock (SPEC.md §11.1 invariant 5).
+ */
+import { parentPort, workerData } from "node:worker_threads";
+import { commandHook } from "../cli/hook.js";
+import { declareResolvedDaemonIdentity, narrowerAllowlist, refreshDaemonAllowlistFrom, } from "../core/daemon-host.js";
+import { daemonIdentity, setDaemonAllowlist } from "../core/daemon-identity.js";
+import { harnessCapFitsMargin } from "../core/harness-wait.js";
+import { processReadCache, readVerifiedRecords, useVerifiedSnapshots } from "../core/state.js";
+const port = parentPort;
+if (port === null) {
+    throw new Error("serve/hook-worker.ts runs as a worker thread and was loaded on the main thread");
+}
+// This thread is an `approval hook` process in every way that matters to a
+// read, so it makes the same opt-in the hook makes on its gated path (APRV-188):
+// a read may resume behind the daemon's published snapshot, admitted only
+// against a hash this thread computes itself. Set once, before the warm read,
+// so the warm read and the hook's own reads are one cache under one proof.
+useVerifiedSnapshots(true);
+// APRV-448. This thread appends on the gate's behalf exactly as the listener's
+// own thread does, so it declares the same identity before it runs a line of
+// any hook. Declared once: the resolution is the listener's, fixed at startup.
+const writer = workerData;
+declareResolvedDaemonIdentity(writer.daemon);
+port.on("message", (job) => {
+    const flag = new Int32Array(job.flag);
+    const post = (message) => port.postMessage(message);
+    // Cold reads (cache misses) made inside a locked section, counted section
+    // by section: `mark` is taken when the lock arrives and settled when it goes.
+    let coldReadsInLock = 0;
+    let mark = 0;
+    const settle = () => {
+        coldReadsInLock += processReadCache.stats.misses - mark;
+    };
+    /** Block until the main thread has taken the store lock for this thread. */
+    const held = () => {
+        while (Atomics.load(flag, 0) !== 1)
+            Atomics.wait(flag, 0, 0);
+        mark = processReadCache.stats.misses;
+    };
+    const seam = {
+        enterWait: () => {
+            settle();
+            Atomics.store(flag, 0, 0);
+            post({ type: "wait" });
+        },
+        leaveWait: () => {
+            post({ type: "resume" });
+            held();
+            // Every append after a wait (the execution after a grant, an expiry) is
+            // judged against the list in force NOW, not the one read before a wait
+            // that may have lasted minutes (APRV-448 review).
+            refreshDaemonAllowlistFrom(job.logPath, writer.policy);
+        },
+        cancelled: () => Atomics.load(flag, 1) === 1,
+    };
+    const gone = () => Atomics.load(flag, 1) === 1;
+    const out = [];
+    const err = [];
+    try {
+        // Outside the lock, and its answer is thrown away: its only effect is the
+        // proved prefix this thread's cache now holds. A read that fails here is
+        // the hook's to meet and report, inside the lock, in its own words.
+        //
+        // A caller that went away before the hook began is owed nothing and has
+        // asked nothing yet (APRV-427 review), so the call ends without running a
+        // line of the hook: looked at before the warm read, after it, and once
+        // more when the lock arrives, because the wait for the lock is where a
+        // queue of busy sections makes a client give up. Past this point the
+        // hook's own poll is what notices.
+        if (gone()) {
+            post({ type: "cancelled" });
+            return;
+        }
+        readVerifiedRecords(job.logPath);
+        if (gone()) {
+            post({ type: "cancelled" });
+            return;
+        }
+        post({ type: "resume" });
+        held();
+        if (gone()) {
+            settle();
+            post({ type: "cancelled" });
+            return;
+        }
+        // The `daemons` allowlist in force for this call (APRV-448), resolved from
+        // the attested policy and this thread's verified read, inside the lock and
+        // before the hook appends anything: the listener's thread does the same
+        // before every verb call. A resolution that fails leaves the previous one
+        // standing, as the daemon's tick does; and the standing one is never wider
+        // than the listener's, so a thread spawned after the policy lost its
+        // attestation does not start unrestricted (APRV-448 review).
+        setDaemonAllowlist(narrowerAllowlist(daemonIdentity()?.allowed ?? null, job.allowed));
+        refreshDaemonAllowlistFrom(job.logPath, writer.policy);
+        // The budget, looked at once more now the lock is here (APRV-427 review):
+        // a call that had room when it arrived and spent it waiting in line or for
+        // the lock would open a question the harness kills its asker before
+        // anyone can answer. Refused as saturation instead, appending nothing.
+        //
+        // Measured ONCE, and the same number is what the hook judges by, waits by
+        // and records: a remainder re-measured inside the hook a few milliseconds
+        // later could fall under the margin after this check had admitted it, and
+        // turn an admitted call into `hook-harness-cap-too-short`.
+        const { arrivedAt, capMs } = job.budget;
+        if (capMs !== null) {
+            const remainingMs = Math.max(0, capMs - Math.max(0, Date.now() - arrivedAt));
+            if (harnessCapFitsMargin(capMs) && !harnessCapFitsMargin(remainingMs)) {
+                settle();
+                post({ type: "saturated", remainingMs });
+                return;
+            }
+            seam.remainingCapMs = remainingMs;
+        }
+        const code = commandHook(job.argv, { out: (text) => out.push(text), err: (text) => err.push(text) }, job.cwd, () => job.body, seam);
+        settle();
+        post({ type: "done", code, stdout: out.join(""), stderr: err.join(""), coldReadsInLock });
+    }
+    catch (cause) {
+        // `commandHook` already turns a throw inside the harness path into an
+        // ordinary deny, so reaching this is a failure of the thread itself. It is
+        // reported as one, and the listener answers it as a refusal: never an allow.
+        post({ type: "failed", message: cause instanceof Error ? cause.message : String(cause) });
+    }
+});
+//# sourceMappingURL=hook-worker.js.map

package/dist/src/serve/hook-worker.js.map

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

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

@@ -0,0 +1,412 @@
+/**
+ * `approval serve` — the agent-facing surface over HTTP, for a harness that
+ * has no local log and no local policy (APRV-421).
+ *
+ * A tenant whose harness runs in a sandbox (Agent Village's Hermes tenants,
+ * the Meta Muse connector packet) has nowhere for `approval hook <harness>` to
+ * write and nothing for it to read. The hosted daemon runs elsewhere, one
+ * process per tenant (design/hosted-daemon-identity.md); what was missing was a
+ * way to reach it. This is that door, and it is a DOOR rather than a second
+ * gate.
+ *
+ * ## Transport only, and the file says so by importing rather than repeating
+ *
+ * Every verdict, every verb and every batch of records here comes from the
+ * function the CLI dispatches to:
+ *
+ * - the verb surface is `mcp/server.ts`'s — {@link publishedVerbs},
+ *   {@link toolDefinitions}, {@link buildArgv} and {@link invokeVerb}, so the
+ *   catalog MATCHES `approval mcp serve` because it IS `approval mcp serve`'s,
+ *   `--as` is absent from every published schema for the same one reason, and
+ *   the launch identity is appended last by the same one line;
+ * - a hook call is `commandHook` with the request body as its stdin, so the
+ *   bytes on the response are the bytes the stdin form prints, for every
+ *   adapter in `HARNESS_ADAPTERS`, with no dialect knowledge in this file;
+ * - a follow page is `core/log-subscribe.ts`'s verified subscription, drained
+ *   once (`serve/follow.ts`).
+ *
+ * Nothing here classifies a command, resolves a policy, mints a token or
+ * verifies a chain. Two implementations of the gate sequence would be two
+ * gates, and the second would be the one nobody reviewed.
+ *
+ * ## Two credentials, two parties
+ *
+ * `serve/credentials.ts` holds the reasoning. The short form: the agent
+ * credential opens the verbs and the hook, the tenant credential opens the
+ * log, the export and status, and the agent credential never reads the log it
+ * is judged by.
+ *
+ * ## Which daemon wrote it (APRV-448)
+ *
+ * Every record this process appends carries the `daemon` field, with the id
+ * `approval status` reports for the same store: `APPROVAL_DAEMON_ID` from the
+ * launch environment, or the id derived from the store's instance, resolved
+ * ONCE at startup by `core/daemon-host.ts`'s `resolveDaemonId`, the function
+ * the daemon loop resolves its own id with. The listener's thread declares it
+ * before it binds, and every hook thread declares the same resolution before
+ * its first job (`serve/hook-worker.ts`), so a verb's records and a hook's
+ * carry one id. No request names any part of it.
+ *
+ * The attested policy's `daemons` allowlist is enforced at the write boundary
+ * exactly as it is for the daemon: refreshed from the verified log inside the
+ * store lock before every verb call and every hook call, and an id the list
+ * does not admit is refused `daemon-not-allowed` with nothing written. This
+ * process does NOT mark itself the daemon (`core/daemon-actor.ts`): that mark
+ * routes an advance under the daemon's own autonomous class, and a process that
+ * dispatches the verbs an agent asks for must never hold it.
+ *
+ * ## What it does not do
+ *
+ * - **No TLS.** There is no certificate handling in this process and there is
+ *   not going to be: the supported deployment is a loopback bind behind a
+ *   proxy the operator owns, and a non-loopback bind requires an explicit flag
+ *   and prints a banner (`cli/serve.ts`).
+ * - **No record of its own.** This server appends nothing on its own account.
+ *   Every event in the log under it was written by a verb a caller asked for,
+ *   under the identity the operator fixed at launch.
+ * - **No state a restart loses.** The only things held between requests are
+ *   the store lock and a few warm hook threads, which are properties of the
+ *   process rather than of any caller. Follow cursors belong to the caller, so
+ *   a host that sleeps and wakes serves the same next page it would have served
+ *   before.
+ *
+ * ## What is serialised, and what is not (APRV-427)
+ *
+ * One lock per store ({@link storeLock}). It covers every stretch of work in
+ * this process that may append to the store or must read it as one snapshot:
+ * a verb call, a follow page, the export, and a hook call's MUTATION sections
+ * (everything up to its poll loop, and everything after it). It does not cover
+ * a hook call's WAIT: the call runs on a worker thread (`serve/hook-thread.ts`)
+ * and hands the lock back for as long as it polls, so one question waiting on
+ * a human no longer holds the tenant's `status`, `queue` and follow, or the
+ * next hook call's own question, until the human answers. The catalog takes no
+ * lock at all. Across processes the guarantee is unchanged and is not this
+ * lock's: every append goes through `core/log.ts`'s lockfile and
+ * compare-and-append.
+ * - **No `.approval/env`.** SPEC.md §11.1 invariant 7, inherited verbatim from
+ *   the MCP server: the environment a gate operation runs under is the one the
+ *   host launched this process with.
+ */
+import { type HookThreadStats, type StoreLock } from "./hook-thread.js";
+/**
+ * Identity is resolved by the MCP server's own function, re-exported here so
+ * that `cli/serve.ts` reaches it through ITS server exactly as `cli/mcp.ts`
+ * reaches it through the MCP one.
+ *
+ * Two transports fixing an identity by two rules would be two answers to
+ * "which identities may this process act as", and the answer has to be one:
+ * `agent:<id>` and nothing else, refused at startup, never supplied by a
+ * caller.
+ */
+export { resolveAgentActor, type IdentityCheck } from "../mcp/server.js";
+import { type ServeCredentials, type ServeScope } from "./credentials.js";
+/** Largest request body accepted. A tool call and a hook envelope are small. */
+export declare const MAX_BODY_BYTES: number;
+/**
+ * How much of an oversized body this server will read and throw away before
+ * dropping the socket.
+ *
+ * An oversized request is refused at {@link MAX_BODY_BYTES}, but the refusal
+ * cannot be WRITTEN until the client stops writing, or the response closes the
+ * socket under it and the caller sees a transport error instead of a verdict.
+ * So the remainder is discarded as it arrives, up to this much, and beyond it
+ * the connection is simply dropped: a caller streaming without end is not a
+ * caller owed a polite answer.
+ */
+export declare const DRAIN_LIMIT_BYTES: number;
+/**
+ * How much of a captured stream travels back in a response body.
+ *
+ * Both streams are bounded, and both carry a flag saying whether they were
+ * clipped. Generous enough that a verdict is never clipped in practice, and
+ * present so that a verb which decided to print a megabyte cannot make a
+ * response unsendable. Clipping happens at a CODEPOINT boundary
+ * ({@link clip}), so what comes back is always valid text.
+ */
+export declare const MAX_STREAM_BYTES: number;
+/**
+ * The exit code every server-authored refusal carries.
+ *
+ * NON-ZERO, always, and this is the finding that made the whole response
+ * contract change. A refusal used to travel as an HTTP status with the exit
+ * code in a header that refusals did not set, so a client following the
+ * documented rule — write stdout, exit `x-approval-exit-code` — read a missing
+ * header as zero, and zero is ALLOW on Claude Code, Cursor, Codex and Muse. A
+ * 413 on an oversized hook envelope was therefore an allow. Nothing on this
+ * surface may be able to turn a refusal into a permission, so the exit code is
+ * in the body, it is always present, and on a refusal it is always this.
+ */
+export declare const REFUSAL_EXIT_CODE = 2;
+/**
+ * The verbs the AGENT credential may call. An ALLOWLIST, and the direction is
+ * the whole of it.
+ *
+ * The catalog is the registry's and does not change (`mcp/server.ts` owns it,
+ * and this surface publishes exactly what `approval mcp serve` publishes).
+ * This is authorization, which is a different question asked one layer later,
+ * and it is asked per verb.
+ *
+ * ## Why a list of what a harness MAY do
+ *
+ * The threat model this transport exists for is a sandboxed harness on another
+ * machine, not an operator at their own laptop. `approval mcp serve` is run BY
+ * the operator, on the operator's box, over a pipe the operator handed it; its
+ * whole catalog is reachable there because the party at the other end is the
+ * party who started it. Here the party at the other end is the party under
+ * oversight, and the operative rule is that it never reads the log it is
+ * judged by, nor spends the host's credentials, nor runs argv on the host.
+ *
+ * A denylist would have to name `log tail`, `log export`, `queue`, `coverage`,
+ * `doctor`, every `adapter <name>`, `run`, `sandbox`, `token`, `reindex`,
+ * `render` and every verb that lands next. This list names what a harness
+ * under oversight needs in order to ASK and to ACT ON a grant, so a verb added
+ * to the registry tomorrow is TENANT-scoped until somebody decides otherwise.
+ * Fail closed, per SPEC.md §11, which is the same reasoning `GUEST_VERBS`
+ * gives for being positive.
+ *
+ * What is on it, and why each:
+ *
+ * - `instructions`, `hook_classify` — read the guide, and find out what the
+ *   classifier makes of a command. Neither reads the log or the policy file;
+ *   both tell an agent what it is about to be judged for before it asks.
+ * - `request`, `wait`, `withdraw` — ask, wait for the answer, and retract your
+ *   own question. This is the gate sequence, and it is the reason the agent
+ *   credential exists.
+ * - `propose`, `start` (APRV-445) — the same sequence for an action the agent
+ *   declares itself, with its payload as a flag value: register-and-request in
+ *   a class the operator declared by name and opened with `agent_may_request`,
+ *   and record the execution the grant or the policy authorized. Neither takes
+ *   a path, and `start` is requester-only.
+ * That is the whole list. It is seven verbs, and the shortness is the point: a
+ * harness under oversight asks and is answered, and everything else about the
+ * gate belongs to the party the gate is for.
+ *
+ * ## What came OFF this list in review, and why
+ *
+ * - `register` takes a task-file POSITIONAL, which is a host path. The hook
+ *   endpoint is a harness's way to register: it synthesises the envelope from
+ *   the tool call, so nothing is lost and a host path stops being something a
+ *   remote caller names.
+ * - `log_verify` and `gate_status` hand back the log's length, its head hash
+ *   and the live state of the gate. "Not a record" is not the same as "not
+ *   about the log": a head hash moving is a decision being recorded, and an
+ *   open window is the human's current posture toward this very agent.
+ * - `policy_check` and `policy_test` answer what the policy does with a class,
+ *   and `policy_check` names the absolute store path while doing it.
+ * - **Both payload builders**, under the rule that a builder is the agent's
+ *   only if it builds from the request's own arguments and never reaches a
+ *   host resource. `payload_hash` takes a FILE, and on this transport that
+ *   file is on the daemon's machine while the caller is not: every path it
+ *   could name is one the host put there, so answering would be a hash oracle
+ *   that also files the bytes into the payload store.
+ *   `payload_agentmail-draft` takes two ids rather than a path, but it reads
+ *   the draft over HTTPS with `AGENTMAIL_API_KEY` FROM THIS SERVER'S OWN
+ *   ENVIRONMENT, so a remote caller would be spending the host's credential on
+ *   ids it chose — the same fault wearing a network instead of a filesystem.
+ *   The narrow reading was taken on purpose: publishing a builder that should
+ *   have been withheld is a capability leak, and withholding one that should
+ *   have been published is a line of configuration.
+ *
+ * Everything else is the tenant's, including the ones easiest to wave through:
+ * `log_tail` and `log_export` return RECORDS, `queue` returns the tenant's
+ * pending decisions, `run` and `sandbox` spawn argv on the daemon's machine,
+ * every `adapter_<name>` spends vault credentials, and `status` is the
+ * tenant's view of the oversight the agent is under. All of them stay
+ * PUBLISHED, so the surface is honest about what exists, and all of them
+ * answer the tenant credential only.
+ */
+export declare const AGENT_VERBS: ReadonlySet<string>;
+/**
+ * The frozen refusal vocabulary this server authors itself (SPEC.md §11.1
+ * invariant 6).
+ *
+ * A refusal a VERB produced keeps the verb's own code, unchanged, because it
+ * is the CLI's refusal arriving over a different transport; so does a refusal
+ * `buildArgv` produced, `mcp-` prefix and all, because that function is the
+ * one both transports call and renaming its codes here would make one surface
+ * lie about the other. What is listed below is only what this file decides.
+ */
+export declare const SERVE_REFUSAL_CODES: readonly ["serve-unauthorized", "serve-agent-forbidden", "serve-tenant-forbidden", "serve-unknown-path", "serve-malformed-url", "serve-unknown-verb", "serve-unknown-harness", "serve-method-not-allowed", "serve-body-too-large", "serve-body-unreadable", "serve-invalid-cursor", "serve-path-pinned", "serve-path-outside-store", "serve-positional-flag", "serve-flag-not-permitted", "serve-export-symlink", "serve-export-hardlink", "serve-export-failed", "serve-hook-failed", "serve-hook-saturated"];
+export type ServeRefusalCode = (typeof SERVE_REFUSAL_CODES)[number];
+export interface ServeOptions {
+    /** `agent:<id>`, already validated. Every verb call is recorded under it. */
+    actor: string;
+    /** The store root: the 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;
+    /** The two bearer credentials, already resolved from the environment. */
+    credentials: ServeCredentials;
+    /**
+     * The launch environment the daemon id is resolved from (APRV-448):
+     * `APPROVAL_DAEMON_ID` when it holds one, otherwise the id derived from the
+     * store's instance. Defaults to `process.env`. Nothing else in this server
+     * reads it; the verbs read the environment the process was launched with, as
+     * before. An unusable declared id makes {@link serveApproval} reject before
+     * it binds, which the CLI has already refused in its own words.
+     */
+    env?: NodeJS.ProcessEnv;
+    /** Interface to bind. The CLI owns the widening decision; this defaults to loopback. */
+    host?: string;
+    /** TCP port. `0` asks the kernel for an ephemeral one, which is what tests use. */
+    port: number;
+    /**
+     * A unix-domain socket to listen on INSTEAD of `host`/`port` (APRV-445). An
+     * absolute path whose directory the serving uid owns; see
+     * {@link checkUnixSocketTarget} and {@link UNIX_SOCKET_MODE}.
+     */
+    socketPath?: string;
+    /** `--timeout` pinned on every hook call, when the operator chose one. */
+    hookTimeout?: string;
+    /**
+     * `--harness-cap` pinned on every hook call, when the operator stated one
+     * (APRV-423).
+     *
+     * Independent of {@link ServeOptions.hookTimeout} and composed with it: that
+     * one bounds how long a call WAITS, this one states the ceiling the harness
+     * on the far side of the call imposes on its own hook process. The request
+     * this server opens is then judged by the shorter of the policy's TTL and
+     * that ceiling minus a margin, so the expiry is recorded while the tenant's
+     * harness is still listening.
+     */
+    hookHarnessCap?: string;
+    /**
+     * Hook calls that may run at once, each on its own thread (APRV-427 review).
+     * Defaults to {@link DEFAULT_HOOK_THREADS}. See `serve/hook-thread.ts`.
+     */
+    hookThreads?: number;
+    /**
+     * Hook calls that may wait for a thread before one is refused
+     * `serve-hook-saturated`. Defaults to {@link DEFAULT_HOOK_QUEUE}.
+     */
+    hookQueue?: number;
+    /** Request lines. The CLI passes stderr; stdout is never written to. */
+    notice?: (text: string) => void;
+}
+export interface ServeHandle {
+    readonly host: string;
+    readonly port: number;
+    /** The unix socket this listener is bound to, or `null` for a TCP bind. */
+    readonly socketPath: string | null;
+    /** The id every record this process appends carries (APRV-448). */
+    readonly daemonId: string;
+    /** How many requests this listener has answered. Diagnostics and tests. */
+    requests(): number;
+    /** The hook thread pool's state now. Diagnostics and tests. */
+    hookThreads(): HookThreadStats;
+    close(): Promise<void>;
+}
+/**
+ * One captured stream, bounded and clipped at a CODEPOINT boundary.
+ *
+ * A naive byte slice can cut a multi-byte sequence in half and produce a
+ * string that is not valid text, which for a JSON body means either a
+ * replacement character where a verdict had a word or, worse, a body a strict
+ * client refuses to parse. `StringDecoder` emits only the complete codepoints
+ * in what it was given and keeps the incomplete tail to itself, which is
+ * exactly the clip wanted here.
+ */
+export declare function clip(text: string): {
+    text: string;
+    truncated: boolean;
+};
+export interface CatalogEntry {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: unknown;
+    /** Which credential opens this verb. Annotation only; the check is below. */
+    scope: ServeScope;
+}
+/**
+ * The published surface: `approval mcp serve`'s tool list, with each entry's
+ * scope stated.
+ *
+ * Derived, not restated. A verb added to the registry tomorrow appears here
+ * the same day it appears as an MCP tool, with `--as` already deleted from its
+ * schema by the same function, and `grant` is absent for the same reason it is
+ * absent there — the registry marks it `human_only` and no transport publishes
+ * a human's authority. Its SCOPE is tenant until somebody puts it on
+ * {@link AGENT_VERBS}, which is the fail-closed half of the same derivation.
+ */
+export declare function serveCatalog(): CatalogEntry[];
+/**
+ * The flags every hook call is made with.
+ *
+ * Exported so a test can hand the SAME argv to `commandHook` directly and
+ * compare the bytes. That comparison is the acceptance criterion, and it is
+ * only honest if both sides are the same invocation of the same verb: a test
+ * that built its own flag list would be comparing two spellings.
+ *
+ * `--as` is appended LAST, as everywhere else on this surface, so the identity
+ * the operator fixed when they started the process wins over anything that
+ * arrived by another route (`parseFlags` keeps the last occurrence).
+ */
+export declare function hookArgv(options: Pick<ServeOptions, "actor" | "cwd" | "log" | "policy" | "hookTimeout" | "hookHarnessCap">): string[];
+type Route = {
+    kind: "catalog";
+} | {
+    kind: "verb";
+    name: string;
+} | {
+    kind: "hook";
+    harness: string;
+} | {
+    kind: "follow";
+} | {
+    kind: "export";
+} | {
+    kind: "status";
+};
+/** The route a path names, or null. Method is checked by the handler. */
+export declare function routeOf(pathname: string): Route | null;
+/**
+ * Which credential opens a route.
+ *
+ * `null` means either one does, which is true of the catalog alone: it is the
+ * published contract, it reads no log and it appends nothing, and both parties
+ * have a reason to ask what this server is.
+ */
+export declare function scopeOf(route: Route): ServeScope | null;
+/**
+ * Start the 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 serveApproval(options: ServeOptions): Promise<ServeHandle>;
+/**
+ * The mode a unix socket is given once bound: everyone the DIRECTORY admits.
+ *
+ * A hosted tenant runs the agent's sandbox as a different uid from this server,
+ * on the same machine, and the socket is how the two meet without a TCP port
+ * anybody on the host could dial. Who may connect is therefore decided by the
+ * directory the socket sits in, which the operator owns and sets (`0710` with
+ * the sandbox's group, an ACL, a bind mount), and the socket itself does not
+ * second-guess it.
+ */
+export declare const UNIX_SOCKET_MODE = 438;
+/**
+ * Refuse a socket path this process should not bind (APRV-445).
+ *
+ * Absolute, inside an existing directory OWNED BY THE SERVING UID (the directory
+ * is the access control, so a directory somebody else owns is somebody else's
+ * access control), and not an existing file of any kind other than a socket: a
+ * stale socket is replaced, and anything else at that path is a file this
+ * server would destroy by binding over it. Synchronous and side-effect free, so
+ * the CLI can refuse before any listener exists.
+ */
+export declare function checkUnixSocketTarget(socketPath: string): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The lock for the store whose log is `logPath` (resolved against `root`).
+ *
+ * Exported so a test can hold the SAME lock the listener takes and watch what
+ * waits on it: that is how the suite shows a hook call's appends are inside
+ * the lock and its wait is outside it, rather than inferring it from timing.
+ */
+export declare function storeLock(logPath: string, root: string): StoreLock;