approval-md 0.4.0 → 0.4.1

package/dist/src/cli/hook.js

@@ -85,6 +85,8 @@ import { harnessProvenance, isHarnessKind, } from "../core/harness-version.js";
 import { abandonedAfterMs, HARNESS_CAP_MARGIN_MS, harnessCapFitsMargin, harnessCappedTtlMs, HOOK_DEFAULT_WAIT, HOOK_RETRY_GRACE_MS, } from "../core/harness-wait.js";
 import { harnessLoopFloor, isLoopEscalated, isSideEffectingClass, loopClearance, UNKNOWN_SESSION, } from "../core/loop.js";
 import { drawSocketPathFor, drawSocketUsable } from "../core/live-draw.js";
+import { appendLockHeld, DEFAULT_LOCK_RETRY_MS, DEFAULT_LOCK_TIMEOUT_MS, } from "../core/log.js";
+import { settleTerminationGuards } from "../core/log-lock.js";
 import { payloadHash } from "../core/payload.js";
 import { classifyApplyPatch, parseApplyPatch } from "../core/apply-patch.js";
 import { loadPolicy, parseDuration } from "../core/policy-load.js";
@@ -988,6 +990,86 @@ export function harnessBlockDirective(code, detail, harness) {
     const exitCode = deny({ out: (text) => out.push(text), err: () => undefined }, code, detail, harness);
     return { stdout: out.join(""), exitCode };
 }
+/**
+ * Raised on `globalThis` while the runtime's own Hermes signal guards are
+ * registered (APRV-466). The `approval` bin reads the same registry symbol and
+ * steps aside while it is `true`, so the bin and the runtime never both print.
+ * An explicit flag rather than a listener count: an unrelated listener that
+ * does not exit must not switch the bin's guard off.
+ */
+export const HERMES_SIGNAL_OWNER = Symbol.for("approval-md.hermes-signal-owner");
+/**
+ * The block directive a Hermes hook prints when a signal arrives before it
+ * reached a verdict (APRV-445, APRV-466), as bytes.
+ *
+ * Two places print it: `hermesFailClosed`'s guard below, and the `approval` bin
+ * (`cli.js`), which has to answer a signal that lands while this module is
+ * still loading and so cannot import it. The bin spells the same bytes by hand,
+ * and `tests/hermes-bin-signal-guard.test.ts` pins the two equal, so the
+ * early-signal answer is one code with one spelling (SPEC.md §11.1 invariant
+ * 6). The wait's own handler words its message differently ("while waiting for
+ * a decision") under the same code.
+ *
+ * On the CLI the runtime's guard prints it for a signal held through the
+ * synchronous stretch before the first spend (the stdin read, the
+ * classification), at the pause `BEFORE_SPEND` (APRV-473); the bin prints it
+ * for a signal during the load (docs/hermes-hook.md, "Two layers against a
+ * signal").
+ */
+export function hermesInterruptedDirective(signal) {
+    return harnessBlockDirective("hook-interrupted", `the hook received ${signal} before it reached a verdict; nothing authorizes this call`, "hermes").stdout;
+}
+/**
+ * The block directive a harness wait answers when a SIGTERM or SIGINT ends it
+ * (APRV-473 for Hermes, APRV-475 for every harness), as bytes and exit code.
+ *
+ * It is the harness's ORDINARY deny, built by {@link harnessBlockDirective}
+ * and so by {@link deny}, under the `hook-interrupted` code: the nested
+ * `hookSpecificOutput` deny at exit 0 for Claude Code, Codex and Muse,
+ * `{permission:"deny"}` at exit 0 for Cursor, `{decision:"deny"}` at exit 2
+ * for Grok, `{action:"block"}` at exit 2 for Hermes. One construction site per
+ * harness, so the answer to an interruption is spelled exactly as every other
+ * refusal that harness receives from this hook, and a harness that blocks on
+ * those blocks on this. `tests/harness-wait-interrupt.test.ts` pins the bytes
+ * per harness.
+ */
+export function interruptedWaitDirective(signal, harness) {
+    return harnessBlockDirective("hook-interrupted", `the hook received ${signal} while waiting for a decision; nothing authorizes this call`, harness);
+}
+/**
+ * The exit code an interrupted wait leaves with when stdout would not take its
+ * directive whole (APRV-475): a closed pipe, or a short write.
+ *
+ * 2, because with an empty or torn stdout the exit code is the whole verdict,
+ * and 2 is the one code these harnesses read as a block on its own: Claude Code
+ * documents it as a blocking error, Grok as its deny, Hermes blocks on it
+ * unconditionally, Muse's live probe blocked on it with an empty stdout, and a
+ * Cursor entry with `failClosed` blocks on any non-zero exit. Exiting 0 there
+ * would be the one wrong answer on the harnesses whose deny is exit 0 with a
+ * body: an exit 0 with no body is no verdict, and those harnesses run the call.
+ */
+const INTERRUPTED_BARE_EXIT = 2;
+/**
+ * Answer an interrupted wait (APRV-475), and return the code to exit with.
+ *
+ * Writes {@link interruptedWaitDirective} synchronously to fd 1, because the
+ * `process.exit` that follows does not wait for a stream to drain. Returns the
+ * directive's own exit code, or {@link INTERRUPTED_BARE_EXIT} when the write
+ * threw or came up short. Called by the wait's signal handler only, BEFORE its
+ * withdrawal, so the block is on stdout however long the withdrawal waits for
+ * the log's lock.
+ */
+function writeInterruptedWait(signal, harness) {
+    const directive = interruptedWaitDirective(signal, harness);
+    let whole = false;
+    try {
+        whole = writeSync(1, directive.stdout) === Buffer.byteLength(directive.stdout);
+    }
+    catch {
+        // stdout is gone; the exit code is the whole verdict.
+    }
+    return whole ? directive.exitCode : INTERRUPTED_BARE_EXIT;
+}
 /** The machine-readable code a Hermes `execute_code` call is refused with. */
 export const HERMES_EXECUTE_CODE_REFUSAL = "hook-hermes-execute-code-unbound";
 /** The tool that carries a program and no path, no argv and no directory. */
