approval-md 0.4.0 → 0.4.2

package/dist/src/cli/hook.js

@@ -76,7 +76,7 @@ import { existsSync, readdirSync, readFileSync, realpathSync, statSync, writeSyn
 import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve as resolvePathSegments, sep, } from "node:path";
-import { attestationRefusal, checkAttestation } from "../core/attest.js";
+import { attestationRefusal, checkAttestation, checkAttestationOfBytes } from "../core/attest.js";
 import { childEnvironment } from "../core/child-env.js";
 import { classifyCommand, commandSegmentShapes, commandSegmentWords, CODE_EXECUTING_RULES, CONTRIBUTOR_SUFFIX, GATE_SELF_CLASS, isCredentialPath, protectedPathClass, } from "../core/command-class.js";
 import { consumeHarnessGrant, findHarnessCarry, finishHarnessExecution, isProposalTask, register, request, startHarnessExecution, withdraw, } from "../core/gate.js";
@@ -85,9 +85,12 @@ 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";
+import { loadPolicy, loadPolicyText, parseDuration, POLICY_FILENAMES, } from "../core/policy-load.js";
+import { isRecordableToolName, toolMapVerdict, UNMAPPED_TOOL_CLASS, } from "../core/tool-map.js";
 import { READ_OUT_OF_SCOPE_CLASS, effectiveReadRoots, isInReadScope, readTargetsOf, renderReadRoots, } from "../core/read-scope.js";
 import { harnessLaunchNeedsRule, harnessLaunchUnruledRefusal, humanOnlyRefusal, resolve as resolvePolicy, } from "../core/policy-match.js";
 import { payloadOf, readVerifiedRecords, requestExpiresAt, requestState, useVerifiedSnapshots, } from "../core/state.js";
@@ -810,6 +813,100 @@ function toolRuleOf(adapter, input) {
     }
     return adapter.toolRules(input.toolName, input.toolInput);
 }
