approval-md 0.3.0 → 0.4.0

package/dist/src/serve/follow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow.js","sourceRoot":"","sources":["../../../src/serve/follow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGtF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC,mDAAmD;AACnD,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAkCrC;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAe,EACf,MAAoB,EACpB,KAAa;IAEb,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,IAAI,QAAQ,GAAG,IAAI,CAAC;IAEpB,MAAM,OAAO,GAAG;QACd,IAAI,EAAE,MAAM,CAAC,GAAG;QAChB,IAAI,EAAE,IAAI;QACV,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;KAC/D,CAAC;IAEF,IAAI,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;YAClE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,IAAI,OAAO,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;gBAC5B,uEAAuE;gBACvE,2CAA2C;gBAC3C,QAAQ,GAAG,KAAK,CAAC;gBACjB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,oBAAoB,CAAC;YAAE,MAAM,KAAK,CAAC;QAC1D,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW;YACzF,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE;YACJ,OAAO;YACP,MAAM,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;YACxE,SAAS,EAAE,QAAQ;SACpB;KACF,CAAC;AACJ,CAAC"}

package/dist/src/serve/hook-thread.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Hook calls off the listener's main thread, holding the store lock only while
+ * they append (APRV-427).
+ *
+ * `serve/hook-worker.ts` holds the reasoning for the thread and the handshake.
+ * This is the listener's half: a small pool of warm worker threads, and the
+ * function that runs one hook call on one of them while taking and releasing
+ * the store's lock on the thread's behalf.
+ *
+ * ## What the lock covers for a hook call
+ *
+ * Every stretch in which the call may append: from its first line to the start
+ * of its poll loop (intake, the abandoned-question sweep, register, request),
+ * and from the end of the loop to its verdict (the spend, a withdrawal). Those
+ * are the stretches another in-process writer must not land inside. The loop
+ * itself only reads the verified log and sleeps, so while the call polls the
+ * lock is free and so is the main thread: other hooks open their own questions,
+ * and the tenant's reads answer.
+ *
+ * ## Why a pool
+ *
+ * A thread per call would work, and would pay two costs per call that a warm
+ * thread pays once: loading the CLI's modules, and proving the verified log
+ * from genesis on its first read (each thread has its own read cache, as each
+ * `approval hook` process does). Idle threads are kept up to
+ * {@link HOOK_THREADS_IDLE}; beyond that a finished thread is terminated.
+ *
+ * ## Bounded, because each thread is a copy of the log (APRV-427 review)
+ *
+ * A thread carries its own parsed log in its read cache: about 26 MB for an
+ * idle thread and another 84 MB once it has proved a 73k-record log. An
+ * uncapped pool let thirty concurrent gated calls, or one harness retrying
+ * faster than its hook timeout, grow the facade until the kernel killed it, and
+ * a kill that lands inside an append leaves the log's lockfile behind with
+ * nothing to recover it. So at most {@link HookThreadLimits.threads} calls run
+ * at once (default {@link DEFAULT_HOOK_THREADS}); up to
+ * {@link HookThreadLimits.queue} more wait for a slot in arrival order (default
+ * {@link DEFAULT_HOOK_QUEUE}); and a call past both is refused at once with
+ * {@link HookSaturatedError}, which the listener answers as a block
+ * (`serve-hook-saturated`). A queued call has opened nothing yet, so the wait
+ * costs the tenant nothing but time.
+ *
+ * Reusing a thread is what the listener did before this file existed: every
+ * hook call ran in the one main thread, one after another, with whatever
+ * module state the previous call left.
+ */
+import type { HookWriter } from "./hook-worker.js";
+/** How many finished hook threads are kept warm for the next call. */
+export declare const HOOK_THREADS_IDLE = 4;
+/** Hook calls that may run at once, and so threads that may exist, by default. */
+export declare const DEFAULT_HOOK_THREADS = 16;
+/** Hook calls that may wait for a thread, by default, before one is refused. */
+export declare const DEFAULT_HOOK_QUEUE = 64;
+/** The two bounds on the pool. */
+export interface HookThreadLimits {
+    /** Calls running at once, and the most threads that ever exist. At least 1. */
+    threads: number;
+    /** Calls waiting for a slot. Zero refuses whatever finds every slot taken. */
+    queue: number;
+}
+/** A call refused because every slot and every place in the queue is taken. */
+export declare class HookSaturatedError extends Error {
+    constructor(limits: HookThreadLimits);
+    /**
+     * The call waited so long for a slot, or for the lock, that the harness's
+     * ceiling leaves no window a human could answer in (APRV-427 review).
+     */
+    static outOfBudget(capMs: number, remainingMs: number): HookSaturatedError;
+}
+/** When a call arrived and the harness ceiling it arrived under, or `null`. */
+export interface HookBudget {
+    arrivedAt: number;
+    capMs: number | null;
+}
+/**
+ * A call that will never be answered, because its client went away or the
+ * listener is closing. Nothing is sent for it.
+ */
+export declare class HookCancelledError extends Error {
+    constructor(reason: string);
+}
+/** The pool's state, for diagnostics and the tests that bound it. */
+export interface HookThreadStats {
+    /** Threads that exist (running or idle), not counting ones being terminated. */
+    threads: number;
+    /** Calls running on a thread. */
+    busy: number;
+    /** Calls waiting for a slot. */
+    queued: number;
+    /** The most threads that ever existed at once. */
+    peakThreads: number;
+    /** Calls whose thread has asked for the store lock and not yet been given it. */
+    awaitingLock: number;
+    /**
+     * Verified reads from genesis made while a thread held the store lock, over
+     * every call this pool has finished. The warm read keeps it at zero.
+     */
+    coldReadsInLock: number;
+}
+/** The store lock, as `mcp/server.ts`'s `serializer()` shapes one. */
+export type StoreLock = <T>(work: () => Promise<T>) => Promise<T>;
+/** What one hook call produced: the stdin form's exit code and both streams. */
+export interface HookOutcome {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface HookThreads {
+    /**
+     * Run `approval hook <argv>` with `body` as its stdin, under `lock`'s
+     * sections. `signal` aborts when the caller has gone away: a queued call
+     * leaves the line, and a running one stops at its next poll tick without
+     * spending or withdrawing (see `HookWaitSeam.cancelled`). Either way the
+     * promise may still settle with the hook's own output, which nobody is owed.
+     */
+    run(argv: string[], cwd: string, logPath: string, body: string, signal?: AbortSignal, budget?: HookBudget): Promise<HookOutcome>;
+    /**
+     * Shut the pool down: cancel every running call and every queued one, then
+     * terminate every thread, busy or idle, from inside the store lock so that
+     * none is killed in a mutation section. A call in flight rejects or settles
+     * with output nobody is owed.
+     */
+    close(): Promise<void>;
+    /** The pool's state now. */
+    stats(): HookThreadStats;
+}
+/**
+ * The pool. `writer` is the identity every thread declares and the policy each
+ * call refreshes the `daemons` allowlist from (APRV-448): required rather than
+ * optional, because a thread's module state is its own, and a pool that could be
+ * built without one would append records the listener's own thread stamps and
+ * these threads do not.
+ */
+export declare function hookThreads(lock: StoreLock, writer: HookWriter, limits?: HookThreadLimits): HookThreads;

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

@@ -0,0 +1,333 @@
+/**
+ * Hook calls off the listener's main thread, holding the store lock only while
+ * they append (APRV-427).
+ *
+ * `serve/hook-worker.ts` holds the reasoning for the thread and the handshake.
+ * This is the listener's half: a small pool of warm worker threads, and the
+ * function that runs one hook call on one of them while taking and releasing
+ * the store's lock on the thread's behalf.
+ *
+ * ## What the lock covers for a hook call
+ *
+ * Every stretch in which the call may append: from its first line to the start
+ * of its poll loop (intake, the abandoned-question sweep, register, request),
+ * and from the end of the loop to its verdict (the spend, a withdrawal). Those
+ * are the stretches another in-process writer must not land inside. The loop
+ * itself only reads the verified log and sleeps, so while the call polls the
+ * lock is free and so is the main thread: other hooks open their own questions,
+ * and the tenant's reads answer.
+ *
+ * ## Why a pool
+ *
+ * A thread per call would work, and would pay two costs per call that a warm
+ * thread pays once: loading the CLI's modules, and proving the verified log
+ * from genesis on its first read (each thread has its own read cache, as each
+ * `approval hook` process does). Idle threads are kept up to
+ * {@link HOOK_THREADS_IDLE}; beyond that a finished thread is terminated.
+ *
+ * ## Bounded, because each thread is a copy of the log (APRV-427 review)
+ *
+ * A thread carries its own parsed log in its read cache: about 26 MB for an
+ * idle thread and another 84 MB once it has proved a 73k-record log. An
+ * uncapped pool let thirty concurrent gated calls, or one harness retrying
+ * faster than its hook timeout, grow the facade until the kernel killed it, and
+ * a kill that lands inside an append leaves the log's lockfile behind with
+ * nothing to recover it. So at most {@link HookThreadLimits.threads} calls run
+ * at once (default {@link DEFAULT_HOOK_THREADS}); up to
+ * {@link HookThreadLimits.queue} more wait for a slot in arrival order (default
+ * {@link DEFAULT_HOOK_QUEUE}); and a call past both is refused at once with
+ * {@link HookSaturatedError}, which the listener answers as a block
+ * (`serve-hook-saturated`). A queued call has opened nothing yet, so the wait
+ * costs the tenant nothing but time.
+ *
+ * Reusing a thread is what the listener did before this file existed: every
+ * hook call ran in the one main thread, one after another, with whatever
+ * module state the previous call left.
+ */
+import { SHARE_ENV, Worker } from "node:worker_threads";
+import { daemonIdentity } from "../core/daemon-identity.js";
+import { HARNESS_CAP_MARGIN_MS, harnessCapFitsMargin } from "../core/harness-wait.js";
+/** How many finished hook threads are kept warm for the next call. */
+export const HOOK_THREADS_IDLE = 4;
+/** Hook calls that may run at once, and so threads that may exist, by default. */
+export const DEFAULT_HOOK_THREADS = 16;
+/** Hook calls that may wait for a thread, by default, before one is refused. */
+export const DEFAULT_HOOK_QUEUE = 64;
+/** A call refused because every slot and every place in the queue is taken. */
+export class HookSaturatedError extends Error {
+    constructor(limits) {
+        super(`every hook slot is busy (${String(limits.threads)} running, ${String(limits.queue)} queued); nothing was registered or requested. Retry the tool call later; the operator raises the bounds with --hook-threads and --hook-queue`);
+        this.name = "HookSaturatedError";
+    }
+    /**
+     * The call waited so long for a slot, or for the lock, that the harness's
+     * ceiling leaves no window a human could answer in (APRV-427 review).
+     */
+    static outOfBudget(capMs, remainingMs) {
+        const error = new HookSaturatedError({ threads: 0, queue: 0 });
+        error.message = `this call waited for a hook slot until only ${String(Math.max(0, remainingMs))}ms of its ${String(capMs)}ms harness ceiling was left, which does not clear the ${String(HARNESS_CAP_MARGIN_MS)}ms margin: a question opened now would still be pending when the harness kills the call. Nothing was registered or requested. Retry the tool call; the operator raises --hook-threads if calls queue this long`;
+        return error;
+    }
+}
+/**
+ * A call that will never be answered, because its client went away or the
+ * listener is closing. Nothing is sent for it.
+ */
+export class HookCancelledError extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = "HookCancelledError";
+    }
+}
+/**
+ * The pool. `writer` is the identity every thread declares and the policy each
+ * call refreshes the `daemons` allowlist from (APRV-448): required rather than
+ * optional, because a thread's module state is its own, and a pool that could be
+ * built without one would append records the listener's own thread stamps and
+ * these threads do not.
+ */
+export function hookThreads(lock, writer, limits = { threads: DEFAULT_HOOK_THREADS, queue: DEFAULT_HOOK_QUEUE }) {
+    const idle = [];
+    const all = new Set();
+    let closed = false;
+    /** Calls holding a slot. Never more than `limits.threads`. */
+    let busy = 0;
+    /** Calls waiting for a slot, oldest first. */
+    const waiting = [];
+    /** The cancel word of every call running on a thread. */
+    const running = new Set();
+    let peakThreads = 0;
+    let coldReadsInLock = 0;
+    let awaitingLock = 0;
+    /**
+     * Take a slot, waiting in line for one if every slot is held, or refuse.
+     *
+     * A thread is only ever spawned by a call holding a slot and finding no idle
+     * thread, so the threads that exist never outnumber the slots.
+     */
+    async function slot(signal) {
+        if (busy < limits.threads) {
+            busy += 1;
+            return;
+        }
+        if (waiting.length >= limits.queue)
+            throw new HookSaturatedError(limits);
+        // The slot is handed over by `freeSlot`, so `busy` is unchanged by it. A
+        // caller that leaves while in line leaves the line: it has opened nothing,
+        // and a slot spent on it would be a slot a caller who is still there waits
+        // for.
+        await new Promise((granted, dropped) => {
+            const entry = {
+                grant: () => {
+                    signal?.removeEventListener("abort", leave);
+                    granted();
+                },
+                drop: (cause) => {
+                    signal?.removeEventListener("abort", leave);
+                    dropped(cause);
+                },
+            };
+            function leave() {
+                const at = waiting.indexOf(entry);
+                if (at !== -1)
+                    waiting.splice(at, 1);
+                entry.drop(new HookCancelledError("the caller went away while its hook call was queued"));
+            }
+            waiting.push(entry);
+            signal?.addEventListener("abort", leave, { once: true });
+        });
+    }
+    function freeSlot() {
+        const next = waiting.shift();
+        if (next !== undefined)
+            next.grant();
+        else
+            busy -= 1;
+    }
+    function retire(worker) {
+        all.delete(worker);
+        void worker.terminate();
+    }
+    function spawn() {
+        const worker = new Worker(new URL("./hook-worker.js", import.meta.url), {
+            // The launch environment, live, rather than a copy taken when the thread
+            // was born: the verb reads the environment the host started this process
+            // with (SPEC.md §11.1 invariant 7), and a warm thread must not answer
+            // from an older one.
+            env: SHARE_ENV,
+            // The identity the listener resolved at startup, declared by the thread
+            // before its first job (APRV-448). Resolved once, on the listener's
+            // thread, so a hook's records and a verb's carry one id.
+            workerData: writer,
+        });
+        // Neither an idle thread nor a busy one keeps the process alive on its own:
+        // the listener does that, and a closed listener leaves nothing behind.
+        worker.unref();
+        all.add(worker);
+        peakThreads = Math.max(peakThreads, all.size);
+        // A thread that dies while idle must not take the process with it through
+        // an unhandled `error`, nor be handed the next call.
+        worker.on("error", () => undefined);
+        worker.once("exit", () => {
+            all.delete(worker);
+            const at = idle.indexOf(worker);
+            if (at !== -1)
+                idle.splice(at, 1);
+        });
+        return worker;
+    }
+    function give(worker) {
+        if (!closed && idle.length < HOOK_THREADS_IDLE)
+            idle.push(worker);
+        else
+            retire(worker);
+    }
+    async function run(argv, cwd, logPath, body, signal, budget = { arrivedAt: Date.now(), capMs: null }) {
+        if (closed)
+            throw new HookCancelledError("the listener is closing");
+        if (signal?.aborted === true)
+            throw new HookCancelledError("the caller went away");
+        await slot(signal);
+        try {
+            // The time in line is spent out of the harness's budget (APRV-427
+            // review). A call that arrived with room and has none left is refused
+            // here, before a thread is spent on it. A ceiling that never had room is
+            // the hook's own refusal to make (`hook-harness-cap-too-short`), and an
+            // autonomous call under it is still answered.
+            const { capMs } = budget;
+            if (capMs !== null && harnessCapFitsMargin(capMs)) {
+                const remainingMs = capMs - Math.max(0, Date.now() - budget.arrivedAt);
+                if (!harnessCapFitsMargin(remainingMs)) {
+                    throw HookSaturatedError.outOfBudget(capMs, remainingMs);
+                }
+            }
+            return await runOnThread(argv, cwd, logPath, body, signal, budget);
+        }
+        finally {
+            freeSlot();
+        }
+    }
+    async function runOnThread(argv, cwd, logPath, body, signal, budget) {
+        if (closed)
+            throw new HookCancelledError("the listener is closing");
+        if (signal?.aborted === true)
+            throw new HookCancelledError("the caller went away");
+        const worker = idle.pop() ?? spawn();
+        const shared = new SharedArrayBuffer(8);
+        const flag = new Int32Array(shared);
+        // The cancel word the hook's poll reads every tick. Set, never cleared: a
+        // call whose caller left is over whatever happens next.
+        const cancel = () => {
+            Atomics.store(flag, 1, 1);
+        };
+        signal?.addEventListener("abort", cancel, { once: true });
+        running.add(flag);
+        return await new Promise((settle, fail) => {
+            /** Ends the section the thread is in, when it is in one. */
+            let release = null;
+            let finished = false;
+            /** Take the store lock on the thread's behalf, then let it proceed. */
+            const enter = () => {
+                awaitingLock += 1;
+                void lock(async () => await new Promise((done) => {
+                    awaitingLock -= 1;
+                    // The thread died while this was queued: nothing to hand over.
+                    if (finished) {
+                        done();
+                        return;
+                    }
+                    release = done;
+                    Atomics.store(flag, 0, 1);
+                    Atomics.notify(flag, 0);
+                }));
+            };
+            const leave = () => {
+                const done = release;
+                release = null;
+                done?.();
+            };
+            const finish = () => {
+                finished = true;
+                leave();
+                running.delete(flag);
+                signal?.removeEventListener("abort", cancel);
+                worker.off("message", onMessage);
+                worker.off("exit", onExit);
+            };
+            function onMessage(message) {
+                switch (message.type) {
+                    case "wait":
+                        leave();
+                        return;
+                    case "resume":
+                        enter();
+                        return;
+                    case "done":
+                        coldReadsInLock += message.coldReadsInLock;
+                        finish();
+                        give(worker);
+                        settle({ code: message.code, stdout: message.stdout, stderr: message.stderr });
+                        return;
+                    case "failed":
+                        finish();
+                        give(worker);
+                        fail(new Error(message.message));
+                        return;
+                    case "saturated":
+                        finish();
+                        give(worker);
+                        fail(HookSaturatedError.outOfBudget(budget.capMs ?? 0, message.remainingMs));
+                        return;
+                    case "cancelled":
+                        finish();
+                        give(worker);
+                        fail(new HookCancelledError("the caller went away before its hook call began"));
+                        return;
+                }
+            }
+            function onExit(code) {
+                finish();
+                fail(new Error(`the hook thread exited (${String(code)}) before it answered`));
+            }
+            worker.on("message", onMessage);
+            worker.once("exit", onExit);
+            // The allowlist the listener holds in force right now (APRV-448 review):
+            // the thread never runs wider than this, even when its own resolution
+            // fails because the policy lost its attestation.
+            const allowed = daemonIdentity()?.allowed ?? null;
+            const job = { argv, cwd, body, logPath, budget, allowed, flag: shared };
+            // The thread warms its read cache first and then asks for its first
+            // section with `resume`, so no cold walk of the log is ever made inside
+            // the lock (see `hook-worker.ts`).
+            worker.postMessage(job);
+        });
+    }
+    return {
+        run,
+        stats: () => ({ threads: all.size, busy, queued: waiting.length, peakThreads, coldReadsInLock, awaitingLock }),
+        close: async () => {
+            closed = true;
+            // Every running call stops at its next poll tick without spending or
+            // withdrawing, exactly as for a client that went away; nobody in line
+            // will be served.
+            for (const flag of running)
+                Atomics.store(flag, 1, 1);
+            for (const entry of waiting.splice(0)) {
+                entry.drop(new HookCancelledError("the listener is closing"));
+            }
+            const resting = idle.splice(0);
+            await Promise.all(resting.map(async (worker) => await worker.terminate()));
+            // A busy thread is terminated only from INSIDE the store lock. Holding it
+            // means no thread is in a mutation section, so none is between taking the
+            // log's append lockfile and releasing it: a thread killed there would
+            // leave the lockfile behind and every later append would time out on it.
+            // A thread in its wait holds neither, and a question it opened stays open
+            // for the retry grace, exactly as for an `approval hook` process that was
+            // killed mid-wait.
+            await lock(async () => {
+                await Promise.all([...all].map(async (worker) => await worker.terminate()));
+            });
+        },
+    };
+}
+//# sourceMappingURL=hook-thread.js.map

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

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