@@ -2111,10 +2193,221 @@ function commandClassify(argv, streams, cwd) {
     return EXIT_OK;
 }
 function sleepSync(ms) {
+    // A synchronous wait never runs with termination signals held by the log
+    // lock's guard (APRV-479 round 2, RS2: `approval codex bridge` waits for a
+    // human here through `driveSync`).
+    settleTerminationGuards();
     if (ms <= 0)
         return;
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+/** The longest delay `setTimeout` honours (2^31 - 1 ms). */
+const MAX_TIMER_MS = 2_147_483_647;
+/** Run `steps` to its verdict, sleeping each pause synchronously. */
+function driveSync(steps) {
+    for (;;) {
+        const next = steps.next(false);
+        if (next.done === true)
+            return next.value;
+        if (next.value > 0)
+            sleepSync(next.value);
+    }
+}
+/**
+ * Run `steps` to its verdict, sleeping each pause on the event loop.
+ *
+ * A zero pause is TWO `setImmediate` hops, and the second is what guarantees a
+ * poll phase in between. libuv hands a signal to its JS listeners only when the
+ * poll phase reads the signal pipe. A single immediate scheduled from a
+ * poll-phase callback runs in the same iteration's check phase, before any
+ * further poll, so a signal that arrived during the synchronous stretch would
+ * still be sitting in the pipe when the spend ran. That is the case whenever
+ * the run is still inside the continuation of the bin's `import()` of `dist/`
+ * on a Node whose module load turns the loop (24, and likely 22; APRV-473
+ * refuter, reproduced on 24). A second immediate scheduled from the check phase
+ * runs in the NEXT iteration's check phase, after that iteration's poll, from
+ * whichever phase the first was scheduled.
+ */
+async function driveYielding(steps) {
+    for (;;) {
+        const next = steps.next(true);
+        if (next.done === true)
+            return next.value;
+        // Clamped to the largest delay a timer holds: past it Node fires the timer
+        // at once, and a pause would become a busy poll. The wait re-reads its
+        // deadline after every pause, so a shorter pause changes nothing it judges.
+        const ms = Math.min(next.value, MAX_TIMER_MS);
+        await new Promise((settle) => {
+            if (ms <= 0)
+                setImmediate(() => setImmediate(settle));
+            else
+                setTimeout(settle, ms);
+        });
+    }
+}
+/**
+ * The pause before anything appends `execution.started` or `gate.bypassed`
+ * (APRV-473): a poll phase of the event loop under {@link driveYielding},
+ * nothing under {@link driveSync}.
+ *
+ * Everything between two pauses runs synchronously, so a signal that lands
+ * during the stdin read, the classification, or the poll read that found the
+ * grant is held until the next pause. Without this one, the next point it
+ * could be dispatched is after the spend, and a hook interrupted before its
+ * verdict would record the execution of a call its harness had already given
+ * up on. With it, the listener in force runs first: the wait's handler
+ * withdraws the question and blocks, the early guard (`hermesFailClosed`)
+ * blocks, and either one exits the process before the spend is reached.
+ *
+ * Shared by every harness (APRV-475): it is a yield inside the one gate chain,
+ * so there is no per-harness copy to drift. A signal is HELD only while some
+ * JS listener for it is registered. Outside the wait, the harnesses other than
+ * Hermes register none, so there a signal takes its default disposition the
+ * moment it arrives (the process dies with nothing printed and nothing spent),
+ * and this pause matters for them at the post-wait spend, where the wait's
+ * handler is registered.
+ *
+ * Taken inside {@link spendUnderLock} since APRV-478, immediately before the
+ * spend's one attempt and after any wait for the log's lock, so nothing that can
+ * wait sits between the last pause and the append.
+ */
+const BEFORE_SPEND = 0;
+/**
+ * Did this attempt lose a race for the log's lock, writing nothing?
+ *
+ * Two shapes: the spend's own append refused `append-failed` with the writer's
+ * `lock-timeout`, and a budget refusal whose `budget.exceeded` evidence lost the
+ * race (`startHarnessExecution` carries the writer's error on that refusal for
+ * this, APRV-478). In both nothing was appended, so re-running the whole
+ * attempt is safe and gives the record the chance a synchronous lock wait gave
+ * it.
+ */
+function lockTimedOut(result) {
+    return (!result.ok &&
+        (result.code === "append-failed" || result.code === "budget-exceeded") &&
+        result.append?.code === "lock-timeout");
+}
+/**
+ * Run one spend (an append that authorizes a harness call) without ever waiting
+ * for the log's lock synchronously (APRV-478).
+ *
+ * ## The hole
+ *
+ * Every writer waits for `<log>.lock` inside `core/log.ts`, retrying with an
+ * `Atomics.wait` sleep for up to {@link DEFAULT_LOCK_TIMEOUT_MS}. On the gate
+ * path that wait came AFTER the last pause ({@link BEFORE_SPEND}), so a signal
+ * that arrived while another writer (the daemon, routinely) held the lock was
+ * held by the wait's listener through the whole stretch, the spend appended
+ * `execution.started` and the allow went out, and the wait's `finally` then
+ * removed the listener and the held signal was discarded with it: a start
+ * recorded after the harness had abandoned the call, on every harness.
+ *
+ * ## What this does instead
+ *
+ * The wait for the lock becomes yields of the same generator chain, under ONE
+ * deadline for the whole spend (the writer's own `lockTimeoutMs`, default
+ * {@link DEFAULT_LOCK_TIMEOUT_MS}, taken once when the spend begins):
+ *
+ * 1. While the lockfile is present ({@link appendLockHeld}, advisory) and the
+ *    deadline has not passed, yield the retry interval (`lockRetryMs`, default
+ *    {@link DEFAULT_LOCK_RETRY_MS}).
+ * 2. {@link BEFORE_SPEND}: the zero pause, taken when the spend begins and again
+ *    after any wait, so it always comes immediately before the attempt (with at
+ *    most the probe in between). This
+ *    is the pause the guarantee rests on: two `setImmediate` hops cross a poll
+ *    phase from any phase, so a signal that arrived during the wait or the
+ *    probe is dispatched here at the latest (a retry timer usually dispatches
+ *    it sooner, but a timer scheduled outside a timer callback can fire before
+ *    the next poll). The listener in force then blocks, withdraws what it can
+ *    and exits, and nothing below runs.
+ * 3. One attempt with `lockTimeoutMs: 0`: the whole spend (a fresh verified read,
+ *    every check, compare-and-append against the head that read saw), whose
+ *    append tries the lock exactly ONCE and never sleeps. The lock protocol is
+ *    `core/log.ts`'s, untouched: atomic create-or-fail, never stolen, the head
+ *    compared under it, so this changes when a writer tries and never what a
+ *    try may do.
+ *
+ * An attempt that lost the race (another writer took the lock between the probe
+ * and the try, a window as long as the attempt's own read) yields the retry
+ * interval and goes back to 1, until the deadline: the same number of tries
+ * inside the same bound as `acquireLock`'s synchronous retry, each one a whole
+ * fresh attempt. An attempt that loses at or after the deadline is final,
+ * exactly as a writer's own `lock-timeout` is: the caller denies, and nothing
+ * was appended (fail closed, §11.1 invariant 8). See {@link lockTimedOut} for
+ * the two refusals that count as a lost race.
+ *
+ * What is left between the last pause and the append is the spend's own read
+ * of the log (milliseconds on a small log, longer on a large one) and its
+ * single try at the lock, never a wait on another process. A signal there is
+ * answered by the verdict the spend reaches.
+ *
+ * **The trade, on the yielding path only.** The writer's synchronous wait read
+ * the log first and then spun on the lock itself, so it caught a gap of a
+ * millisecond. Here the spend's read sits between the probe that saw the lock
+ * free and the try, so a lock that is only ever free for gaps shorter than that
+ * read (a writer holding it at a duty cycle near 100%) can run the spend out of
+ * its bound where the synchronous wait got through. That ends in the deny
+ * above, the grant left standing for a retry: fail closed. Holding the lock
+ * across a yield to close it is not an option, because a handler that exits at
+ * that yield would leave a lockfile that is never stolen.
+ *
+ * **Under {@link driveSync} nothing changes.** `commandHook` in process and in
+ * the serve worker, and `decideHarnessCall` for the Codex bridge, have no event
+ * loop that a signal could be dispatched on, so a yielded wait buys them
+ * nothing. The driver says so at the first pause (see {@link GateSteps}), and
+ * the spend is then exactly what it was: that zero pause (no pause under this
+ * driver) and one call with the caller's own options, whose writer waits for
+ * the lock synchronously, per head-moved attempt, as it always did.
+ *
+ * `attempt` receives the append options to use (the caller's own, with
+ * `lockTimeoutMs: 0` on the yielding path), and the attempt number (1-based),
+ * for a caller whose first attempt may reuse a read it already holds and whose
+ * later ones may not.
+ */
+function* spendUnderLock(logPath, append, attempt) {
+    // The shared pause, and the driver's answer to whether it turns the loop.
+    const yielding = (yield BEFORE_SPEND) === true;
+    if (!yielding)
+        return attempt(append ?? {}, 1);
+    const askedBudget = append?.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+    const budgetMs = Number.isFinite(askedBudget) ? Math.max(0, askedBudget) : DEFAULT_LOCK_TIMEOUT_MS;
+    // Never a zero (or non-finite) retry: under `driveSync` a zero pause is no
+    // pause, and the probe loop would spin.
+    const askedRetry = append?.lockRetryMs ?? DEFAULT_LOCK_RETRY_MS;
+    const retryMs = Number.isFinite(askedRetry) ? Math.max(1, askedRetry) : DEFAULT_LOCK_RETRY_MS;
+    const once = { ...append, lockTimeoutMs: 0 };
+    const deadline = Date.now() + budgetMs;
+    for (let tries = 1;; tries += 1) {
+        let waited = tries > 1;
+        for (;;) {
+            if (!appendLockHeld(logPath))
+                break;
+            const left = deadline - Date.now();
+            if (left <= 0)
+                break;
+            waited = true;
+            yield Math.min(retryMs, left);
+        }
+        // Uncontended first try: the pause above was taken a probe ago, and the
+        // probe is the only thing that ran since. Otherwise the pause again, now
+        // immediately before the attempt.
+        if (waited)
+            yield BEFORE_SPEND;
+        const result = attempt(once, tries);
+        if (!lockTimedOut(result))
+            return result;
+        const left = deadline - Date.now();
+        if (left > 0) {
+            yield Math.min(retryMs, left);
+            continue;
+        }
+        // A copy, as `core/head-retry.ts` makes its own: only the message changes.
+        return {
+            ...result,
+            message: `${result.message ?? "lock-timeout"}; the spend waited for the log's lock on the event loop for its whole ${String(budgetMs)} ms bound, trying every ${String(retryMs)} ms, and another writer held it at each of its ${String(tries)} attempt${tries === 1 ? "" : "s"} (APRV-478). Nothing was appended.`,
+        };
+    }
+}
 function truncate(text, limit) {
     const collapsed = text.replace(/\s+/gu, " ").trim();
     return collapsed.length <= limit ? collapsed : `${collapsed.slice(0, limit - 1)}…`;
@@ -2742,8 +3035,25 @@ function withdrawAbandoned(run, streams, records, now, keepHash, only = null) {
  * is about (APRV-146). The gate requires it and compares it against what the
  * human answered: the same value keyed the carryover that found these grants, so
  * presenting it states, at the spend, the fact the match was made on.
+ *
+ * Steps since APRV-478: each key is spent through {@link spendUnderLock}, so a
+ * wait for the log's lock is a yield and the shared pause before the spend
+ * ({@link BEFORE_SPEND}) is taken there, immediately before each append.
+ *
+ * **A multi-key spend pauses before every key, deliberately.** A signal that
+ * lands after the first key is spent and before the second is dispatched at the
+ * second key's pause: the call blocks with the first key's `execution.started`
+ * already recorded (before the signal) and the rest unspent. That is the same
+ * outcome as a spend that fails on a later key, above: a recorded start for a
+ * call the harness does not run, a grant that costs one more prompt, and
+ * nothing authorized. The alternative, spending the later keys with no pause,
+ * would make each later key's lock wait synchronous again, and a signal there
+ * would be held through starts recorded AFTER it and answered with an allow.
+ * Recording nothing after the signal and blocking is the stricter of the two.
+ * An atomic spend of every key at once needs a gate operation that does not
+ * exist; this is the residue the SPEC hunk names for a multi-class call.
  */
-function consumeGrants(run, keys, hash, 
+function* consumeGrants(run, keys, hash, 
 /**
  * This invocation's own task id (APRV-200). The gate compares it against the
  * task the request record carries and records `grant_origin: "direct"` only
@@ -2751,11 +3061,12 @@ function consumeGrants(run, keys, hash,
  */
 task) {
     for (const key of keys) {
-        const spent = consumeHarnessGrant(run.logPath, key, run.actor, {
+        const spent = yield* spendUnderLock(run.logPath, run.options.append, (append) => consumeHarnessGrant(run.logPath, key, run.actor, {
             ...run.options,
+            append,
             presentedPayloadHash: hash,
             spendingTask: task,
-        });
+        }));
         if (!spent.ok)
             return { code: spent.code, message: `${key}: ${spent.message}` };
     }
@@ -2914,10 +3225,13 @@ known = null) {
  * declaration would buy no oversight and would double the volume of exactly the
  * traffic this is trying not to drown the log in. The supervised classes are
  * registered already, by the caller, which is what makes them sampleable.
+ *
+ * Steps since APRV-478, for the reason {@link consumeGrants} gives: each class
+ * is recorded through {@link spendUnderLock}, which takes the shared pause.
  */
-function recordUnattended(run, task, classes, hash) {
+function* recordUnattended(run, task, classes, hash) {
     for (const cls of classes) {
-        const started = startHarnessExecution(run.logPath, { task, actionKey: `${task}:${cls}`, cls, payload_hash: hash }, run.actor, run.options);
+        const started = yield* spendUnderLock(run.logPath, run.options.append, (append) => startHarnessExecution(run.logPath, { task, actionKey: `${task}:${cls}`, cls, payload_hash: hash }, run.actor, { ...run.options, append }));
         if (!started.ok)
             return { code: started.code, message: `${cls}: ${started.message}` };
     }
@@ -3045,7 +3359,11 @@ function renderVerdict(streams, adapter, codexCommand, verdict) {
         ? allow(streams, verdict.reason, adapter.kind, codexCommand)
         : deny(streams, verdict.code, verdict.detail, adapter.kind);
 }
-export function gateHarnessCall(streams, run, classes, 
+export function gateHarnessCall(...args) {
+    return driveSync(gateHarnessSteps(...args));
+}
+/** {@link gateHarnessCall} as steps, for a driver that yields (APRV-473). */
+function* gateHarnessSteps(streams, run, classes, 
 /**
  * The bytes the grant binds to: `{command, cwd}` for a Bash call, the change
  * itself for a file tool (APRV-124). Whatever this is, it is what reaches the
@@ -3306,8 +3624,9 @@ floor = null) {
             // SPEC.md §6.3), so there is nothing to wait for and nothing to spend.
             // What there is, since APRV-141, is something to charge: the start event
             // is this execution's authorization, and the registration `fresh` just
-            // wrote is what makes it a sampleable one.
-            const charged = recordUnattended(run, task, classes, hash);
+            // wrote is what makes it a sampleable one. The shared pause before the
+            // spend is taken inside (APRV-473, APRV-478).
+            const charged = yield* recordUnattended(run, task, classes, hash);
             if (charged !== null) {
                 return sayDeny(`hook-gate-refused:${charged.code}`, charged.message);
             }
@@ -3315,7 +3634,7 @@ floor = null) {
         }
         // Every gated class carried an unspent grant: a human already answered this
         // exact question about these exact bytes, and nobody is asked again.
-        const failed = consumeGrants(run, spendKeys, hash, task);
+        const failed = yield* consumeGrants(run, spendKeys, hash, task);
         if (failed !== null) {
             return sayDeny(`hook-gate-refused:${failed.code}`, failed.message);
         }
@@ -3349,24 +3668,42 @@ floor = null) {
     // `process.exit` is deliberate and immediate: the default disposition for
     // these signals is to die, and a handler that only withdrew would leave the
     // hook wedged in its poll loop with the harness waiting on it.
+    //
+    // APRV-473, APRV-475. On every `approval hook <harness>` CLI route this
+    // handler gets its turn: the wait yields to the event loop between polls
+    // (`driveYielding`), so a signal is dispatched within one pause of its
+    // arrival instead of being held until the wait returns. It exits, so nothing
+    // after it in this function runs: no poll reads the grant a human gives
+    // afterwards, and nothing spends it. The synchronous callers (`commandHook`
+    // in process, the Codex bridge's `decideHarnessCall`, a serve worker thread)
+    // drive these steps with `driveSync`, under which this listener is
+    // registered and removed without the loop ever turning, so it never runs
+    // there and never writes into a stdout that is not a hook's (the bridge's is
+    // a JSON-RPC channel). A serve thread's caller departing is `callerGone`.
     const onSignal = (signal) => {
         leaveWait();
-        withdrawPending(run, streams, ownKeys, `the requesting hook process received ${signal} while waiting; the session is ending, so no retry will adopt this request`);
-        // APRV-445. On Hermes an exit with nothing on stdout is an ALLOW unless the
-        // exit is 2, and a harness tearing down may still read the verdict. So the
-        // block directive goes out first, written synchronously because
-        // `process.exit` below does not wait for a stream to drain.
-        if (run.harness === "hermes") {
-            const directive = harnessBlockDirective("hook-interrupted", `the hook received ${signal} while waiting for a decision; nothing authorizes this call`, "hermes");
-            try {
-                writeSync(1, directive.stdout);
-            }
-            catch {
-                // stdout is gone; the exit code below is the whole verdict.
-            }
-            process.exit(HERMES_DENY_EXIT);
+        // APRV-445, APRV-475. A harness tearing down may still read the verdict,
+        // and on several harnesses an exit with nothing on stdout is not a block
+        // (Hermes reads it as an ALLOW unless the exit is 2; Claude Code, Codex
+        // and Muse read most such exits as a failed hook and run the call). So the
+        // harness's own block directive goes out FIRST, in its own dialect,
+        // written synchronously, before the withdrawal: the withdrawal is a
+        // compare-and-append that can wait up to the lock timeout behind another
+        // writer, and a harness that escalates SIGTERM to SIGKILL inside that wait
+        // must already be holding the block (APRV-475 refuter). The directive does
+        // not depend on the withdrawal's outcome, and a withdrawal that never lands
+        // leaves the question open as a timed-out one is.
+        const exitCode = writeInterruptedWait(signal, run.harness);
+        try {
+            withdrawPending(run, streams, ownKeys, `the requesting hook process received ${signal} while waiting; the session is ending, so no retry will adopt this request`);
+        }
+        catch (cause) {
+            // The withdrawal failed outright (an I/O fault inside the append). The
+            // block is already on stdout: a block with the question left standing
+            // is the stricter of the two outcomes this handler can still reach.
+            streams.err(`approval: the hook could not withdraw its request after ${signal}: ${cause instanceof Error ? cause.message : String(cause)}\n`);
         }
-        process.exit(EXIT_USAGE);
+        process.exit(exitCode);
     };
     const onTerm = () => onSignal("SIGTERM");
     const onInt = () => onSignal("SIGINT");
@@ -3431,7 +3768,7 @@ floor = null) {
                         streams.err(`approval: the log's last line was incomplete when this hook read it (another writer mid-append); reading again rather than giving up on ${task}\n`);
                     }
                     tornReads += 1;
-                    sleepSync(Math.min(run.intervalMs, Math.max(0, deadline - Date.now())));
+                    yield Math.min(run.intervalMs, Math.max(0, deadline - Date.now()));
                     continue;
                 }
                 // AT the deadline (APRV-427 review). A clean read at this tick would
@@ -3536,13 +3873,22 @@ floor = null) {
                 if (states.every((state) => state === "granted")) {
                     // The grants are spent before the allow is printed, so this exact
                     // command cannot ride the same authorization twice.
+                    //
+                    // APRV-473, APRV-478. `consumeGrants` turns the event loop before it
+                    // spends: once per retry while another writer holds the log's lock,
+                    // and once more (`BEFORE_SPEND`) immediately before each append. A
+                    // signal that arrived while this read ran, or while the spend waited
+                    // for the lock, is dispatched there, to the handler above, which
+                    // blocks, withdraws (a no-op now the request is decided, refused
+                    // `already-decided`) and exits. The grant is then left unspent rather
+                    // than recorded as the start of a call the harness gave up on.
                     leaveWait();
                     // Looked at again now the lock is held: re-taking it may have waited,
                     // and a caller that left meanwhile must not have its grant spent on a
                     // verdict nobody will receive. The retry is who spends it.
                     if (callerGone())
                         return sayGone();
-                    const failed = consumeGrants(run, spendKeys, hash, task);
+                    const failed = yield* consumeGrants(run, spendKeys, hash, task);
                     if (failed !== null) {
                         return sayDeny(`hook-gate-refused:${failed.code}`, failed.message);
                     }
@@ -3586,7 +3932,7 @@ floor = null) {
                 }
                 return keptOpen(`no decision on ${waitKeys.join(", ")} within the hook's ${waitText(run)}.`, stillLagging);
             }
-            sleepSync(Math.min(run.intervalMs, Math.max(0, deadline - Date.now())));
+            yield Math.min(run.intervalMs, Math.max(0, deadline - Date.now()));
         }
     }
     catch (cause) {
@@ -4809,7 +5155,7 @@ function bypassBanner(window, classes, seq) {
  * command that ran and left no record is the one state this feature must not be
  * able to reach, so an append failure is a deny.
  */
-function runBypass(streams, input, adapter, cwd, logPath, flags, actor, window, 
+function* runBypass(streams, input, adapter, cwd, logPath, flags, actor, window, 
 /**
  * The verified read `window` was derived from (APRV-294), handed on to the
  * append so the same records answer "is a window open" and "which head does
@@ -4869,7 +5215,12 @@ decidedOn) {
     // window path is the one a human comes back to read, so the binary that
     // printed the allow is named on it.
     const provenance = harnessProvenance(adapter.kind, input.harnessVersion);
-    const recorded = recordGateBypass(logPath, {
+    // APRV-473 refuter: the bypass record is this path's authorization, exactly
+    // as `execution.started` is the gated path's, so a signal held through the
+    // stdin read is dispatched before it is written (`BEFORE_SPEND`, taken
+    // inside `spendUnderLock`, after any wait for the log's lock, which yields:
+    // APRV-478).
+    const recorded = yield* spendUnderLock(logPath, undefined, (append, round) => recordGateBypass(logPath, {
         tool: input.toolName,
         summary: truncate(described.headline, SUMMARY_LIMIT),
         classes,
@@ -4878,14 +5229,17 @@ decidedOn) {
         ...(input.toolUseId === null ? {} : { toolUseId: input.toolUseId }),
         ...(input.cwd.length === 0 ? {} : { cwd: input.cwd }),
         ...(provenance === null ? {} : { harness: provenance }),
-    }, actor, {}, 
-    // APRV-294: the window this verdict was decided under, and the read it was
-    // decided on. The append uses both, so a window that ended in between is
-    // reported as the thing that happened rather than as "no window is open".
+    }, actor, { append }, 
+    // APRV-294: the window this verdict was decided under, and the read it
+    // was decided on. The append uses both, so a window that ended in
+    // between is reported as the thing that happened rather than as "no
+    // window is open". The read seeds the FIRST round only: a later round
+    // exists because another writer took the lock, so that read's head is
+    // already known to be stale, and `recordGateBypass` re-reads.
     {
         openedSeq: window.seq,
-        ...(decidedOn === null ? {} : { read: decidedOn }),
-    });
+        ...(decidedOn === null || round > 1 ? {} : { read: decidedOn }),
+    }));
     if (!recorded.ok) {
         // Invariant 8: the record lands before the allow, so a refusal here is a
         // deny even though a window is open. `append-failed` reaches the caller
@@ -4898,7 +5252,7 @@ decidedOn) {
     const notes = [...described.notes, ...(policyNote === null ? [] : [policyNote])];
     return allow(streams, `gate-open: ${classes.join(", ")} bypassed by the window opened at seq ${String(window.seq)} by ${window.openedBy} (expires ${window.expiresAt}); recorded as gate.bypassed seq ${String(recorded.record.seq)}${notes.length === 0 ? "" : ` (${notes.join("; ")})`}`, adapter.kind, codexCommand);
 }
-function runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
+function* runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
     // Codex and (APRV-445) Hermes answer a misconfigured entry with a verdict:
     // on both a usage error's empty stdout is a harness that runs the call, and
     // on Hermes a non-zero exit with an empty stdout is an allow outright.
@@ -5199,13 +5553,13 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
     // words. The window suspends the POLICY; it never suspends the log.
     const looked = lookupWindow(logPath);
     if (looked.window !== null) {
-        return runBypass(streams, input, adapter, cwd, logPath, parsed.flags, actor, looked.window, 
+        return yield* runBypass(streams, input, adapter, cwd, logPath, parsed.flags, actor, looked.window, 
         // APRV-294. The records this window was derived from travel with it: the
         // bypass record is appended against the head they ended at, so the
         // verdict and the record are one read of the log.
         looked.records === null ? null : { records: looked.records, head: looked.head });
     }
-    return renderVerdict(streams, adapter, codexCommand, decideHarnessCall({
+    return renderVerdict(streams, adapter, codexCommand, yield* decideHarnessSteps({
         streams,
         input,
         adapter,
@@ -5244,6 +5598,10 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
  * progress and withdrawal lines, which are a report rather than a decision.
  */
 export function decideHarnessCall(decide) {
+    return driveSync(decideHarnessSteps(decide));
+}
+/** {@link decideHarnessCall} as steps, for a driver that yields (APRV-473). */
+function* decideHarnessSteps(decide) {
     const { streams, input, adapter, cwd, logPath, root, options, actor, timeoutMs, intervalMs, graceMs, codexCommand, windowRecords, } = decide;
     const harnessCapMs = decide.harnessCapMs ?? null;
     const harnessCapStated = decide.harnessCapStated ?? false;
@@ -5486,8 +5844,10 @@ export function decideHarnessCall(decide) {
         // §6.3), so nothing is requested, decided or granted here. What IS appended
         // since APRV-141 is the execution record itself — the moment the policy
         // authorized this command — because a budget the busiest path does not
-        // charge is not a budget. See `recordUnattended`.
-        const charged = recordUnattended(run, task, classes, payloadHash(payload));
+        // charge is not a budget. See `recordUnattended`. A held signal is
+        // dispatched first, at the pause it takes before the append (APRV-473,
+        // `BEFORE_SPEND`), and a wait for the log's lock yields (APRV-478).
+        const charged = yield* recordUnattended(run, task, classes, payloadHash(payload));
         if (charged !== null) {
             return {
                 permission: "deny",
@@ -5503,14 +5863,14 @@ export function decideHarnessCall(decide) {
     // do not survive a merge. An initialized-but-empty `.approval/log/` counts as
     // reachable — an audit trail that has recorded nothing is an empty log, not a
     // missing one (see `preflightLog`) — and `register` appends the first line.
-    return gateHarnessCall(streams, run, classes, payload, headline, task, note, floor);
+    return yield* gateHarnessSteps(streams, run, classes, payload, headline, task, note, floor);
 }
-function commandHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
+function* commandHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
     if (adapter.kind === "hermes") {
-        return hermesFailClosed(argv, streams, cwd, readStdin, adapter, waitSeam);
+        return yield* hermesFailClosed(argv, streams, cwd, readStdin, adapter, waitSeam);
     }
     try {
-        return runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam);
+        return yield* runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam);
     }
     catch (cause) {
         // A hook that throws is a hook the harness treats as a non-blocking error,
@@ -5541,7 +5901,7 @@ function commandHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
  * nothing on stdout by design. A throw becomes the same block the other
  * adapters' catch produces.
  */
-function hermesFailClosed(argv, streams, cwd, readStdin, adapter, 
+function* hermesFailClosed(argv, streams, cwd, readStdin, adapter, 
 /** APRV-427: serve's wait seam, passed through untouched (null on the CLI). */
 waitSeam) {
     let stdout = "";
@@ -5567,12 +5927,24 @@ waitSeam) {
     // handler is prepended, so inside the wait it answers first and exits. CLI
     // only: under `approval serve` (a wait seam) the process's signals belong to
     // the server.
+    //
+    // A JS listener runs only when the event loop turns (APRV-466). On the CLI
+    // this run is driven by `driveYielding` (APRV-473), so the loop turns at
+    // every pause: between the wait's polls, where the wait's handler answers,
+    // and once before anything appends `execution.started` (`BEFORE_SPEND`),
+    // where whichever of the two is registered answers a signal held through
+    // the synchronous stretch before it (the stdin read, the classification, the
+    // registration). A signal that lands after the last pause is dispatched
+    // once the run has returned, to the `approval` bin's own guard, which exits
+    // with the answer this run gave. While these guards are registered,
+    // HERMES_SIGNAL_OWNER tells the bin's guard to step aside, so the two never
+    // both print.
     const onEarlySignal = (signal) => {
         if (raw !== null && isHermesPostEvent(raw))
             process.exit(EXIT_OK);
         if (stdout.length === 0) {
             try {
-                writeSync(1, harnessBlockDirective("hook-interrupted", `the hook received ${signal} before it reached a verdict; nothing authorizes this call`, "hermes").stdout);
+                writeSync(1, hermesInterruptedDirective(signal));
             }
             catch {
                 // stdout is gone; the exit code below is the whole verdict.
@@ -5582,23 +5954,27 @@ waitSeam) {
     };
     const onEarlyTerm = () => onEarlySignal("SIGTERM");
     const onEarlyInt = () => onEarlySignal("SIGINT");
+    const owner = globalThis;
+    const ownerBefore = owner[HERMES_SIGNAL_OWNER];
     if (waitSeam === null) {
         process.on("SIGTERM", onEarlyTerm);
         process.on("SIGINT", onEarlyInt);
+        owner[HERMES_SIGNAL_OWNER] = true;
     }
     try {
-        return hermesVerdict();
+        return yield* hermesVerdict();
     }
     finally {
         if (waitSeam === null) {
+            owner[HERMES_SIGNAL_OWNER] = ownerBefore;
             process.off("SIGTERM", onEarlyTerm);
             process.off("SIGINT", onEarlyInt);
         }
     }
-    function hermesVerdict() {
+    function* hermesVerdict() {
         let code;
         try {
-            code = runHarnessHook(argv, tracked, cwd, reading, adapter, waitSeam);
+            code = yield* runHarnessHook(argv, tracked, cwd, reading, adapter, waitSeam);
         }
         catch (cause) {
             // A post-event never blocks: the call already ran (see the post path).
@@ -5657,6 +6033,48 @@ export function commandHook(argv, streams, cwd, readStdin = defaultStdin,
  * the call polls. Every CLI route omits it. See {@link HookWaitSeam}.
  */
 waitSeam = null) {
+    return driveSync(hookSteps(argv, streams, cwd, readStdin, waitSeam));
+}
+/**
+ * {@link commandHook}, with its pauses on the event loop (APRV-473).
+ *
+ * Every `approval hook` CLI route, from `main`: Hermes since APRV-473, the
+ * other five harnesses (and `classify`, which never pauses) since APRV-475.
+ * The same steps as the synchronous form; the difference is that a SIGTERM or
+ * SIGINT reaches the listener in force within one pause of arriving, instead
+ * of after the run returns. In the wait that listener withdraws the question
+ * this invocation opened, prints the harness's own `hook-interrupted` block
+ * directive ({@link interruptedWaitDirective}) and exits with that directive's
+ * exit code, so a grant that lands after the harness abandoned the call is
+ * never spent on it. See {@link GateSteps} and {@link BEFORE_SPEND}.
+ */
+export function commandHookYielding(argv, streams, cwd, readStdin = defaultStdin) {
+    // The loop now turns mid-wait, so an asynchronous stderr failure (EPIPE on a
+    // closed pipe after `announceWait`, where pipes are asynchronous) would
+    // surface as an uncaught exception in the middle of the wait and end it
+    // without withdrawing. Stderr carries progress lines and never the verdict,
+    // so its failure is swallowed (APRV-473 refuter).
+    process.stderr.on("error", () => undefined);
+    return driveYielding(hookSteps(argv, streams, cwd, readStdin, null));
+}
+/**
+ * The steps {@link commandHook} and {@link commandHookYielding} drive, for a
+ * test that drives them itself (APRV-475 refuter).
+ *
+ * A test seam and nothing more: it exists so a test can stop at each pause and
+ * look at the log, which is the only deterministic way to pin that the pause
+ * before a spend ({@link BEFORE_SPEND}) sits between the read that found a
+ * grant and the append that spends it, on every harness. No CLI route and no
+ * embedding caller uses it; the one entry for those is the two drivers above.
+ *
+ * Pass `true` to each `next()` to step as {@link commandHookYielding} does
+ * (the spend then waits for a held log lock in yields, APRV-478); `false` or
+ * nothing steps as {@link commandHook} does.
+ */
+export function commandHookSteps(argv, streams, cwd, readStdin) {
+    return hookSteps(argv, streams, cwd, readStdin, null);
+}
+function* hookSteps(argv, streams, cwd, readStdin, waitSeam) {
     const sub = argv[0];
     const rest = argv.slice(1);
     if (sub === undefined) {
@@ -5670,7 +6088,7 @@ waitSeam = null) {
     // boundary and doctor use, so a kind that can be recorded is a kind that can
     // be invoked, and neither can be added without the other.
     if (isHarnessKind(sub)) {
-        return commandHarnessHook(rest, streams, cwd, readStdin, HARNESS_ADAPTERS[sub], waitSeam);
+        return yield* commandHarnessHook(rest, streams, cwd, readStdin, HARNESS_ADAPTERS[sub], waitSeam);
     }
     if (sub === "classify")
         return commandClassify(rest, streams, cwd);