+/**
+ * Is this call one the adapter's own tables leave unclaimed? (APRV-499.)
+ *
+ * Unclaimed means: not the shell tool, not a file or read tool, not a
+ * pass-through tool, and not a tool the hard-coded rule table answers (gated OR
+ * read). Exactly these calls reach the policy's `tools` mapping and its
+ * unmapped-tool default, and before APRV-499 exactly these were answered "not a
+ * gated tool". The adapter's tables keep precedence because they read the
+ * call's arguments, and a `tools` entry reads only its name.
+ */
+function unclaimedTool(adapter, input) {
+    if (input.toolName === adapter.shellTool)
+        return false;
+    if (adapter.fileTools.includes(input.toolName))
+        return false;
+    if (adapter.readTools.includes(input.toolName))
+        return false;
+    if (adapter.passThroughTools?.includes(input.toolName) === true)
+        return false;
+    return toolRuleOf(adapter, input) === null;
+}
+/**
+ * The policy file's bytes, found the way `loadPolicy` finds them: `--policy`
+ * when given, else the first of {@link POLICY_FILENAMES} in the policy
+ * directory, else in `cwd`. `null` when there is none to read.
+ *
+ * Read ONCE and handed to both the parse and the attestation hash (APRV-142's
+ * rule, applied to this hook's unclaimed-tool answer), so no file swap between
+ * the two can attest one policy and decide by another.
+ */
+function readHookPolicyBytes(options, cwd) {
+    const candidates = options.policy?.file === undefined
+        ? POLICY_FILENAMES.map((filename) => join(options.policy?.dir ?? cwd, filename))
+        : [options.policy.file];
+    for (const candidate of candidates) {
+        try {
+            return { path: candidate, bytes: readFileSync(candidate) };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function unclaimedStanding(options, cwd, toolName, records) {
+    const read = readHookPolicyBytes(options, cwd);
+    if (read === null)
+        return { kind: "decide" };
+    const load = loadPolicyText(read.path, read.bytes.toString("utf8"));
+    if (!load.ok)
+        return { kind: "decide" };
+    if (toolMapVerdict(load.policy, toolName).kind !== "not-gated")
+        return { kind: "decide" };
+    if (records === null) {
+        return {
+            kind: "unattested",
+            code: "hook-io",
+            detail: `${toolName} is outside the gate only under an attested policy, and the log that would show the attestation could not be read and verified; nothing was appended`,
+        };
+    }
+    const refusal = attestationRefusal(checkAttestationOfBytes(records, read.bytes));
+    if (refusal === null)
+        return { kind: "ungated" };
+    return {
+        kind: "unattested",
+        code: `hook-gate-refused:${refusal.code}`,
+        detail: `${refusal.message}. ${toolName} is a tool this adapter does not classify, and whether the policy gates it (a \`tools\` entry, \`defaults.unmapped_tool\`) is a question only the attested policy answers, so the on-disk file is not read as "not a gated tool" until a human attests it. Nothing was appended.`,
+    };
+}
+/**
+ * {@link unclaimedStanding} for a caller that has not read the log: the fast
+ * path and the post-execution half. One verified read, resumed behind the
+ * daemon's snapshot (APRV-188) where there is one.
+ */
+function unclaimedUngated(flags, cwd, toolName) {
+    const { logPath, options } = hookScope(flags, cwd);
+    useVerifiedSnapshots(true);
+    const read = readVerifiedRecords(logPath);
+    return unclaimedStanding(options, cwd, toolName, read.ok ? read.records : null).kind === "ungated";
+}
+/**
+ * The `hook-policy-unavailable` detail (APRV-499, refutation S2): the load's
+ * own code and message, the first per-entry errors it computed, and the
+ * repair, so the human reading the refusal is told what to change.
+ */
+function policyUnavailableDetail(load) {
+    const errors = load.errors ?? [];
+    const shown = errors
+        .slice(0, 5)
+        .map((error) => `${error.path.length === 0 ? "(root)" : error.path}: ${error.message}`);
+    const more = errors.length > shown.length ? `; and ${String(errors.length - shown.length)} more` : "";
+    const listed = shown.length === 0 ? "" : ` (${shown.join("; ")}${more})`;
+    return `${load.code}: ${load.message}${listed}; every class resolves to manual and the hook cannot verify a decision. Repair: correct ${shown.length === 0 ? "the policy file" : "each entry named above"}, then have a human attest the result (\`approval policy attest\`); an edited policy is inoperative until then`;
+}
 /**
  * Every harness this runtime speaks a hook protocol for, by kind (APRV-358).
  *
@@ -988,6 +1085,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 +2288,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 +3130,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 +3156,14 @@ 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,
-        });
+            // APRV-499 (refutation S3): a mapped or unmapped spend names its tool.
+            ...(run.harnessTool === undefined ? {} : { harnessTool: run.harnessTool }),
+        }));
         if (!spent.ok)
             return { code: spent.code, message: `${key}: ${spent.message}` };
     }
@@ -2914,10 +3322,20 @@ 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) {
+    const harnessTool = run.harnessTool;
     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,
+            ...(harnessTool === undefined ? {} : { harness_tool: harnessTool }),
+        }, run.actor, { ...run.options, append }));
         if (!started.ok)
             return { code: started.code, message: `${cls}: ${started.message}` };
     }
@@ -3045,7 +3463,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
@@ -3225,6 +3647,9 @@ floor = null) {
         const registered = register(run.logPath, { task, envelope }, run.actor, {
             ...run.options,
             ...(provenance === null ? {} : { harness: provenance }),
+            // APRV-499: the hook is the one caller that may declare the reserved
+            // harness.tool.unmapped class.
+            toolMapHook: true,
         });
         if (!registered.ok) {
             return sayDeny(`hook-gate-refused:${registered.code}`, registered.message);
@@ -3306,8 +3731,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 +3741,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 +3775,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 +3875,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 +3980,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 +4039,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) {
@@ -3930,7 +4383,14 @@ function runPostToolUse(flags, streams, cwd, input, actor, adapter) {
         // nothing, and the close below finds no start and says so in its own words.
         !adapter.readTools.includes(input.toolName) &&
         // APRV-445: a tool the rule table gated wrote a start like any other.
-        toolRuleOf(adapter, input)?.kind !== "gated") {
+        toolRuleOf(adapter, input)?.kind !== "gated" &&
+        // APRV-499: an unclaimed tool the policy maps, or one it records or asks
+        // about as unmapped, wrote a start too. So did any unclaimed tool whose
+        // policy no longer loads or is not the attested one, as far as this half
+        // can tell, so that one goes on to the close, which finds the start or says
+        // there is none. Only an ATTESTED policy that loads and leaves the tool
+        // outside the gate keeps this answer (fix round 1, refutation B1).
+        (!unclaimedTool(adapter, input) || unclaimedUngated(flags, cwd, input.toolName))) {
         return report(streams, "post-tool-not-gated", `${input.toolName} is not a gated tool, so no execution.started was ever written for it`);
     }
     if (input.toolUseId === null) {
@@ -3971,7 +4431,23 @@ function runPostToolUse(flags, streams, cwd, input, actor, adapter) {
     }
     return report(streams, POST_TOOL_REPORTED, `recorded ${reading.outcome} for ${String(finished.records.length)} delegated execution(s) of ${finished.task}`, { task: finished.task, outcome: reading.outcome, appended: finished.records.length });
 }
-function describeToolCall(input, adapter, protectedPaths, cwd, readRoots = []) {
+function describeToolCall(input, adapter, protectedPaths, cwd, readRoots = [], 
+/**
+ * The loaded policy whose `tools` mapping and `defaults.unmapped_tool` an
+ * unclaimed call is answered by (APRV-499), or `null` when there is none to
+ * read (the open window over a policy that did not load).
+ */
+toolPolicy = null, 
+/**
+ * May an unclaimed call the policy leaves outside the gate be described as
+ * "not a gated tool"? (APRV-499 fix round 1, refutations B1 and S1.) The
+ * closed path passes `true` and checks the attestation on the allow it gets
+ * back. The open window passes `true` only for an attested policy that
+ * loads; otherwise an unclaimed call is described under
+ * `harness.tool.unmapped`, so the bypass RECORDS it rather than letting it
+ * run unrecorded on the word of a file nobody vouched for.
+ */
+ungatedAllowed = true) {
     if (adapter.kind === "codex" && input.toolName === "apply_patch") {
         // APRV-363. The app-server's LEGACY `applyPatchApproval` carries its change
         // as a MAP of path to change, inline on the request, and never as an
@@ -4190,6 +4666,42 @@ function describeToolCall(input, adapter, protectedPaths, cwd, readRoots = []) {
             notes: [],
         };
     }
+    // APRV-499: a call the adapter's own tables leave unclaimed (every MCP tool
+    // among them) is answered by the policy's `tools` mapping, first match wins,
+    // then by `defaults.unmapped_tool`. Below the rule table and the shell, and
+    // above the read and file branches only because those two never see an
+    // unclaimed call: the predicate excludes them. The payload is the whole call,
+    // as the rule table's is, so a grant binds every argument; only the NAME is
+    // written to the log, on the start record.
+    if (unclaimedTool(adapter, input)) {
+        const verdict = toolPolicy === null ? { kind: "not-gated" } : toolMapVerdict(toolPolicy, input.toolName);
+        if (verdict.kind === "not-gated" && ungatedAllowed) {
+            return { kind: "allow", reason: `${input.toolName} is not a gated tool`, unclaimed: true };
+        }
+        // Refutation S4: a name the record could not carry is refused here, by
+        // name, before anything is appended, rather than at the write boundary.
+        if (!isRecordableToolName(input.toolName)) {
+            return {
+                kind: "deny",
+                code: "hook-io",
+                detail: `tool-name-invalid: ${JSON.stringify(input.toolName.slice(0, 80))}${input.toolName.length > 80 ? "…" : ""} is classified by the policy's tool mapping, and a tool so classified is recorded by name, which must be 1 to 256 of letters, digits, _, ., : and - (the characters a tools entry can match). Nothing was appended`,
+            };
+        }
+        const cls = verdict.kind === "not-gated" ? UNMAPPED_TOOL_CLASS : verdict.cls;
+        const note = verdict.kind === "mapped"
+            ? `tools entry ${String(verdict.index)} (${JSON.stringify(verdict.match)}) maps ${input.toolName} to ${verdict.cls} (APRV-499)`
+            : verdict.kind === "unmapped"
+                ? `${input.toolName} matches no tools entry; defaults.unmapped_tool: ${verdict.mode} (APRV-499)`
+                : `${input.toolName} is outside the gate only under an attested policy that loads, and this one ${toolPolicy === null ? "did not load" : "is not attested"}, so it is described as ${UNMAPPED_TOOL_CLASS} (APRV-499)`;
+        return {
+            kind: "gated",
+            classes: [cls],
+            payload: { tool: input.toolName, input: input.toolInput },
+            headline: `${input.toolName} (${cls})`,
+            notes: [note],
+            harnessTool: input.toolName,
+        };
+    }
     // APRV-347, above the file-tool branch because the two lists are disjoint and
     // a read is the cheaper question to answer: a read inside the scope, or one
     // naming no path at all, returns `null` here and takes the allow below.
@@ -4809,7 +5321,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
@@ -4831,7 +5343,18 @@ decidedOn) {
     // APRV-347. The window suspends the POLICY, not the classification: a read
     // outside the scope is described as one here too, so the bypass RECORD says
     // what was actually authorized rather than calling it an ordinary read.
-    resolveReadRoots(cwd, policyRootOf(load, scope.root), load.ok ? load.policy.read_scope?.roots : undefined));
+    resolveReadRoots(cwd, policyRootOf(load, scope.root), load.ok ? load.policy.read_scope?.roots : undefined), 
+    // APRV-499. The window suspends the policy's ANSWER, not its mapping: a
+    // mapped or unmapped tool is described under its class here too, so the
+    // bypass record names it.
+    load.ok ? load.policy : null, 
+    // Fix round 1 (refutations S1 and B1): "not a gated tool" is believed only
+    // from an attested policy that loads. A policy that did not load, or one
+    // nobody attested, cannot say a tool is outside the gate, so the call is
+    // described under harness.tool.unmapped and the bypass records it: a
+    // window being open does not let a call run unrecorded.
+    unclaimedStanding(scope.options, cwd, input.toolName, decidedOn?.records ?? null).kind ===
+        "ungated");
     if (described.kind === "deny") {
         return deny(streams, described.code, `${described.detail} The open window does not reach this: a command the classifier cannot read is a command nothing here can establish is safe to run unapproved.`, adapter.kind);
     }
@@ -4869,7 +5392,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 +5406,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 +5429,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.
@@ -5146,28 +5677,41 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
         input.toolName !== adapter.shellTool &&
         !adapter.fileTools.includes(input.toolName)) {
         if (!adapter.readTools.includes(input.toolName)) {
-            return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+            // APRV-499: an unclaimed tool is answered here, with one policy load,
+            // only when the policy loads and neither maps it nor declares
+            // `defaults.unmapped_tool`. Otherwise it goes on to the path below, where
+            // a mapped or unmapped call is classified and a policy that did not load
+            // is refused.
+            // Fix round 1 (refutation B1): and only when those bytes are the ATTESTED
+            // policy, which costs one verified read of the log. Anything else goes on
+            // to the path below, which refuses it in the gate's own words or, under
+            // an open window, records the bypass.
+            if (unclaimedUngated(parsed.flags, cwd, input.toolName)) {
+                return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+            }
         }
-        // APRV-347, and the placement is the whole of its cost. A read tool call is
-        // the most frequent event a session produces, and before this task it was
-        // answered here with no policy load, no verified read of the log and no
-        // window lookup. Everything below this line is expensive, so the reads that
-        // do not need it must not pay for it.
-        //
-        // The short-circuit is sound because `read_scope` is ADDITIVE: it can only
-        // widen the roots, so a target already inside the BUILT-IN roots is inside
-        // the effective ones whatever the policy says, and the policy need not be
-        // read to know it. A target outside them falls through, the policy is
-        // loaded below, and `describeToolCall` asks again with the widened set —
-        // which is where a policy-declared root actually takes effect.
-        //
-        // The cost of the fast path is a handful of `realpath` calls and no process
-        // spawn, provided the hook is configured with `--dir` as the docs show
-        // (otherwise `hookScope` runs `git rev-parse` to find the primary).
-        const early = hookScope(parsed.flags, cwd);
-        if (credentialReadGate(input.toolName, input.toolInput, cwd) === null &&
-            readToolGate(input.toolName, input.toolInput, resolveReadRoots(cwd, early.root), cwd) === null) {
-            return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+        else {
+            // APRV-347, and the placement is the whole of its cost. A read tool call is
+            // the most frequent event a session produces, and before this task it was
+            // answered here with no policy load, no verified read of the log and no
+            // window lookup. Everything below this line is expensive, so the reads that
+            // do not need it must not pay for it.
+            //
+            // The short-circuit is sound because `read_scope` is ADDITIVE: it can only
+            // widen the roots, so a target already inside the BUILT-IN roots is inside
+            // the effective ones whatever the policy says, and the policy need not be
+            // read to know it. A target outside them falls through, the policy is
+            // loaded below, and `describeToolCall` asks again with the widened set —
+            // which is where a policy-declared root actually takes effect.
+            //
+            // The cost of the fast path is a handful of `realpath` calls and no process
+            // spawn, provided the hook is configured with `--dir` as the docs show
+            // (otherwise `hookScope` runs `git rev-parse` to find the primary).
+            const early = hookScope(parsed.flags, cwd);
+            if (credentialReadGate(input.toolName, input.toolInput, cwd) === null &&
+                readToolGate(input.toolName, input.toolInput, resolveReadRoots(cwd, early.root), cwd) === null) {
+                return allow(streams, `${input.toolName} is not a gated tool`, adapter.kind, codexCommand);
+            }
         }
     }
     // APRV-188. From here on this process may resume a verified read behind the
@@ -5199,13 +5743,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 +5788,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;
@@ -5263,7 +5811,7 @@ export function decideHarnessCall(decide) {
         return {
             permission: "deny",
             code: "hook-policy-unavailable",
-            detail: `${load.code}: ${load.message}; every class resolves to manual and the hook cannot verify a decision`,
+            detail: policyUnavailableDetail(load),
         };
     }
     const protectedPaths = load.policy.protected_paths ?? [];
@@ -5275,12 +5823,43 @@ export function decideHarnessCall(decide) {
     // both paths since APRV-214 (see `describeToolCall`): the open window
     // classifies exactly as the closed one does, and a second copy of this would
     // be a second answer to "what is this command".
-    const described = describeToolCall(input, adapter, protectedPaths, cwd, readRoots);
+    const described = describeToolCall(input, adapter, protectedPaths, cwd, readRoots, load.policy);
     if (described.kind === "deny") {
         return { permission: "deny", code: described.code, detail: described.detail };
     }
     if (described.kind === "allow") {
-        return { permission: "allow", reason: described.reason };
+        if (described.unclaimed !== true)
+            return { permission: "allow", reason: described.reason };
+        // APRV-499 fix round 1 (refutation B1): the on-disk policy leaves this call
+        // outside the gate, and that is believed only of the ATTESTED policy. The
+        // log is required for that, exactly as it is for an unattended Bash call.
+        if (!existsSync(logPath) && !existsSync(dirname(logPath))) {
+            return {
+                permission: "deny",
+                code: "hook-log-unreachable",
+                detail: `no log at ${logPath}, so whether the policy that leaves ${input.toolName} ungated is the attested one cannot be established; the hook writes to an existing log and never creates one. Run \`approval init\` (then \`approval policy attest\`) in ${root}, or pass --log <path> to point the hook at the log that already exists`,
+            };
+        }
+        let records = windowRecords;
+        if (records === null) {
+            const read = readVerifiedRecords(logPath);
+            if (!read.ok)
+                return { permission: "deny", code: "hook-io", detail: read.message };
+            records = read.records;
+        }
+        const standing = unclaimedStanding(options, cwd, input.toolName, records);
+        if (standing.kind === "ungated")
+            return { permission: "allow", reason: described.reason };
+        if (standing.kind === "unattested") {
+            return { permission: "deny", code: standing.code, detail: standing.detail };
+        }
+        // The file changed between the two reads of this one decision: refuse,
+        // and the next call decides against whatever is there then.
+        return {
+            permission: "deny",
+            code: "hook-policy-unavailable",
+            detail: `the policy file changed while ${input.toolName} was being decided; nothing was appended, and a retry is decided against the file as it then stands`,
+        };
     }
     const { classes, payload, headline } = described;
     /** What the history-rewrite refinement did, for the decision reason. */
@@ -5335,6 +5914,7 @@ export function decideHarnessCall(decide) {
         // changed when an operator reordered their policy would read as a change of
         // state.
         channels: Object.keys(load.policy.channels ?? {}).sort(),
+        ...(described.harnessTool === undefined ? {} : { harnessTool: described.harnessTool }),
     };
     const resolutions = classes.map((cls) => resolvePolicy(load, cls));
     const autonomies = resolutions.map((resolution) => resolution.autonomy);
@@ -5486,8 +6066,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 +6085,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 +6123,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 +6149,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 +6176,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 +6255,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 +6310,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);