package/dist/src/serve/hook-worker.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 { type DaemonIdResolution } from "../core/daemon-host.js";
+import type { LoadPolicyOptions } from "../core/policy-load.js";
+/**
+ * What every thread in the pool writes as (APRV-448), handed over once as the
+ * thread's `workerData`.
+ *
+ * A worker thread holds its own copy of every module, so the identity the
+ * listener declared on its own thread is not declared here: without this, a
+ * hook call's records would carry no `daemon` field and meet no `daemons`
+ * allowlist while a verb call's beside them did. The listener resolves the id
+ * ONCE, from its launch environment and its log path, and every thread declares
+ * that same resolution; no request carries any part of it.
+ */
+export interface HookWriter {
+    /** The listener's own resolution, declared verbatim. */
+    daemon: DaemonIdResolution;
+    /** Where the store's policy is, for the per-call allowlist refresh. */
+    policy: LoadPolicyOptions;
+}
+/** One hook call, as the listener hands it over. */
+export interface HookJob {
+    argv: string[];
+    cwd: string;
+    body: string;
+    /** The store's log, for the warm read before the lock. */
+    logPath: string;
+    /**
+     * When the call arrived (epoch ms, the listener's clock, which is this
+     * thread's too) and the harness ceiling it arrived under, or `null` where
+     * the harness has none. The remainder is computed ONCE, when the lock
+     * arrives, and the hook is handed that exact number.
+     */
+    budget: {
+        arrivedAt: number;
+        capMs: number | null;
+    };
+    /**
+     * The `daemons` allowlist the listener holds in force when it hands the call
+     * over (APRV-448 review), or `null` for no restriction. The thread starts
+     * each call from the stricter of this and its own, so a thread whose own
+     * resolution fails (a policy edited and not re-attested) never runs wider
+     * than the listener beside it.
+     */
+    allowed: readonly string[] | null;
+    /**
+     * Two `Int32`s. `[0]` is 1 while this thread holds the store lock by proxy,
+     * else 0. `[1]` is set to 1 by the listener when the HTTP client that asked
+     * has gone away (or the listener is closing), and read by the hook's poll as
+     * {@link HookWaitSeam.cancelled}.
+     */
+    flag: SharedArrayBuffer;
+}
+/** What this thread posts back. */
+export type HookWorkerMessage = {
+    type: "wait";
+} | {
+    type: "resume";
+} | {
+    type: "done";
+    code: number;
+    stdout: string;
+    stderr: string;
+    /**
+     * Verified reads from genesis this call made while holding the store
+     * lock. Zero is the property the warm read exists for; the listener
+     * sums it into its diagnostics so a test can assert it without timing.
+     */
+    coldReadsInLock: number;
+} | {
+    type: "failed";
+    message: string;
+}
+/** The caller went away before the hook began: nothing was run or appended. */
+ | {
+    type: "cancelled";
+}
+/**
+ * The call's harness budget ran below the margin while it waited for the
+ * lock, so no question it opened could be held: nothing was run or appended.
+ */
+ | {
+    type: "saturated";
+    remainingMs: number;
+};