approval-md 0.3.0 → 0.4.1

package/dist/src/cli/hook.js

@@ -72,29 +72,31 @@
  * auditor holding the log alone. See `docs/claude-code-hook.md`.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync, writeSync } from "node:fs";
 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 { childEnvironment } from "../core/child-env.js";
-import { classifyCommand, commandSegmentWords, CODE_EXECUTING_RULES, CONTRIBUTOR_SUFFIX, GATE_SELF_CLASS, protectedPathClass, } from "../core/command-class.js";
-import { consumeHarnessGrant, findHarnessCarry, finishHarnessExecution, register, request, startHarnessExecution, withdraw, } from "../core/gate.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";
 import { openGateWindow, recordGateBypass, } from "../core/gate-window.js";
 import { harnessProvenance, isHarnessKind, } from "../core/harness-version.js";
-import { abandonedAfterMs, HOOK_DEFAULT_WAIT, HOOK_RETRY_GRACE_MS, } from "../core/harness-wait.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 { 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, requestState, useVerifiedSnapshots, } from "../core/state.js";
+import { payloadOf, readVerifiedRecords, requestExpiresAt, requestState, useVerifiedSnapshots, } from "../core/state.js";
 import { boolFlag, parseFlags, stringFlag } from "./args.js";
 import { EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
 import { primaryRoot as resolvePrimaryRoot } from "./git-scope.js";
-import { HOOK_GROK_HELP, HOOK_HELP, HOOK_MUSE_HELP } from "./help.js";
+import { HOOK_GROK_HELP, HOOK_HELP, HOOK_HERMES_HELP, HOOK_MUSE_HELP } from "./help.js";
 import { DEFAULT_LOG_PATH } from "./paths.js";
 import { refusal as renderRefusal, style, table } from "./style.js";
 import { usageErrorText } from "./usage.js";
@@ -111,6 +113,22 @@ const PRINCIPAL_ACTOR = /^(human|agent):.+/u;
 const DEFAULT_TIMEOUT = HOOK_DEFAULT_WAIT;
 /** Poll interval for the decision wait. */
 const DEFAULT_INTERVAL_MS = 1_000;
+/**
+ * How many CONSECUTIVE torn-tail reads the decision wait reads past before it
+ * treats the log as unreadable (APRV-427 review).
+ *
+ * The poll reads the log while other writers append to it: the daemon beside
+ * a CLI hook, and every other hook call beside one run by `approval serve`. An
+ * append is one write on an O_APPEND handle, but a reader on a filesystem that
+ * grows a file a page at a time can see the front of a line before its end, and
+ * the verified read calls that a torn tail. It is a moment in someone else's
+ * write, and the next tick reads the whole line. Treating it as terminal
+ * withdrew a live question and denied `hook-io` because a DIFFERENT call was
+ * mid-append. So a torn read is read again next tick, like a view that lags;
+ * only a tail that stays torn for this many ticks in a row (a crashed write,
+ * which nobody is going to finish) takes the old withdraw-and-deny path.
+ */
+export const TORN_TAIL_RETRIES = 5;
 /**
  * How much of the command line goes in the (claimed) summary field.
  *
@@ -199,8 +217,36 @@ export const HOOK_DENY_CODES = [
      * directory, once. Past the grace the hook withdraws it (reason `timeout`),
      * because a question nothing will adopt is a message on a phone that decides
      * nothing.
+     *
+     * **Who withdraws, stated because the deny text used to imply a scheduler
+     * that does not exist (APRV-410).** This process is over when it denies, so
+     * the withdrawal is made by the NEXT gated tool call this actor makes, from
+     * the sweep at the top of every gated invocation. It cannot be anyone else: a
+     * withdrawal is the requester's own (APRV-106 rule 1, `not-requester`), the
+     * gate refuses a `system:` withdrawal outright, and the event schema binds
+     * the one `system:` withdrawal that exists to `policy-drift` and to nothing
+     * else (APRV-235). So a session that denies here and then makes no further
+     * gated call leaves the question pending until the TTL, and a decision on it
+     * lands as an ordinary grant. What stops that grant authorizing anything is
+     * the other half of APRV-410: a retry past the grace does not carry it
+     * (`findHarnessCarry`), so it asks again.
      */
     "hook-timeout",
+    /**
+     * The harness ceiling this hook was told it runs under leaves no window a
+     * human could answer in (APRV-423).
+     *
+     * `--harness-cap` (or the harness's own documented maximum) at or below
+     * `HARNESS_CAP_MARGIN_MS` means the question would lapse at the instant it
+     * was asked: the request must end a margin before the harness kills the
+     * process that opened it, and there is no room left for the asking. Nothing
+     * is registered, nothing is requested and nobody's phone lights up. The
+     * repair is a configuration change — raise the harness entry's timeout, or
+     * state the real one — and it is a refusal rather than a silent widening
+     * because a hook that quietly ignored its own ceiling would be back to
+     * recording grants on calls nobody holds.
+     */
+    "hook-harness-cap-too-short",
     /** The gate refused intake; the gate's own code follows a colon. */
     "hook-gate-refused",
     /**
@@ -283,6 +329,32 @@ export const HOOK_DENY_CODES = [
      * and it cannot recall a prompt the model has already been sent.
      */
     "hook-muse-contributor-model",
+    /**
+     * A Hermes Agent `execute_code` call, refused before anything else looks at
+     * it (APRV-398).
+     *
+     * The tool takes a `code` string and runs it in-process. There is no path, no
+     * argv and no working directory: nothing the classifier reads exists in the
+     * call, so no class can be resolved and no payload can bind what will happen.
+     * A verdict over `{code}` would authorize a program this runtime never
+     * parsed, which is the same hole `hook-opaque` closes for `bash -c` and the
+     * same one `hook-unsupported-execution-context` closes for a command whose
+     * directory is invisible. SPEC.md §11.1 says ambiguity resolves to the
+     * stricter path, and the strictest honest answer to "may I run this arbitrary
+     * program" is no.
+     *
+     * Distinct from `hook-opaque`, and the distinction is the repair. That one
+     * says a command line carried a construct the classifier could not read, and
+     * the fix is to write the command differently. This one says the TOOL has no
+     * readable surface at all on this harness, so there is no spelling of an
+     * `execute_code` call that would be answered differently: the repair is to do
+     * the work through the shell tool, where the words are visible and the
+     * classifier can price them, or through `approval run` with a granted token.
+     *
+     * Distinct from `hook-unclassified`, which says the classifier had nothing to
+     * say about bytes it could see. Here there are no bytes to see.
+     */
+    "hook-hermes-execute-code-unbound",
     /** Malformed hook input, or a log/filesystem fact that stopped the check. */
     "hook-io",
 ];
@@ -356,6 +428,22 @@ export function hookScope(flags, cwd) {
 function policyRootOf(load, fallback) {
     return load.ok ? dirname(load.source.path) : fallback;
 }
+/**
+ * The ceiling a harness puts on its hook process, in milliseconds, or `null`
+ * (APRV-423): the operator's stated `--harness-cap` clamped to the adapter's
+ * contractual maximum, or, with nothing stated, the adapter's documented
+ * default, falling back to that maximum.
+ *
+ * Exported so `approval serve` computes the same number the hook will before
+ * it hands the call to a thread (APRV-427 review): the budget a queued call
+ * has left is this less the time it has waited.
+ */
+export function effectiveHarnessCapMs(adapter, statedCapMs) {
+    const ceilingMs = adapter.capCeilingMs ?? null;
+    if (statedCapMs === null)
+        return adapter.capDefaultMs ?? ceilingMs;
+    return ceilingMs === null ? statedCapMs : Math.min(statedCapMs, ceilingMs);
+}
 const CLAUDE_ADAPTER = {
     kind: "claude-code",
     originApp: "claude-code-hook",
@@ -491,6 +579,239 @@ const MUSE_ADAPTER = {
     shellCwdKey: "workdir",
     contributorModelGuard: true,
 };
+/**
+ * Hermes Agent's event names, which are its own and not Claude Code's
+ * (APRV-398).
+ *
+ * snake_case, and the VERBS differ too: `pre_tool_call` where every other
+ * harness in this table says `PreToolUse`. That is why they are constants
+ * rather than two more entries in {@link POST_TOOL_EVENTS} — a harness whose
+ * post-event name appeared in that shared list would also accept
+ * `PostToolUse` from an event nobody sent, and the dispatch would answer a
+ * name this harness never uses.
+ */
+export const HERMES_PRE_TOOL_EVENT = "pre_tool_call";
+export const HERMES_POST_TOOL_EVENT = "post_tool_call";
+/**
+ * Hermes Agent's read tools, read off its own tool registrations (APRV-398).
+ *
+ * `read_file` names one `path` (with `offset` and `limit`). `search_files` is
+ * BOTH of the readers another harness would ship as two: its `target` enum
+ * selects `content` (a grep) or `files` (a name search), and either way the
+ * directory it works in is one `path`. So there is no `glob`, no `grep` and no
+ * `list_files` here — not because they were left out, but because this harness
+ * does not have them.
+ *
+ * NO TOOL ON THIS HARNESS TAKES A LIST OF PATHS, which is the one thing worth
+ * saying out loud: Muse's `search` names an ARRAY under `paths` and needed
+ * `firstOutOfScope` to answer a list, and `readToolGate`'s single-path arm
+ * answers everything here. A `paths` array arriving from a future release would
+ * fall to that same list handling with no change, because the gate reads both.
+ *
+ * OBSERVED (APRV-415, the live probe of APRV-398): a running session sent
+ * `read_file` with `path` and `limit`, and the tools it sent in total were
+ * `terminal`, `write_file`, `patch`, `read_file` and `execute_code`.
+ * `search_files` was not exercised by the five prompts, so it stays on this list
+ * as the registration says, in the direction APRV-347 made safe: a listed tool
+ * Hermes never sends is INERT, an unlisted tool it does send would be an
+ * unscoped read. A read arriving through `terminal` as `cat` is scoped by the
+ * classifier regardless, which is the floor under all of it.
+ */
+const HERMES_READ_TOOLS = ["read_file", "search_files"];
+/**
+ * The classes Hermes's own side-effecting tools are judged under (APRV-445,
+ * from the Agent Village DATA-234 survey of Hermes v2026.9.24).
+ *
+ * Before this table every one of these reached the not-a-gated-tool allow,
+ * because the adapter knew `terminal`, `write_file`, `patch` and the two read
+ * tools and nothing else, so a policy line for `cron.manage` or `message.send`
+ * was a line no Hermes call could ever reach. They are code, not policy: the
+ * classifier decides what a call IS and the policy decides what happens to it,
+ * so an operator prices these classes with ordinary `classes:` lines.
+ *
+ * - `cronjob_manage` (legacy alias `cronjob`): every action that changes the
+ *   schedule or runs a job is `cron.manage`; `list` is a read. A scheduled job
+ *   runs later with no `pre_tool_call` at all, so the schedule is the one place
+ *   a human can see it.
+ * - `process_manage` (legacy alias `process`): `write`, `submit`, `kill`,
+ *   `close` and `handoff` act on a running process and are `process.write`;
+ *   `list`, `poll`, `log` and `wait` are reads.
+ * - `browser_exec`, `browser_cdp` and every other `browser_*`: `browser.exec`.
+ * - `skill_manage`: `skill.manage`. `delegate_task`: `agent.delegate`.
+ *   `send_message`: `message.send` (not agent-callable at v2026.9.24; the rule
+ *   stands so the day it is, it is already gated).
+ *
+ * An action this table does not recognise on a tool it does know is judged
+ * under the tool's side-effecting class rather than allowed: a new verb on a
+ * tool that schedules or drives processes is a new way to do that, and the
+ * strict reading is the safe one.
+ */
+const HERMES_CRON_READ_ACTIONS = new Set(["list"]);
+const HERMES_PROCESS_READ_ACTIONS = new Set(["list", "poll", "log", "wait"]);
+function hermesToolRule(toolName, toolInput) {
+    const action = readString(toolInput, "action");
+    const headline = (cls) => `${toolName}${action === null ? "" : ` ${action}`} (${cls})`;
+    if (toolName === "cronjob_manage" || toolName === "cronjob") {
+        if (action !== null && HERMES_CRON_READ_ACTIONS.has(action)) {
+            return { kind: "read", reason: `${toolName} ${action} reads the schedule and changes nothing` };
+        }
+        return { kind: "gated", cls: "cron.manage", headline: headline("cron.manage") };
+    }
+    if (toolName === "process_manage" || toolName === "process") {
+        if (action !== null && HERMES_PROCESS_READ_ACTIONS.has(action)) {
+            return { kind: "read", reason: `${toolName} ${action} reads a process and changes nothing` };
+        }
+        return { kind: "gated", cls: "process.write", headline: headline("process.write") };
+    }
+    if (toolName.startsWith("browser_")) {
+        return { kind: "gated", cls: "browser.exec", headline: headline("browser.exec") };
+    }
+    if (toolName === "skill_manage") {
+        return { kind: "gated", cls: "skill.manage", headline: headline("skill.manage") };
+    }
+    if (toolName === "delegate_task") {
+        return { kind: "gated", cls: "agent.delegate", headline: headline("agent.delegate") };
+    }
+    if (toolName === "send_message") {
+        return { kind: "gated", cls: "message.send", headline: headline("message.send") };
+    }
+    return null;
+}
+/**
+ * Hermes Agent by Nous Research (APRV-398).
+ *
+ * The harness Agent Village v2 runs every resident agent on, one per tenant in
+ * a Railway sandbox, which is why this adapter exists at all. Its hook is a
+ * shell hook like every other entry in this table, configured under `hooks:` in
+ * `$HERMES_HOME/config.yaml` rather than in the repository: Hermes documents no
+ * project-local configuration directory, so the organ lives in the user home
+ * and `core/command-class.ts` matches it there.
+ *
+ * ## The dialect: exactly one form, and the form is Hermes's own
+ *
+ * Hermes's shell-hook parser accepts two block dialects, checked in this order:
+ * its own `{action:"block", message}` and a Claude-compatible
+ * `{decision:"block", reason}`. This adapter emits the NATIVE one and never
+ * both.
+ *
+ * The live probe (APRV-415) measured every dialect one at a time and then all of
+ * them at once: `{action:"block"}` at exit 2, `{action:"block"}` at exit 0,
+ * `{decision:"block"}`, a bare exit 2, and the mixed payload ALL BLOCKED. So
+ * HERMES TOLERATES A SUPERSET, which is exactly where it differs from Muse — a
+ * payload carrying several dialects there was unparseable, an unparseable hook
+ * was a failed hook, and a failed hook failed OPEN, so being more explicit made
+ * the refusal weaker (`docs/muse-hook.md`). One dialect is still what this
+ * adapter emits, and the reason is now the smaller one rather than the load-
+ * bearing one: the native form is the shape the parser tries first and the one
+ * least likely to be dropped by a release that tidies up a compatibility layer,
+ * and a verdict whose meaning does not depend on how much of it the harness
+ * understood is a verdict a reader can check. The tolerance is a fact about this
+ * release, not a licence to hedge in the next one.
+ *
+ * THE ALLOW IS `{}`, and that is not a placeholder. Hermes has no
+ * `{"action":"allow"}`: its parser returns "no directive" for an empty stdout,
+ * for `{}`, and for any JSON object naming no directive key, and no directive
+ * means the call proceeds. The probe confirmed it: the `allow-empty-object`
+ * trial CREATED its file under `fail_closed: true`. `{}` is chosen over an empty
+ * stdout because the two are distinguishable to a human reading a log and only
+ * one of them says a hook ran and decided; it is chosen over an invented
+ * `{"action":"allow"}` because that spelling is an allow only by falling through
+ * the parser's unrecognised-directive path — which the probe also measured, and
+ * which did fall through on the old build — and a verdict that works by not being
+ * understood is a verdict one release could turn into a block. The reason text
+ * rides on stderr, where Hermes reads it only as a block message at the blocking
+ * exit code, which an allow never uses.
+ *
+ * ## The first real gate since Claude Code, measured
+ *
+ * A per-entry `fail_closed: true` turns three hook failures into a BLOCK: a
+ * spawn error, a timeout, and stdout that is non-empty and not a JSON object.
+ * Grok Build and Muse Code both fail open on all three with no setting to change
+ * it, so both adapters are enforcement only while healthy.
+ *
+ * OBSERVED, 3 OF 3, on Hermes `main` at `118984d7` (APRV-415): the armed crash
+ * was refused, the armed garbage was refused, and the armed hang was refused at
+ * exactly 300s, the per-entry cap. So this adapter is a gate on a current Hermes
+ * rather than a backstop, which no adapter since Claude Code could say.
+ *
+ * THREE LIMITS RIDE WITH IT, and `docs/hermes-hook.md` states all three rather
+ * than selling the headline. The default is `false`, so an entry without the key
+ * fails open. The key does not cover a hook that exits non-zero having printed
+ * NOTHING, which is left to {@link HERMES_DENY_EXIT}'s unconditional block. And
+ * there is a VERSION FLOOR: `v0.21.3` (build `2026.9.14`) does not know the key
+ * at all and ignores it silently, with `hermes hooks list` rendering no
+ * `fail_closed` flag on either build, so the listing cannot be used to check it.
+ * {@link HERMES_FAIL_CLOSED_FLOOR} in `core/harness-version.ts` carries the floor
+ * and `approval doctor`'s harness-version row reports a build below it.
+ *
+ * ## `execute_code` has no readable surface, and may not even be hooked
+ *
+ * The tool takes a `code` string and no path, no argv and no directory, so
+ * nothing a verdict could bind exists in the call. It is refused before the
+ * event dispatch with {@link HERMES_EXECUTE_CODE_REFUSAL}.
+ *
+ * There is a second reason, and it is the stronger one. `execute_code` runs in
+ * a persistent kernel whose scripts can call Hermes's other tools IN-PROCESS.
+ * Whether those inner calls re-fire `pre_tool_call` is STILL not established and
+ * cannot be established from here: the probe refused every `execute_code` call
+ * before it ran, twice, which is the refusal working and is also the reason no
+ * inner call was ever observed. If they do not re-fire, one `execute_code` call
+ * is an unbounded bypass of this entire adapter. Refusing the tool is the only
+ * answer available to a hook that cannot see inside it, and it is the
+ * fail-closed one.
+ */
+const HERMES_ADAPTER = {
+    kind: "hermes",
+    originApp: "hermes-hook",
+    defaultActor: "agent:hermes",
+    // Two numbers, because Hermes bounds the hook twice and the shorter wins.
+    //
+    // The CEILING is 300 s, OBSERVED rather than read off a page: APRV-415's probe
+    // armed a hang and Hermes refused it at exactly 300 s, the per-entry cap. No
+    // entry can outlive it however it is written, so a stated `--harness-cap` is
+    // clamped to it.
+    //
+    // The DEFAULT is 30 s: `plugins.hook_callback_timeout`, which bounds the whole
+    // hook dispatch, fails closed on `pre_tool_call` by itself, and is what a
+    // Hermes install runs with until an operator raises it. The first pass of
+    // APRV-423 assumed the 300 s ceiling whenever the flag was absent, which on a
+    // default install asserted a T+240 s deadline for a hook Hermes kills at 30 s:
+    // APRV-410 again, with a fictional deadline. So with no flag the runtime
+    // assumes the stricter number, which does not clear the margin, and refuses
+    // `hook-harness-cap-too-short` with the repair below. An operator who has
+    // raised `hook_callback_timeout` states the smaller of it and the entry's
+    // `timeout` with `--harness-cap`, and that statement replaces the default.
+    capCeilingMs: 300_000,
+    capDefaultMs: 30_000,
+    capRepair: "On Hermes: raise `plugins.hook_callback_timeout` above the per-entry `timeout` in the harness's config, then pass `--harness-cap <the smaller of the two>` on the hook command, or start `approval serve` with `--hook-harness-cap <the smaller of the two>` for a hosted tenant (for the documented `hook_callback_timeout: 600` with `timeout: 300`, that is 300s). Without the flag this runtime assumes Hermes's 30s default callback timeout, which leaves no room for a human.",
+    // `terminal`, carrying `command` and a PER-CALL `workdir`. Hermes's contract
+    // has the field Codex's withholds (APRV-310), and the live probe found that
+    // having it is not the same as being sent it: the model passed no `workdir` at
+    // all, and the directory the command would have run in is reported nowhere
+    // else. So the field makes enforcement POSSIBLE and
+    // {@link hermesUnboundDirectory} is what makes it actual, by refusing the call
+    // that leaves the field out instead of guessing a directory for it.
+    shellTool: "terminal",
+    // `write_file` names `path` and `content`; `patch` names `path`,
+    // `old_string` and `new_string`. Both shapes are already what
+    // `fileToolGate` reads, so neither needed a new key. Both were observed on the
+    // live run, `patch` with `new_string`, `old_string` and `path` exactly.
+    fileTools: ["write_file", "patch"],
+    readTools: HERMES_READ_TOOLS,
+    shellCwdKey: "workdir",
+    toolRules: hermesToolRule,
+};
+/** The adapter's rule-table verdict for this call, or `null` (APRV-445). */
+function toolRuleOf(adapter, input) {
+    if (adapter.toolRules === undefined)
+        return null;
+    if (input.toolName === adapter.shellTool)
+        return null;
+    if (adapter.fileTools.includes(input.toolName) || adapter.readTools.includes(input.toolName)) {
+        return null;
+    }
+    return adapter.toolRules(input.toolName, input.toolInput);
+}
 /**
  * Every harness this runtime speaks a hook protocol for, by kind (APRV-358).
  *
@@ -514,7 +835,26 @@ export const HARNESS_ADAPTERS = {
     codex: CODEX_ADAPTER,
     grok: GROK_ADAPTER,
     muse: MUSE_ADAPTER,
+    hermes: HERMES_ADAPTER,
 };
+/**
+ * Is `name` this adapter's post-execution event?
+ *
+ * One reading of the question, so the three places that used to spell it
+ * themselves cannot come apart (APRV-398). Codex names one event, Hermes names
+ * its own snake_case pair, and everything else uses Claude Code's two; a
+ * harness whose names appeared in another harness's list would answer an event
+ * nobody sent it.
+ */
+function isPostToolEvent(adapter, name) {
+    if (name === null)
+        return false;
+    if (adapter.kind === "codex")
+        return name === CODEX_POST_TOOL_EVENT;
+    if (adapter.kind === "hermes")
+        return name === HERMES_POST_TOOL_EVENT;
+    return POST_TOOL_EVENTS.includes(name);
+}
 /**
  * The decision object the harness reads from stdout.
  *
@@ -533,6 +873,33 @@ function decision(permission, reason, harness, codexCommand) {
     if (harness === "grok") {
         return `${JSON.stringify({ decision: permission, reason })}\n`;
     }
+    if (harness === "hermes") {
+        // APRV-398. Hermes's OWN block form and exactly one form:
+        // `{action:"block", message}`. It emits neither the Claude-compatible
+        // `{decision:"block", reason}` beside it nor any other key, and the test
+        // asserts the top-level keys precisely so a later edit cannot quietly add
+        // one — on Muse a verdict carrying an unsupported key was a FAILED hook and
+        // a failed hook failed open, which made the more explicit refusal the weaker
+        // one. APRV-415 measured Hermes on the same question and it is NOT Muse: the
+        // mixed payload blocked, so this harness tolerates a superset. One dialect is
+        // kept anyway, because the tolerance is a property of one release and a
+        // verdict whose meaning depends on how much of it the harness parsed is not a
+        // verdict a reader can check.
+        //
+        // THE ALLOW IS `{}` AND CARRIES NO REASON, which is the harness's own
+        // vocabulary rather than a shrug: Hermes has no allow directive, and a
+        // parser that finds no directive lets the call proceed. `{}` over an empty
+        // stdout because a human reading a log can tell a hook that decided from a
+        // hook that printed nothing; `{}` over an invented `{"action":"allow"}`
+        // because that would be an allow only by falling through the parser's
+        // unrecognised path, and a verdict that works by not being understood is one
+        // release away from being a block. The reason reaches stderr instead (see
+        // {@link allow}), where it is read as a block message at the blocking exit
+        // code and nowhere else.
+        return permission === "deny"
+            ? `${JSON.stringify({ action: "block", message: reason })}\n`
+            : "{}\n";
+    }
     const hookSpecificOutput = {
         hookEventName: "PreToolUse",
         permissionDecision: permission,
@@ -548,6 +915,14 @@ function allow(streams, reason, harness, codexCommand) {
     if (harness === "codex" && codexCommand === undefined) {
         return deny(streams, "hook-io", "the Codex allow lost its exact bound tool_input.command", harness);
     }
+    // APRV-398. Hermes's allow is `{}` and has nowhere to put a reason, so the
+    // reason goes to stderr rather than being dropped: it names the classes the
+    // verdict authorized and carries the loop floor's own words when one stood,
+    // which is the line an operator reads back off a session. Hermes reads stderr
+    // only as a block message at the blocking exit code, and an allow never uses
+    // that exit code, so this cannot become part of a verdict.
+    if (harness === "hermes")
+        streams.err(`approval hook hermes: allow — ${reason}\n`);
     streams.out(decision("allow", reason, harness, codexCommand));
     return EXIT_OK;
 }
@@ -561,9 +936,230 @@ function allow(streams, reason, harness, codexCommand) {
  * of its documented contract and leaves the reason where a person can read it.
  */
 const GROK_DENY_EXIT = 2;
+/**
+ * The exit code a HERMES deny carries, and why it IS 2 (APRV-398).
+ *
+ * This is the one place the Muse reasoning does not carry over, and the
+ * difference is in Hermes's own code rather than in a preference. Hermes defines
+ * a blocking exit code, applies it to `pre_tool_call` and to no other event, and
+ * treats it as UNCONDITIONAL: the call is blocked whatever stdout said, and the
+ * block message is taken from the stdout directive first, from stderr second,
+ * and from a default third. So the body and the exit code are not two accounts
+ * of one answer that the harness has to reconcile — the harness states the
+ * precedence itself, and the two agree by its own rule.
+ *
+ * That makes 2 strictly stronger than 0 here, and it closes the one gap
+ * `fail_closed` leaves open. `fail_closed: true` blocks on a spawn error, a
+ * timeout, and stdout that is non-empty and not a JSON object; it does NOT block
+ * a hook that exits non-zero having printed nothing, because its condition
+ * requires a non-empty stdout. Exiting 2 means every refusal this adapter
+ * reaches blocks on the exit code alone, including the ones where the body never
+ * made it out.
+ *
+ * Grok's 2 and this 2 are therefore the same number for opposite reasons, and it
+ * is worth not conflating them: there, exit 2 is the ONLY signal Grok reads and
+ * the body is decoration. Here the body is the message and the exit code is the
+ * floor under it.
+ */
+const HERMES_DENY_EXIT = 2;
 function deny(streams, code, detail, harness) {
     streams.out(decision("deny", `${code}: ${detail}`, harness));
-    return harness === "grok" ? GROK_DENY_EXIT : EXIT_OK;
+    if (harness === "grok")
+        return GROK_DENY_EXIT;
+    if (harness === "hermes")
+        return HERMES_DENY_EXIT;
+    return EXIT_OK;
+}
+/**
+ * The block directive a harness reads, as bytes, for a refusal raised OUTSIDE
+ * the hook (APRV-421).
+ *
+ * `approval serve` can refuse a hook request before `commandHook` is reached
+ * at all: an oversized body, a credential at the wrong door, a method it does
+ * not answer. Each of those is a refusal by the transport, and a transport
+ * refusal a harness reads as "no verdict" is a harness that runs the command.
+ * So the refusal has to be spoken in the harness's own dialect, and the only
+ * correct source of that dialect is the function that prints it here.
+ *
+ * It renders through {@link deny} for that reason: one construction site per
+ * harness, still never `ask`. The exit code returned is the one the verb would
+ * have carried; a caller may impose a stricter one, and the transport does.
+ */
+export function harnessBlockDirective(code, detail, harness) {
+    const out = [];
+    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. */
+const HERMES_EXECUTE_CODE_TOOL = "execute_code";
+/**
+ * The retry a Hermes session makes after one of these refusals, in one place.
+ *
+ * It is the whole point of refusing rather than falling back: a session that is
+ * told what to send next stays usable, and the live probe watched the model
+ * answer a block by trying the SAME effect through another tool and another
+ * directory. A refusal that did not name the repair would get that behaviour
+ * again, one tool along.
+ */
+const HERMES_ABSOLUTE_RETRY = "spell the directory in full from `/` and send the call again; the classifier then reads the same path the harness will write";
+/**
+ * A Hermes call whose effective directory this hook cannot see, as the reason it
+ * is refused, or `null` when the call binds its own directory (APRV-415).
+ *
+ * ## The fact, observed rather than reasoned
+ *
+ * The live probe of APRV-398 (Hermes `main` at `118984d7`, 60 envelopes) settled
+ * three things that together make this refusal necessary:
+ *
+ * 1. the envelope's `cwd` is the Hermes PROCESS directory (`Path.cwd()` in its
+ *    payload builder), which is not where the work happens. A session launched in
+ *    the scratch project wrote into `$HERMES_HOME/cache/scratch`, and a Telegram
+ *    gateway session's `cwd` was the USER HOME;
+ * 2. `terminal` keeps a PER-SESSION recorded working directory that a `cd` in an
+ *    earlier call moves, and no field of the event reports it. The model passed
+ *    no `workdir` at all on the probe's shell call;
+ * 3. all four file tools resolve a RELATIVE path against that same unreported
+ *    directory (`tools/file_tools_paths.py`, `_resolve_path_for_task`).
+ *
+ * So a call that does not state an absolute directory is the APRV-310 shape
+ * across every tool on this harness: the verdict would bind bytes in one
+ * directory and the harness would act in another. That is not a narrower answer
+ * this runtime may reach by guessing, and `describeToolCall`'s fallback to the
+ * event `cwd` — correct on Muse, where `cwd` IS the session root — would bind a
+ * directory that does not even contain the work here.
+ *
+ * ## Why a refusal rather than a fallback, and why it is usable
+ *
+ * SPEC.md §11.1: ambiguity resolves to the stricter path, and a self-reported
+ * field never reduces scrutiny. A relative `workdir` cannot widen anything, and
+ * on this harness it cannot be narrowed into either, because there is no
+ * trustworthy directory to fall back TO. The refusal carries
+ * `hook-unsupported-execution-context`, the same code the Codex `Bash` refusal
+ * carries, because it is the same defect — the harness did not say WHERE — and
+ * the repair differs only in being available: a Hermes session repairs it
+ * itself, in the next call, by naming an absolute path. That is why the reason
+ * names the retry rather than describing the contract.
+ *
+ * The probe also watched what a blocked model does next: it retries the same
+ * effect through another tool or another path. Refusing the shell tool alone
+ * would have moved the work into `write_file`, which is exactly why every gated
+ * tool is covered here and why an ABSENT path is refused beside a relative one.
+ * A missing `path` on this harness does not mean "the workspace" the way Claude
+ * Code's `Glob` does; it means that same unreported recorded directory.
+ */
+function hermesUnboundDirectory(input, adapter) {
+    const tool = input.toolName;
+    if (tool === adapter.shellTool) {
+        const key = adapter.shellCwdKey ?? "workdir";
+        const declared = readString(input.toolInput, key);
+        if (declared !== null && isAbsolute(declared))
+            return null;
+        return `Hermes \`${tool}\` is refused because the call ${declared === null
+            ? `states no \`${key}\``
+            : `states a relative \`${key}\` (${JSON.stringify(declared)})`}, and this harness reports the effective directory nowhere else: its \`cwd\` is the Hermes process directory, while the command runs in a per-session directory that an earlier \`cd\` moves and no field of this event carries. A verdict over the command alone would bind bytes in a directory the hook cannot see. Set \`${key}\` to an absolute path — ${HERMES_ABSOLUTE_RETRY}. No policy or open window authorizes bytes whose directory the hook cannot bind`;
+    }
+    if (!adapter.fileTools.includes(tool) && !adapter.readTools.includes(tool))
+        return null;
+    // The same keys `fileToolGate` and `readToolGate` read, in their order, plus
+    // the `paths` array neither Hermes tool sends today: a later release that
+    // added one would otherwise arrive as an unbound call that reads as bound.
+    const declared = readString(input.toolInput, "path") ??
+        readString(input.toolInput, "file_path") ??
+        readString(input.toolInput, "notebook_path");
+    const list = input.toolInput["paths"];
+    const entries = Array.isArray(list)
+        ? list.filter((entry) => typeof entry === "string" && entry.trim() !== "")
+        : [];
+    const candidates = declared === null ? entries : [declared, ...entries];
+    if (candidates.length === 0) {
+        return `Hermes \`${tool}\` is refused because the call names no path at all. On this harness an unnamed target is not the workspace: it is the per-session recorded directory that an earlier \`cd\` moves and that no field of this event carries, and a live session's was \`$HERMES_HOME/cache/scratch\` while a gateway session's was the user's home. Name the directory or file with an absolute \`path\` — ${HERMES_ABSOLUTE_RETRY}`;
+    }
+    const relative = candidates.find((candidate) => !isAbsolute(candidate));
+    if (relative === undefined)
+        return null;
+    return `Hermes \`${tool}\` is refused because the path it names is relative (${JSON.stringify(relative)}), and Hermes resolves a relative path against the per-session recorded directory that an earlier \`cd\` moves, which this event does not carry: its \`cwd\` is the Hermes process directory. The verdict and the write would name different files. Send the same call with an absolute path — ${HERMES_ABSOLUTE_RETRY}. No policy or open window authorizes a path the hook cannot place`;
 }
 /** The machine-readable code a Contributor-tier session is refused with. */
 export const MUSE_CONTRIBUTOR_REFUSAL = "hook-muse-contributor-model";
@@ -1276,13 +1872,228 @@ export function refineReadScope(result, roots, cwd) {
     }
     return { result: { ok: true, segments, classes }, notes };
 }
+// ===========================================================================
+// Write scope, the disk half (APRV-402)
+// ===========================================================================
+/**
+ * ## Why writes need a second pass too
+ *
+ * Deletes and reads each had one and writes did not, which left the oldest of
+ * the three rules the loosest. `files.write.workspace` was decided on the text
+ * alone: a relative destination is the workspace, said the classifier, and a
+ * relative destination is the workspace only while nothing on the way to it is
+ * a symlink out. `cp x build/y`, `tee build/y`, `mkdir build/y`, and since
+ * APRV-397 `tar -x -C build` and `npm pack --pack-destination build`, were all
+ * autonomous with `build` pointing anywhere at all.
+ *
+ * Not a regression and not new with the packaging rows (APRV-402): the hole is
+ * as old as the workspace-write row, and before APRV-397 every packaging
+ * command was denied as unclassified, so nothing that was refused became
+ * allowed by a symlink. What changed is that the rows now say `workspace` often
+ * enough for the gap to be worth the disk.
+ *
+ * ## The shape is the other two passes' shape
+ *
+ * Resolve the nearest EXISTING ancestor of each destination, re-append the
+ * unresolved tail, and TIGHTEN when the result is outside every root. It can
+ * only ever move a segment toward the stricter class, so a caller that skipped
+ * it is no more permissive than one that runs it, which is what lets
+ * `hook classify` and `hook <harness>` share it without either becoming the
+ * authority.
+ *
+ * ## What it costs, measured before it was written (APRV-402 AC1)
+ *
+ * The walk is 0.10 ms to 0.13 ms per destination on a warm cache (0.07 ms for
+ * an absolute one), over 20k iterations of each shape. A write segment names
+ * one or two destinations, so a write command pays about a fifth of a
+ * millisecond. APRV-209 measured a cold gated invocation at about 371 ms, of
+ * which 116 ms is the module graph and 51 ms is `hook.js` alone; this is under
+ * half a percent of that last term and it is paid only by segments the
+ * classifier already called a workspace write. The delete and read passes pay
+ * the same price per target and have since APRV-267 and APRV-347.
+ */
+/** The class an out-of-scope write tightens to, as `core/command-class.ts` spells it. */
+const OUT_OF_SCOPE_WRITE_CLASS = "files.delete.out_of_scope";
+/** The rule a write tightened by this pass reports. */
+const WRITE_SCOPE_REJECTED_RULE = "write-out-of-scope-resolved";
+/** The class this pass re-reads, and the only one it will touch. */
+const WORKSPACE_WRITE = "files.write.workspace";
+/**
+ * The classifier rules whose destinations this pass re-reads.
+ *
+ * Exactly the rows APRV-402 names: the workspace-write row (`mkdir`, `cp`,
+ * `mv`, `touch`, `tee`, `ln`, `chmod`, `truncate`, `rmdir`) and the six
+ * packaging answers APRV-397 added. `rm-workspace` and `redirect-write` reach
+ * the same class by the same text-only reasoning and are deliberately NOT here:
+ * they are the same hole in two more rules and they are their own decision, not
+ * one to take inside this task's diff.
+ */
+const WRITE_SCOPE_RULES = [
+    "workspace-write",
+    "tar-extract",
+    "tar-create",
+    "gunzip-write",
+    "base64-write",
+    "openssl-digest-out",
+    "npm-pack",
+];
+/**
+ * The roots a write may land in, resolved.
+ *
+ * The scratch roots are the ones `resolveScratchRoots` already computes and
+ * already guards, so this rule and the delete rule cannot disagree about where
+ * the agent's own scratch is. The working directory is the other one, and it is
+ * the root the classifier's own text rule already implies: "a relative
+ * destination is the workspace" means the workspace is wherever the command
+ * runs.
+ *
+ * `cwd` is harness-supplied, and reading a root out of it does not offend
+ * SPEC.md §11.1 invariant 4, because this pass only ever narrows. The baseline
+ * it narrows from is no check at all, so a poisoned `cwd` buys back exactly
+ * today's answer and never a looser one. Compare the read pass, which checks
+ * containment against the GATE root: that pass decides whether a read is in
+ * scope at all, so the scope has to be one the subject cannot choose. This one
+ * only takes an allowance away.
+ */
+export function resolveWriteRoots(cwd) {
+    const roots = resolveScratchRoots(cwd);
+    const here = resolvedPath(cwd);
+    if (here !== null && !roots.includes(here))
+        roots.unshift(here);
+    return roots;
+}
 /**
- * The classifier, its context, and all three impure refinements, in the one
+ * Where this destination really is, or `null` when nothing can say.
+ *
+ * The same walk `targetStaysInScratch` and `resolvedReadTarget` do, for the
+ * same reason: the destination usually does NOT exist yet, so the nearest
+ * existing ancestor is resolved and the unresolved tail re-appended. A symlink
+ * anywhere in that chain therefore cannot smuggle a write out of the roots,
+ * which is the escape the pure half cannot see.
+ */
+function resolvedWriteTarget(target, cwd) {
+    let existing = isAbsolute(target) ? target : resolvePathSegments(cwd, target);
+    const tail = [];
+    for (let depth = 0; depth < 64; depth += 1) {
+        if (existsSync(existing))
+            break;
+        const up = dirname(existing);
+        if (up === existing)
+            return null;
+        tail.unshift(basename(existing));
+        existing = up;
+    }
+    const resolved = resolvedPath(existing);
+    if (resolved === null)
+        return null;
+    return tail.length === 0 ? resolved : join(resolved, ...tail);
+}
+/**
+ * The words of a write segment that could name a path on disk.
+ *
+ * Every argument that is not spelled as a flag, plus the value half of
+ * `--opt=value`. This is the delete pass's own filter, and it is deliberately
+ * coarser than the classifier's flag table: it reaches `-C dir`, `-o file` and
+ * `--pack-destination dir` without this file holding a second copy of that
+ * table to drift against. It over-includes (a `tar` archive being READ is a
+ * candidate too, and so is `chmod`'s mode), and over-including can only tighten
+ * a segment that would otherwise have been waved through.
+ *
+ * A bare `-` is not a path: it is stdin or stdout, and every binary in these
+ * rows that accepts it means the stream.
+ */
+function writeCandidates(args) {
+    const candidates = [];
+    for (const arg of args) {
+        if (arg === "-")
+            continue;
+        if (!arg.startsWith("-")) {
+            candidates.push(arg);
+            continue;
+        }
+        const equals = arg.indexOf("=");
+        if (equals === -1)
+            continue;
+        const value = arg.slice(equals + 1);
+        if (value.length > 0)
+            candidates.push(value);
+    }
+    return candidates;
+}
+/**
+ * Tighten a `files.write.workspace` segment to the out-of-scope write class
+ * wherever the disk disagrees with the text.
+ *
+ * IMPURE by design and by contract, exactly as the other two passes are. The
+ * class it tightens to is the one `core/command-class.ts` already answers for
+ * an out-of-scope packaging destination rather than a new name: a class no
+ * policy mentions resolves by `defaults.autonomy` (SPEC.md §7), so minting
+ * `files.write.out_of_scope` here would arrive AUTONOMOUS in every deployment
+ * with permissive defaults, which is the one way a tightening pass could
+ * loosen something.
+ *
+ * `roots` empty means the caller asked for no write scoping, and every segment
+ * comes back untouched: the same "absent yields today's answer" the read pass
+ * promises.
+ */
+export function refineWriteScope(result, roots, cwd) {
+    if (!result.ok)
+        return { result, notes: [] };
+    if (roots.length === 0)
+        return { result, notes: [] };
+    if (!result.segments.some((segment) => segment.class === WORKSPACE_WRITE && WRITE_SCOPE_RULES.includes(segment.rule))) {
+        return { result, notes: [] };
+    }
+    const notes = [];
+    const segments = result.segments.map((segment) => {
+        if (segment.class !== WORKSPACE_WRITE)
+            return segment;
+        if (!WRITE_SCOPE_RULES.includes(segment.rule))
+            return segment;
+        const words = commandSegmentWords(segment.text);
+        const parsed = words === null ? undefined : words[0];
+        // The classifier read this segment a moment ago, so a parse that disagrees
+        // here is two reads of the same bytes disagreeing. Fail closed.
+        if (parsed === undefined) {
+            notes.push(`${WRITE_SCOPE_REJECTED_RULE}: \`${segment.text}\` could not be re-read, so it is ${OUT_OF_SCOPE_WRITE_CLASS}`);
+            return { ...segment, class: OUT_OF_SCOPE_WRITE_CLASS, rule: WRITE_SCOPE_REJECTED_RULE };
+        }
+        const reject = (path, detail) => {
+            notes.push(`${WRITE_SCOPE_REJECTED_RULE}: ${detail}`);
+            return {
+                ...segment,
+                class: OUT_OF_SCOPE_WRITE_CLASS,
+                rule: WRITE_SCOPE_REJECTED_RULE,
+                path,
+            };
+        };
+        for (const candidate of writeCandidates(parsed.args)) {
+            const resolved = resolvedWriteTarget(candidate, cwd);
+            if (resolved === null) {
+                return reject(candidate, `${candidate} does not resolve to any path this hook can see, so \`${segment.text}\` is ${OUT_OF_SCOPE_WRITE_CLASS}`);
+            }
+            if (!roots.some((root) => resolved === root || isBelow(resolved, root))) {
+                return reject(resolved, `${candidate} resolves to ${resolved}, which is outside the workspace and every scratch root (${roots.join(", ")}), so \`${segment.text}\` is ${OUT_OF_SCOPE_WRITE_CLASS}`);
+            }
+        }
+        return segment;
+    });
+    if (notes.length === 0)
+        return { result, notes };
+    const classes = [];
+    for (const segment of segments) {
+        if (!classes.includes(segment.class))
+            classes.push(segment.class);
+    }
+    return { result: { ok: true, segments, classes }, notes };
+}
+/**
+ * The classifier, its context, and all four impure refinements, in the one
  * order every caller must use.
  *
  * `hook classify` printing a different class from the one `hook claude-code`
  * decides would make the explainer a different program (APRV-108's note), and
- * that stays true now there are three refinements in the chain.
+ * that stays true now there are four refinements in the chain.
  *
  * `readRoots` is the one argument whose ABSENCE is the loose answer rather than
  * the strict one (APRV-347), so it is passed explicitly at every call site: an
@@ -1299,9 +2110,15 @@ export function classifyForHook(command, protectedPaths, cwd, readRoots = []) {
     const rewritten = refineRewrite(classified, cwd);
     const scratched = refineScratchDelete(rewritten.result, roots);
     const scoped = refineReadScope(scratched.result, readRoots, cwd);
+    // APRV-402. Its roots are not `readRoots`: a read scope is a read notion and
+    // must not become a write authorization, so this pass asks its own question
+    // of the working directory and the scratch roots. Last in the chain because
+    // it is the narrowest, and because nothing after it would re-read a segment
+    // it has already tightened.
+    const written = refineWriteScope(scoped.result, resolveWriteRoots(cwd), cwd);
     return {
-        result: scoped.result,
-        notes: [...rewritten.notes, ...scratched.notes, ...scoped.notes],
+        result: written.result,
+        notes: [...rewritten.notes, ...scratched.notes, ...scoped.notes, ...written.notes],
     };
 }
 // ===========================================================================
@@ -1376,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)}…`;
@@ -1780,6 +2808,33 @@ function readToolGate(toolName, toolInput, roots, cwd) {
         summary: `${toolName} ${file} (outside the read scope)`,
     };
 }
+/**
+ * A read tool call naming a credential file (APRV-445 refutation, B2): the
+ * Hermes home's `.env` and `auth.json`, and the approval home's vault, keys and
+ * environment map. `null` for anything else.
+ */
+function credentialReadGate(toolName, toolInput, cwd) {
+    const declared = readString(toolInput, "file_path") ??
+        readString(toolInput, "notebook_path") ??
+        readString(toolInput, "path");
+    if (declared === null)
+        return null;
+    // APRV-445 recheck SF2(e, f): judged through realpath, so a symlinked
+    // parent cannot launder the path, and a directory of credentials handed to a
+    // read tool (a search, a glob, a grep) is gated as the credentials are.
+    const file = canonicalPath(absolute(declared, cwd));
+    // Recheck 3 (SF1a): only a directory that holds credentials (a home root, an
+    // approval home, a home's `approval/`, or a directory under a home holding a
+    // credential file); `skills/`, `workspace/` and the like are ordinary.
+    if (!isCredentialPath(file) && !holdsCredentials(file))
+        return null;
+    const input = { ...toolInput };
+    delete input["description"];
+    return {
+        payload: { tool: toolName, rule: "credential", file, input },
+        summary: `${toolName} ${file} (credential)`,
+    };
+}
 /** The verdict note for a gated read: what was asked for, and against what. */
 function readScopeNote(gated, roots) {
     return `read-scope: ${gated.declared} resolves to ${gated.file}, which is outside the read scope (${renderReadRoots(roots)})`;
@@ -1911,6 +2966,12 @@ function abandonedRequests(run, records, now, keepHash) {
             continue;
         if (record.actor !== run.actor)
             continue;
+        // APRV-445. Under `approval serve` the hook and `propose` act as ONE actor,
+        // and a proposal's request is harness-executed too, so without this every
+        // proposal pending past the hook's wait plus grace (minutes) would be swept
+        // as abandoned by the next gated tool call, days before its TTL.
+        if (isProposalTask(record.task))
+            continue;
         const key = record.action_key;
         if (typeof key !== "string" || key.length === 0)
             continue;
@@ -1974,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
@@ -1983,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}` };
     }
@@ -2146,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}` };
     }
@@ -2185,7 +3267,7 @@ function recordUnattended(run, task, classes, hash) {
  * both serves the channels and consumes the taps. That is worth saying: on
  * 2026-09-05 taps piled up unconsumed while hooks waited out their windows.
  */
-function announceWait(streams, run, waiting) {
+function announceWait(streams, run, waiting, expiryOf) {
     const where = run.channels.length === 0
         ? "no channel (this policy configures none, so nothing is delivering the question)"
         : `channel ${run.channels.join(", ")}`;
@@ -2193,7 +3275,21 @@ function announceWait(streams, run, waiting) {
         const adopted = action.origin === "adopted"
             ? " The question was already open for these exact bytes, so this tool call adopts it rather than asking a second time."
             : "";
-        streams.err(`approval: ${action.actionKey} (${action.cls}) is waiting for a human on ${where}; a decision on the phone releases it, and this hook blocks for up to ${String(run.timeoutMs)}ms before denying with hook-timeout and leaving the request open for a ${minutesText(run.graceMs)} retry grace.${adopted}\n`);
+        const at = expiryOf.get(action.actionKey);
+        // Second review pass (F7): which of the two ends first decides the sentence.
+        // "Open for a 5m grace" beside "expires at T+240s" was two claims about one
+        // question that could not both hold; the shorter one is the one stated.
+        const holdsOpen = at !== undefined && windowEndsBeforeGrace(run)
+            ? `. The request expires at ${at}, which comes before the ${minutesText(run.graceMs)} retry grace would run out, so that is how long it stays open for a retry; a decision after it is refused rather than granted.`
+            : ` and leaving the request open for a ${minutesText(run.graceMs)} retry grace.${expiryClause(at)}`;
+        streams.err(`approval: ${action.actionKey} (${action.cls}) is waiting for a human on ${where}; a decision on the phone releases it, and this hook blocks for up to ${waitText(run)} before denying with hook-timeout${holdsOpen}${adopted}\n`);
+    }
+    // APRV-423, third review pass. The wait is CLAMPED to what the ceiling
+    // leaves (see `HookRun.waitMs`), so the runtime acts rather than warns: a
+    // wait the harness would have cut short is shortened here, and the operator
+    // is told once so the configured --timeout is not mistaken for the wait.
+    if (run.harnessCapMs !== null && run.waitMs < run.timeoutMs) {
+        streams.err(`approval: this hook's ${String(run.timeoutMs)}ms --timeout is longer than the ${String(run.harnessCapMs)}ms harness ceiling leaves after the ${String(HARNESS_CAP_MARGIN_MS)}ms margin, so it waits ${String(run.waitMs)}ms instead and answers before the harness stops listening. Lower --timeout, or state the real ceiling with --harness-cap.\n`);
     }
     const socket = drawSocketPathFor(run.logPath);
     const listener = drawSocketUsable(socket);
@@ -2201,6 +3297,55 @@ function announceWait(streams, run, waiting) {
         return;
     streams.err(`approval: no listener is running for this log (${listener.reason}: ${socket}), so the request above may sit undelivered and a decision may go unconsumed. Start the gate's ambient runtime in the checkout that owns this log: \`eval "$(approval env)" && approval up\`, which runs the daemon loop and every configured channel in one process.\n`);
 }
+/**
+ * ` The request expires at <instant> ...`, or `""` when nothing bounds it
+ * (APRV-423).
+ *
+ * One phrasing for the three places that state the deadline — the announce
+ * line, the timeout deny and the expiry deny — so an agent reading two of them
+ * in one session is reading the same sentence about the same moment.
+ */
+function expiryClause(at) {
+    if (at === undefined)
+        return "";
+    return ` The request expires at ${at}, after which a decision on it is refused rather than granted.`;
+}
+/**
+ * Does the window a capped request is judged by close before the retry grace
+ * this invocation would hold the question open for? (APRV-423, second review
+ * pass.)
+ *
+ * Both are durations measured from the `approval.requested` record's own `ts`
+ * (`harnessCappedTtlMs` for the window, `abandonedAfterMs` for the grace), so
+ * the comparison needs no clock. `false` for an uncapped run whatever the
+ * policy's TTL: the uncapped sentences are left byte-for-byte as APRV-287 wrote
+ * them, which `tests/cli-hook.test.ts`'s snapshot case depends on. Computed from
+ * this invocation's own flags, so for an ADOPTED question opened under other
+ * flags it is the current invocation's reading of the two windows.
+ */
+/**
+ * `55000ms wait`, or `0ms wait (a 240000ms --timeout clamped to what the 30000ms
+ * harness ceiling leaves)` when the ceiling shortened it (APRV-423, third
+ * review pass). One spelling for the announce line, the lagging note and the
+ * `hook-timeout` denies, so a reader is never told a wait this process did not
+ * make.
+ */
+function waitText(run) {
+    if (run.waitMs === run.timeoutMs || run.harnessCapMs === null) {
+        return `${String(run.waitMs)}ms wait`;
+    }
+    return `${String(run.waitMs)}ms wait (a ${String(run.timeoutMs)}ms --timeout clamped to what the ${String(run.harnessCapMs)}ms harness ceiling leaves)`;
+}
+function windowEndsBeforeGrace(run) {
+    if (run.harnessCapMs === null)
+        return false;
+    const window = harnessCappedTtlMs(run.ttlMs, run.harnessCapMs);
+    return window !== null && window <= abandonedAfterMs(run.timeoutMs, run.graceMs);
+}
+/** ` (expired at <instant>)`, or `""`. The parenthetical form of the above. */
+function expiryAt(at) {
+    return at === undefined ? "" : ` (expired at ${at})`;
+}
 /**
  * The hook's own rendering of a verdict: one decision object on stdout, in the
  * dialect of the harness that asked.
@@ -2214,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
@@ -2299,7 +3448,12 @@ floor = null) {
         streams.err(`approval: withdrew ${String(swept.length)} abandoned harness request(s) nothing retried (${swept.join(", ")}); a tap on one of them now authorizes nothing and the channel says so\n`);
     }
     const actions = classes.map((cls) => {
-        const carry = findHarnessCarry(intake.records, hash, cls, intakeTs, run.ttlMs);
+        // APRV-410: the window this invocation is configured for bounds which
+        // GRANT it may carry, so an answer that landed after the asking process
+        // was gone is not adopted by a later one. The sweep above takes back the
+        // pending questions; this refuses the grants that were written on questions
+        // nobody was holding. The two halves are the same fact from both sides.
+        const carry = findHarnessCarry(intake.records, hash, cls, intakeTs, run.ttlMs, abandonedAfterMs(run.timeoutMs, run.graceMs));
         if (carry === null)
             return { cls, actionKey: `${task}:${cls}`, origin: "new" };
         return {
@@ -2311,6 +3465,62 @@ floor = null) {
     const fresh = actions.filter((action) => action.origin === "new");
     const adopted = actions.filter((action) => action.origin === "adopted");
     const carried = actions.filter((action) => action.origin === "carried");
+    /**
+     * The window every request this invocation opens will be judged by
+     * (APRV-423): the policy's TTL, narrowed by the harness ceiling this process
+     * runs under. `null` means nothing bounds it, which is a policy with no
+     * `approval_ttl` under a harness that documents no maximum and an operator
+     * who stated none.
+     */
+    const ownTtlMs = harnessCappedTtlMs(run.ttlMs, run.harnessCapMs);
+    /**
+     * When each waited-on key lapses, ISO-8601, for the lines this invocation
+     * prints. Filled from the runtime's OWN write-boundary timestamps — the `ts`
+     * on the record `request` returned, and the request record intake already
+     * read for an adopted key — so a deny that names a deadline names the one the
+     * gate will judge by, and no second read of the log pays for the sentence.
+     *
+     * CAPPED REQUESTS ONLY (APRV-423). The sentence exists to state a deadline
+     * its reader cannot work out from the policy: under a harness ceiling the
+     * window is neither `approval_ttl` nor the harness's own timeout, and an
+     * agent told "it lapsed" with no instant has no way to tell a four-minute
+     * window from the hour its policy declares. A request the policy alone bounds
+     * already has its deadline stated where its reader can see it (the approver's
+     * own card, `approval status`, the queue), so the hook's lines are left
+     * exactly as APRV-281 and APRV-287 wrote them — which also keeps every
+     * uncapped deny byte-for-byte reproducible across two invocations, the
+     * property `tests/cli-hook.test.ts` pins when it compares a cold read's
+     * verdict with a snapshot-resumed one.
+     */
+    const expiryOf = new Map();
+    // APRV-423, and the last thing checked before this invocation opens a
+    // question. A ceiling at or below the margin leaves no window: the request
+    // would have to lapse before the harness kills this process, and there is no
+    // "before" left. Refused rather than widened, because a hook that ignored its
+    // own ceiling is a hook whose question outlives its asker, which is the whole
+    // failure this cap exists to end (APRV-410). Placed here rather than at the
+    // top of the function so it refuses exactly the act it is about: an ADOPTED
+    // question was opened by a process that cleared this check, and a CARRIED
+    // grant is a human's answer that already exists.
+    if (fresh.length > 0 && run.harnessCapMs !== null && !harnessCapFitsMargin(run.harnessCapMs)) {
+        // Second review pass: the deny names the actions it refused for (so a reader
+        // can still see which class routed this call to a human), says whether the
+        // ceiling was stated or assumed, and ends with the harness's own repair
+        // where the adapter has one.
+        const needing = fresh.map((action) => `${action.actionKey} (${action.cls})`).join(", ");
+        const origin = run.harnessCapStated
+            ? "stated with --harness-cap"
+            : "assumed from the harness's documented defaults because no --harness-cap was passed";
+        // APRV-427 review: where time spent before this invocation was charged,
+        // the operator's number is named as theirs and the remainder as what is
+        // left of it, rather than reporting the remainder as what they stated.
+        const source = run.harnessCapCeilingMs === null
+            ? origin
+            : `~${String(run.harnessCapMs)}ms left of the ${String(run.harnessCapCeilingMs)}ms ceiling ${origin}; the rest was spent before this hook began, waiting in approval serve's queue or for its store lock`;
+        const repair = run.harnessCapRepair ??
+            `Raise the harness entry's timeout past ${String(HARNESS_CAP_MARGIN_MS)}ms and state the real one with --harness-cap, or route this class somewhere a human is not on the critical path.`;
+        return sayDeny("hook-harness-cap-too-short", `${needing} would need a human, but this hook runs under a ${String(run.harnessCapMs)}ms harness ceiling (${source}), and a request must lapse at least ${String(HARNESS_CAP_MARGIN_MS)}ms before that ceiling so the runtime records the expiry while the harness is still listening. That leaves no window in which a human could answer, so nothing was registered, nothing was requested and no question reached a phone. ${repair}`);
+    }
     // Only the classes that need a new question are registered. A retry whose
     // every class carries or adopts registers no task at all — the envelope it
     // would declare already exists, under the key it is about to wait on.
@@ -2359,6 +3569,12 @@ floor = null) {
             payload_hash: hash,
             payload: { value: payload },
             execution: "harness",
+            // APRV-423. The ceiling this process runs under, recorded so the gate,
+            // the daemon's sweep and every channel judge the question by a window
+            // that ends before the harness kills the asker. Omitted entirely when
+            // there is no ceiling to state: an absent field is the pre-APRV-423
+            // shape, and the policy's TTL governs alone.
+            ...(run.harnessCapMs === null ? {} : { harnessCapMs: run.harnessCapMs }),
             ...(floorApplies(action.cls) ? { loopFloor: true } : {}),
         }, run.actor, run.options);
         if (!result.ok) {
@@ -2368,8 +3584,31 @@ floor = null) {
             withdrawPending(run, streams, ownKeys, `intake refused ${action.actionKey}; this command cannot proceed, so the classes already opened for it are questions nobody needs to answer`);
             return sayDeny(`hook-gate-refused:${result.code}`, result.message);
         }
-        if (result.record !== null)
+        if (result.record !== null) {
             ownKeys.push(action.actionKey);
+            // The deadline in words, from the `ts` the runtime stamped on the record
+            // it just wrote. Never from this process's own clock: a gate-typed event
+            // carries the write boundary's instant (SPEC.md §11.1 invariant 2), and a
+            // deny that named a deadline measured from anything else would be naming
+            // a moment the gate does not judge by.
+            if (ownTtlMs !== null && run.harnessCapMs !== null) {
+                const lapses = Date.parse(result.record.ts);
+                if (!Number.isNaN(lapses)) {
+                    expiryOf.set(action.actionKey, new Date(lapses + ownTtlMs).toISOString());
+                }
+            }
+        }
+    }
+    // An adopted question was opened by an earlier invocation, under whatever
+    // ceiling THAT one ran under, so its deadline is read off the request record
+    // intake already verified rather than recomputed from this process's flags.
+    for (const action of adopted) {
+        const derivation = requestState(intake.records, action.actionKey, intakeTs, run.ttlMs);
+        if (derivation.declared.harness_cap_ms === null)
+            continue;
+        const at = requestExpiresAt(derivation);
+        if (at !== null)
+            expiryOf.set(action.actionKey, at);
     }
     /** Every key that must be granted before this hook says yes. */
     const waitKeys = [...adopted.map((action) => action.actionKey), ...ownKeys];
@@ -2385,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);
             }
@@ -2394,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);
         }
@@ -2409,21 +3649,68 @@ floor = null) {
     // an earlier tool call, which wait in the same silence and were the case the
     // announce would most easily have missed. A carried grant is not here because
     // nothing is waiting on it.
-    announceWait(streams, run, actions.filter((action) => waitKeys.includes(action.actionKey)));
-    const deadline = Date.now() + run.timeoutMs;
+    announceWait(streams, run, actions.filter((action) => waitKeys.includes(action.actionKey)), expiryOf);
+    const deadline = Date.now() + run.waitMs;
+    // APRV-427. From the first poll to the last this invocation only READS the
+    // verified log and sleeps, so an embedding caller (`approval serve`) may let
+    // other work on the same store run meanwhile. `leaveWait` hands the stretch
+    // back before anything below appends, and once more whichever way the loop
+    // is left; it is a no-op from the CLI, where there is no seam.
+    let waiting = false;
+    const leaveWait = () => {
+        if (!waiting)
+            return;
+        waiting = false;
+        run.waitSeam?.leaveWait();
+    };
     // A signal arriving mid-wait means the session is going away: nothing will
     // retry this command, so the question this invocation opened is retracted.
     // `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) => {
-        withdrawPending(run, streams, ownKeys, `the requesting hook process received ${signal} while waiting; the session is ending, so no retry will adopt this request`);
-        process.exit(EXIT_USAGE);
+        leaveWait();
+        // 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(exitCode);
     };
     const onTerm = () => onSignal("SIGTERM");
     const onInt = () => onSignal("SIGINT");
-    process.on("SIGTERM", onTerm);
-    process.on("SIGINT", onInt);
+    // Prepended: under Hermes an earlier guard (`hermesFailClosed`) listens for
+    // the same signals, and this handler, which also withdraws, must answer first.
+    process.prependListener("SIGTERM", onTerm);
+    process.prependListener("SIGINT", onInt);
     /**
      * Has this invocation already said, on stderr, that the verified view lags
      * the requests it is waiting on (APRV-294)? Said once per invocation: the
@@ -2431,22 +3718,96 @@ floor = null) {
      * matters under sixty copies of itself.
      */
     let saidLagging = false;
+    /** Consecutive torn-tail reads, for {@link TORN_TAIL_RETRIES}. */
+    let tornReads = 0;
+    /** The last whole verified view this wait read, for a torn read at the deadline. */
+    let lastClean = null;
+    const callerGone = () => run.waitSeam?.cancelled?.() === true;
+    /** The verdict for a caller that went away: nothing spent, nothing withdrawn. */
+    const sayGone = () => sayDeny("hook-timeout", `the caller that asked went away before ${waitKeys.join(", ")} could be answered to it. NOTHING WAS SPENT AND NOTHING WAS WITHDRAWN: the question, or a grant already recorded on it, is left for a retry of this exact command in this exact directory to adopt within the ${minutesText(run.graceMs)} retry grace.`);
+    const pollRead = run.waitSeam?.pollRead ?? ((path) => readVerifiedRecords(path));
+    /**
+     * The deny for a wait that ran out with the question left OPEN, after
+     * `lead` (APRV-427 review: one builder, so every route to it says the same
+     * thing). Two forms, as the second review pass (F7) fixed them: where the
+     * capped window closes before the retry grace would, the sentence names the
+     * expiry as what bounds the question; otherwise it names the grace and adds
+     * the expiry where there is one.
+     */
+    const keptOpen = (lead, stillLagging) => {
+        // APRV-423. The deadline the still-open question is under, named in the
+        // same breath as the wait that ran out: the two are different numbers and
+        // the second one is the one that decides whether a retry can still adopt
+        // this question. Under a harness ceiling it is also the instant the runtime
+        // will append `approval.expired` at, which is what keeps this deny and that
+        // record from disagreeing about one request.
+        const deadlines = waitKeys
+            .map((key) => expiryOf.get(key))
+            .filter((at) => at !== undefined);
+        const expiresAt = [...new Set(deadlines)].sort().join(", ");
+        if (deadlines.length > 0 && windowEndsBeforeGrace(run)) {
+            return sayDeny("hook-timeout", `${lead} This tool call is denied and NOTHING WAS WITHDRAWN: the harness ceiling this hook runs under bounds the question, and the request(s) expire at ${expiresAt}, which comes before the ${minutesText(run.graceMs)} retry grace would run out, so that is how long they stay open. A decision inside that window authorizes a retry of this exact command in this exact directory, once; retry it after the approver answers, and the retry adopts the same question rather than asking a second one. A decision after ${expiresAt} is refused rather than granted, the runtime records the lapse as approval.expired, and a retry then asks the question fresh.${stillLagging}`);
+        }
+        const expiresText = deadlines.length === 0
+            ? ""
+            : ` The harness ceiling this hook runs under bounds the question too: the request(s) expire at ${expiresAt}, and a decision after that is refused rather than granted — the runtime records the lapse as approval.expired.`;
+        return sayDeny("hook-timeout", `${lead} This tool call is denied and NOTHING WAS WITHDRAWN: the request(s) stay open for the ${minutesText(run.graceMs)} retry grace, and a decision inside that window authorizes a retry of this exact command in this exact directory, once.${expiresText} Retry it after the approver answers; the retry adopts the same question rather than asking a second one. Past the grace the question is taken back (approval.withdrawn, reason timeout) BY THE NEXT GATED TOOL CALL THIS ACTOR (${run.actor}) MAKES, which is the only process that may: a withdrawal is the requester's own (APRV-106), so no daemon and no channel can do it for you. Until that next call the request stays pending, and a decision that lands past the grace is recorded as a grant — it authorizes nothing, because a retry past the grace asks again rather than carrying a grant nobody was holding (APRV-410).${stillLagging}`);
+    };
+    run.waitSeam?.enterWait();
+    waiting = true;
     try {
         for (;;) {
-            const read = readVerifiedRecords(run.logPath);
+            if (callerGone())
+                return sayGone();
+            let read = pollRead(run.logPath);
+            if (!read.ok && read.code === "log-torn-tail" && tornReads < TORN_TAIL_RETRIES) {
+                if (Date.now() < deadline) {
+                    // Another writer's line, caught half-landed. Read again next tick;
+                    // see TORN_TAIL_RETRIES. Said once, like the lagging view below.
+                    if (tornReads === 0) {
+                        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;
+                    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
+                // take the timeout path and leave the question open for the retry
+                // grace; someone else's half-written line must not turn that into a
+                // withdrawal. So the tick is judged by the last whole view this wait
+                // read, and the timeout path below runs on it. Only a tail that stays
+                // torn past the retries, a write nobody is going to finish, still
+                // withdraws and denies.
+                if (lastClean === null) {
+                    return keptOpen(`no decision on ${waitKeys.join(", ")} within the hook's ${waitText(run)}, and the log's last line was incomplete when the wait ended (another writer mid-append).`, "");
+                }
+                read = lastClean;
+            }
             if (!read.ok) {
+                leaveWait();
                 withdrawPending(run, streams, ownKeys, `the hook could not read the log while waiting on ${task}`);
                 return sayDeny("hook-io", read.message);
             }
+            tornReads = 0;
+            lastClean = read;
             const ts = new Date().toISOString();
             // Only the keys this invocation is waiting on count. Deriving the set
             // from the log again would let an empty or foreign result read as
             // "nothing pending" and fall through to allow; the verified log must show
             // every one of these keys granted before the hook says yes.
-            const derived = waitKeys.map((key) => ({
-                key,
-                state: requestState(read.records, key, ts, run.ttlMs).state,
-            }));
+            const derived = waitKeys.map((key) => {
+                const derivation = requestState(read.records, key, ts, run.ttlMs);
+                // APRV-423: the deadline this read judged by, kept beside the state so
+                // the verdict and the sentence that explains it come from one
+                // derivation. A key whose record this view does not carry yet answers
+                // `null`, and the lagging branch below is what handles that.
+                if (derivation.declared.harness_cap_ms !== null) {
+                    const at = requestExpiresAt(derivation);
+                    if (at !== null)
+                        expiryOf.set(key, at);
+                }
+                return { key, state: derivation.state };
+            });
             const states = derived.map((entry) => entry.state);
             /**
              * Keys this process ESTABLISHED exist, that this read does not carry
@@ -2480,7 +3841,7 @@ floor = null) {
                 .map((entry) => entry.key);
             if (lagging.length > 0 && !saidLagging) {
                 saidLagging = true;
-                streams.err(`approval: the verified log does not yet carry ${lagging.join(", ")} (verified head: ${read.head === null ? "empty" : `seq ${String(read.head.seq)}`}). The request(s) were appended by this hook, so this is a view that lags rather than a decision; the hook keeps waiting for the verification to catch up, up to its ${String(run.timeoutMs)}ms wait. A sync or a daemon restart in the last minute is the usual cause (docs/claude-code-hook.md).\n`);
+                streams.err(`approval: the verified log does not yet carry ${lagging.join(", ")} (verified head: ${read.head === null ? "empty" : `seq ${String(read.head.seq)}`}). The request(s) were appended by this hook, so this is a view that lags rather than a decision; the hook keeps waiting for the verification to catch up, up to its ${waitText(run)}. A sync or a daemon restart in the last minute is the usual cause (docs/claude-code-hook.md).\n`);
             }
             if (!states.includes("requested") && lagging.length === 0) {
                 // Precedence, as `approval wait` fixes it: a human's "no" outranks a
@@ -2497,12 +3858,37 @@ floor = null) {
                     return sayDeny("hook-withdrawn", `the request for ${task} was withdrawn before a decision; nothing is pending and nothing was authorized`);
                 }
                 if (states.includes("expired")) {
-                    return sayDeny("hook-expired", `the request for ${task} lapsed before a decision`);
+                    // APRV-423. WHICH deadline it lapsed at, because under a harness
+                    // ceiling that is not the policy's TTL and an agent told only "it
+                    // lapsed" would read a four-minute window as an hour-long one that
+                    // somehow failed. The runtime, not this hook, appends the
+                    // `approval.expired` record: `decide` materialises it the moment a
+                    // late tap is refused, and the daemon's sweep materialises it on its
+                    // own cadence. A hook never writes one.
+                    const lapsed = derived
+                        .filter((entry) => entry.state === "expired")
+                        .map((entry) => `${entry.key}${expiryAt(expiryOf.get(entry.key))}`);
+                    return sayDeny("hook-expired", `the request for ${task} lapsed before a decision (${lapsed.join(", ")}). A decision arriving now is refused rather than granted, and the runtime records the lapse as approval.expired; run the command again to ask the question fresh.`);
                 }
                 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.
-                    const failed = consumeGrants(run, spendKeys, hash, task);
+                    //
+                    // 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 = yield* consumeGrants(run, spendKeys, hash, task);
                     if (failed !== null) {
                         return sayDeny(`hook-gate-refused:${failed.code}`, failed.message);
                     }
@@ -2531,6 +3917,7 @@ floor = null) {
                 // Past the grace nobody is coming back for it, and a question nothing
                 // will adopt is taken back rather than left for a restarted listener to
                 // re-deliver.
+                leaveWait();
                 const withdrawn = withdrawAbandoned(run, streams, read.records, ts, null, ownKeys);
                 // APRV-294: a wait that ends with the view still short of its own
                 // requests says so. The deny is the same deny — the wait ran out — and
@@ -2541,11 +3928,11 @@ floor = null) {
                     ? ""
                     : ` The verified view still does not carry ${lagging.join(", ")}, which this hook appended: the request(s) exist and the view is behind, so check the log that owns them (\`approval log verify\`, \`approval status\`) rather than reading this as an unanswered question.`;
                 if (withdrawn.length > 0) {
-                    return sayDeny("hook-timeout", `no decision on ${waitKeys.join(", ")} within the hook's ${String(run.timeoutMs)}ms wait, and the ${minutesText(run.graceMs)} retry grace has run out: ${withdrawn.join(", ")} WAS WITHDRAWN (reason timeout). A tap on it now authorizes nothing and the channel says so. Run the command again to ask the question fresh.${stillLagging}`);
+                    return sayDeny("hook-timeout", `no decision on ${waitKeys.join(", ")} within the hook's ${waitText(run)}, and the ${minutesText(run.graceMs)} retry grace has run out: ${withdrawn.join(", ")} WAS WITHDRAWN (reason timeout). A tap on it now authorizes nothing and the channel says so. Run the command again to ask the question fresh.${stillLagging}`);
                 }
-                return sayDeny("hook-timeout", `no decision on ${waitKeys.join(", ")} within the hook's ${String(run.timeoutMs)}ms wait. This tool call is denied and NOTHING WAS WITHDRAWN: the request(s) stay open for the ${minutesText(run.graceMs)} retry grace, and a decision inside that window authorizes a retry of this exact command in this exact directory, once. Retry it after the approver answers; the retry adopts the same question rather than asking a second one. Past the grace the hook takes the question back (approval.withdrawn, reason timeout), so a late retry asks again rather than adopting a question nobody is holding.${stillLagging}`);
+                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) {
@@ -2553,10 +3940,12 @@ floor = null) {
         // deny. Unlike the timeout, this process cannot say what state it left
         // behind, so the question it opened is retracted rather than left standing
         // on a failure nobody diagnosed.
+        leaveWait();
         withdrawPending(run, streams, ownKeys, `the requesting hook process failed while waiting (${cause instanceof Error ? cause.message : String(cause)})`);
         throw cause;
     }
     finally {
+        leaveWait();
         process.off("SIGTERM", onTerm);
         process.off("SIGINT", onInt);
     }
@@ -2760,9 +4149,81 @@ function readMuseReportedOutcome(input) {
     }
     return { ok: true, outcome: "completed" };
 }
+/**
+ * Hermes's outcome, read off `post_tool_call` where the event carries one
+ * (APRV-398).
+ *
+ * The envelope's result field is read for its SHAPE only, exactly as the generic
+ * reader reads Claude Code's: an `exit_code` decides a shell call, an `error`
+ * string or an `error` flag decides anything, and a result this cannot read is
+ * UNREADABLE rather than assumed complete. Nothing of the tool's output text is
+ * read, and nothing from it reaches the log.
+ *
+ * Unreadable is the safe answer in both directions at once and the reasoning is
+ * the generic reader's own: a failure nobody observed trips an escalation on
+ * noise, and a completion nobody observed clears a streak on nothing. Appending
+ * neither leaves the path as vacuous as it was before this adapter existed, for
+ * that call.
+ *
+ * A POST EVENT ON THIS HARNESS IS NOT EVIDENCE THE TOOL RAN, which APRV-415's
+ * probe established and which changes what the missing-result case may conclude.
+ * `post_tool_call` fired 29ms after an exit-2 deny, and it fired again after the
+ * armed hang was refused at the 300s cap: Hermes reports the end of its own
+ * dispatch, not the end of an execution. So an envelope this reader cannot read
+ * is UNREADABLE rather than complete. The event name is Hermes saying its
+ * `post_tool_call` code path ran and nothing more, and crediting a completion on
+ * that alone would clear a failure streak (amended SPEC.md §10.2) on a call that
+ * may have been blocked. A blocked call usually has no `execution.started` to
+ * close, because the pre half appended nothing; the case this protects is the one
+ * where the pre half ALLOWED and something later in Hermes's own executor —
+ * `approvals.mode`, a guardrail, a tool-scope check — stopped the call anyway.
+ */
+function readHermesReportedOutcome(input) {
+    // A shell result arrives as an object on this harness (`tool_input` is an
+    // object throughout its contract), so the generic object reader is the right
+    // shape; a string result says nothing about success and says so below.
+    const response = input.toolResponse;
+    if (response === null) {
+        return {
+            ok: false,
+            detail: "the post_tool_call event carries no readable result, and on this harness a post event is not evidence the tool ran: it fires for a blocked call and after a refused timeout, so nothing here says the execution completed or failed",
+        };
+    }
+    if (response["interrupted"] === true || input.interrupted) {
+        return {
+            ok: false,
+            detail: "the tool call was interrupted, so it neither completed nor failed on its own terms; an interruption is somebody stopping the session rather than a loop to escalate or a recovery to credit",
+        };
+    }
+    const exitCode = response["exit_code"] ?? response["exitCode"] ?? response["returncode"];
+    if (typeof exitCode === "number") {
+        return { ok: true, outcome: exitCode === 0 ? "completed" : "failed" };
+    }
+    const errorText = response["error"];
+    if (response["error"] === true ||
+        response["status"] === "error" ||
+        (typeof errorText === "string" && errorText.length > 0)) {
+        return { ok: true, outcome: "failed" };
+    }
+    // A result object the harness DID attach, naming neither an exit code nor an
+    // error: read as a completion, which is the generic reader's own precedent. The
+    // residual is stated rather than hidden — if a blocked call turns out to carry a
+    // result object of this shape, this line credits a completion that did not
+    // happen, and the repair is one more key here once a capture names it.
+    return { ok: true, outcome: "completed" };
+}
 function readReportedOutcome(input, adapter) {
     if (adapter.kind === "codex")
         return readCodexReportedOutcome(input);
+    if (adapter.kind === "hermes") {
+        if (input.hookEventName !== HERMES_POST_TOOL_EVENT) {
+            return {
+                ok: false,
+                detail: `hook_event_name is ${input.hookEventName === null ? "absent" : JSON.stringify(input.hookEventName)}, which is not the event this adapter reports an outcome for (${HERMES_POST_TOOL_EVENT})`,
+            };
+        }
+        return readHermesReportedOutcome(input);
+    }
     if (adapter.kind === "muse") {
         if (input.hookEventName !== "PostToolUse") {
             return {
@@ -2813,7 +4274,9 @@ function runPostToolUse(flags, streams, cwd, input, actor, adapter) {
         // APRV-347: a read tool MAY have had a start written for it (one outside
         // the scope), so it belongs in this set. A read inside the scope wrote
         // nothing, and the close below finds no start and says so in its own words.
-        !adapter.readTools.includes(input.toolName)) {
+        !adapter.readTools.includes(input.toolName) &&
+        // APRV-445: a tool the rule table gated wrote a start like any other.
+        toolRuleOf(adapter, input)?.kind !== "gated") {
         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) {
@@ -2964,6 +4427,20 @@ function describeToolCall(input, adapter, protectedPaths, cwd, readRoots = []) {
             };
         }
         const classes = classified.classes.filter((cls) => cls !== GATE_SELF_CLASS);
+        // APRV-445 refutation (B2, L10). The classifier matches protected paths by
+        // their SEGMENTS, and a relative word carries only the segments it was
+        // written with: `echo X >> .env` run in `$HERMES_HOME` names `.env`, not
+        // `.hermes/.env`, and classified as a workspace write. Where the harness
+        // states the per-call directory the command runs in, every relative word
+        // and every write target is ALSO judged resolved against it: a write that
+        // lands on an organ takes the organ's class, and a read that lands on a
+        // credential takes `account.credential`. It only ever adds a class.
+        if (shellCwd !== null) {
+            for (const cls of resolvedPathClasses(raw, classified.segments, shellCwd, protectedPaths)) {
+                if (!classes.includes(cls))
+                    classes.push(cls);
+            }
+        }
         if (adapter.kind === "codex") {
             // The pure shell classifier sees each segment independently. Preserve
             // Codex hook organs when an earlier simple `cd` changes the directory or
@@ -3045,10 +4522,37 @@ function describeToolCall(input, adapter, protectedPaths, cwd, readRoots = []) {
             segments: classified.segments,
         };
     }
+    // APRV-445: the harness's own side-effecting tools, by name and arguments.
+    // The payload is the whole call, so a grant binds every argument.
+    const ruled = toolRuleOf(adapter, input);
+    if (ruled !== null) {
+        if (ruled.kind === "read")
+            return { kind: "allow", reason: ruled.reason };
+        return {
+            kind: "gated",
+            classes: [ruled.cls],
+            payload: { tool: input.toolName, input: input.toolInput },
+            headline: ruled.headline,
+            notes: [],
+        };
+    }
     // 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.
     if (adapter.readTools.includes(input.toolName)) {
+        // APRV-445 refutation (B2): a read tool naming a credential file is
+        // `account.credential` wherever the file sits, inside the read scope
+        // included, as the same read through the shell already was.
+        const credential = credentialReadGate(input.toolName, input.toolInput, cwd);
+        if (credential !== null) {
+            return {
+                kind: "gated",
+                classes: ["account.credential"],
+                payload: credential.payload,
+                headline: credential.summary,
+                notes: [],
+            };
+        }
         const read = readToolGate(input.toolName, input.toolInput, readRoots, cwd);
         if (read === null) {
             return {
@@ -3078,6 +4582,465 @@ function describeToolCall(input, adapter, protectedPaths, cwd, readRoots = []) {
         notes: gated.protectedPath ? [fileTierNote(gated)] : [],
     };
 }
+/**
+ * The classes a shell command's PATHS take once they are resolved the way the
+ * shell and the filesystem will resolve them (APRV-445 refutation B2 and L10,
+ * recheck SF2 and L-e), for a harness that states the directory each call runs
+ * in.
+ *
+ * The classifier matches organs and credentials by path SEGMENTS of the words
+ * as written. A word written relative (`.env` run in `$HERMES_HOME`), through a
+ * variable (`$HERMES_HOME/.env`), after a `cd`, or through a symlinked parent
+ * (`h/.env` where `h -> .hermes`) carries none of the segments that matter. So
+ * each path a segment touches is also judged here:
+ *
+ * - WRITTEN paths are the redirect targets (heredocs included) and the
+ *   write-argument positions of the binaries whose writes are known (L-e):
+ *   never the binary, never a word that is merely an argument. A written path
+ *   resolving to an organ takes its class; one carrying a glob or a variable
+ *   this hook cannot expand is `policy.core` when it lands in one of the gate's
+ *   own directories ({@link gateRootKind}) or a pattern in it could name the
+ *   home or an organ (recheck 3); an unexpanded `$HERMES_HOME` in a written
+ *   path is `policy.core` wherever it is written from. A copy into a directory
+ *   writes `<dir>/<source name>`; an extraction writes into its directory.
+ * - READ paths (a read segment's arguments, `<` targets, a copy's sources) that
+ *   resolve to a credential take `account.credential`, and so does a directory
+ *   that holds credentials ({@link holdsCredentials}) handed to a binary that
+ *   reads directories recursively (`grep -r`, `rg`, `find`, `tar`, ...).
+ * - After a `cd` this hook cannot resolve, every later relative write is
+ *   `policy.core` and every later relative read `account.credential`.
+ * - `cd` moves the directory for the segments after it. Like the Codex arm, a
+ *   `cd` may or may not have run (`||`, a failed `cd`), so the directories
+ *   before and after it are both kept and every later path is judged from each.
+ * - Every path is resolved through `realpath` on its deepest existing ancestor,
+ *   so a symlinked parent or working directory is judged by where it lands.
+ * - `$HERMES_HOME` / `${HERMES_HOME}` expand to `APPROVAL_HERMES_HOME`, else
+ *   `HERMES_HOME`, from this hook process's environment; `~`, `$HOME` and
+ *   `${HOME}` to `HOME`. Under `approval serve` the process is the daemon, so a
+ *   hosted operator sets `APPROVAL_HERMES_HOME` there; without it, the
+ *   conservative rules above apply to the unexpanded spelling.
+ *
+ * What stays out of reach is listed in `docs/hermes-hook.md`: inline programs
+ * (`python -c`, which the classifier already refuses as opaque), `dd`/`install`
+ * (unclassified, so already denied), and a recursive search of an ANCESTOR of
+ * the home with a filename filter.
+ *
+ * It only ever adds classes.
+ */
+function resolvedPathClasses(raw, segments, cwd, protectedPaths, env = process.env) {
+    const found = [];
+    const add = (cls) => {
+        if (cls !== null && !found.includes(cls))
+            found.push(cls);
+    };
+    const shapes = commandSegmentShapes(raw) ?? [];
+    // Trusted as given: the operator sets it (under co-location, the control
+    // plane sets it from the tenant's home), and nothing the agent writes reaches
+    // this process's environment.
+    const hermesHome = env["APPROVAL_HERMES_HOME"] ?? env["HERMES_HOME"] ?? null;
+    const home = env["HOME"] ?? null;
+    /** The word with the variables this hook can know expanded. */
+    const expand = (word) => {
+        let text = word;
+        let hermesUnknown = false;
+        const hermesRef = /^\$(?:\{HERMES_HOME\}|HERMES_HOME)(?=\/|$)/u;
+        if (hermesRef.test(text)) {
+            if (hermesHome !== null && hermesHome.length > 0)
+                text = text.replace(hermesRef, hermesHome);
+            else
+                hermesUnknown = true;
+        }
+        const homeRef = /^(?:~|\$\{HOME\}|\$HOME)(?=\/|$)/u;
+        if (homeRef.test(text) && home !== null && home.length > 0)
+            text = text.replace(homeRef, home);
+        return { text, hermesUnknown, unresolved: hermesUnknown || /[$`]/u.test(text) };
+    };
+    // After a `cd` this hook cannot resolve (`cd $X`, `cd "$D"`, `cd -`), the
+    // directory every later relative path lands in is unknown (recheck 3, SF2).
+    let cwdUnknown = false;
+    let cwds = [canonicalPath(cwd)];
+    for (const [index, segment] of segments.entries()) {
+        const shape = shapes.length === segments.length
+            ? shapes[index]
+            : shapes.find((candidate) => candidate.text === segment.text);
+        if (shape === undefined)
+            continue;
+        const bin = shape.bin === null ? null : basename(shape.bin);
+        const operands = shape.args.filter((arg) => !arg.startsWith("-"));
+        if (bin === "cd" || bin === "pushd") {
+            const target = operands[0];
+            if (target === undefined) {
+                // A bare `cd` goes HOME; `cd -` and `pushd` with no operand go to a
+                // directory recorded earlier in a shell this hook never saw.
+                if (bin === "cd" && !shape.args.includes("-") && home !== null) {
+                    cwds = [...new Set([...cwds, canonicalPath(home)])];
+                }
+                else {
+                    cwdUnknown = true;
+                }
+            }
+            else {
+                const expanded = expand(target);
+                if (expanded.unresolved || hasGlobChars(expanded.text)) {
+                    cwdUnknown = true;
+                }
+                else {
+                    const next = cwds.map((from) => canonicalPath(resolvePathSegments(from, expanded.text)));
+                    cwds = [...new Set([...cwds, ...next])];
+                }
+            }
+            continue;
+        }
+        if (bin === null && shape.writes.length === 0 && shape.reads.length === 0)
+            continue;
+        const judgeWrite = (word) => {
+            const target = expand(word);
+            if (target.hermesUnknown) {
+                add("policy.core");
+                return;
+            }
+            if (!isAbsolute(target.text) && cwdUnknown) {
+                add("policy.core");
+                return;
+            }
+            const globbed = target.unresolved || hasGlobChars(target.text);
+            for (const from of cwds) {
+                const absoluteTarget = resolvePathSegments(from, target.text);
+                if (globbed) {
+                    // SF3a: a pattern in any component that could name the home, the
+                    // approval home or an organ is an organ write; a pattern written
+                    // into one of the gate's own directories (SF1b) may be any file
+                    // there. Anywhere else it is a workspace write.
+                    if (globCouldNameOrgan(absoluteTarget) || writesIntoGateRoot(canonicalPath(dirname(absoluteTarget)))) {
+                        add("policy.core");
+                    }
+                    continue;
+                }
+                add(protectedPathClass(canonicalPath(absoluteTarget), protectedPaths));
+            }
+        };
+        /** A copy or move INTO a directory writes `<dir>/<basename of source>`. */
+        const judgeWriteInto = (directory, sources) => {
+            for (const source of sources) {
+                const name = basename(expand(source).text);
+                if (name.length === 0 || name === "." || name === "..") {
+                    // `cp -r stuff/. dir`: the contents land in the directory itself.
+                    judgeExtractInto(directory);
+                    continue;
+                }
+                judgeWrite(join(directory, name));
+            }
+        };
+        /** An extraction or a contents-copy writes unknown names into `directory`. */
+        const judgeExtractInto = (directory) => {
+            const target = expand(directory);
+            if (target.hermesUnknown || (cwdUnknown && !isAbsolute(target.text))) {
+                add("policy.core");
+                return;
+            }
+            if (target.unresolved)
+                return;
+            for (const from of cwds) {
+                if (writesIntoGateRoot(canonicalPath(resolvePathSegments(from, target.text))))
+                    add("policy.core");
+            }
+        };
+        const judgeRead = (word, recursive) => {
+            const target = expand(word);
+            if (target.hermesUnknown) {
+                add("account.credential");
+                return;
+            }
+            if (!isAbsolute(target.text) && cwdUnknown) {
+                add("account.credential");
+                return;
+            }
+            if (target.unresolved)
+                return;
+            for (const from of cwds) {
+                const absoluteTarget = resolvePathSegments(from, target.text);
+                if (hasGlobChars(target.text)) {
+                    // SF3b: expand against the directory when it is known; otherwise a
+                    // pattern that could name a credential is read as one.
+                    const candidates = expandGlob(absoluteTarget);
+                    if (candidates === null) {
+                        if (globCouldNameCredential(absoluteTarget))
+                            add("account.credential");
+                    }
+                    else {
+                        for (const candidate of candidates) {
+                            if (isCredentialPath(canonicalPath(candidate)))
+                                add("account.credential");
+                        }
+                    }
+                    continue;
+                }
+                const resolved = canonicalPath(absoluteTarget);
+                if (isCredentialPath(resolved))
+                    add("account.credential");
+                else if (recursive && holdsCredentials(resolved))
+                    add("account.credential");
+            }
+        };
+        for (const target of shape.writes)
+            judgeWrite(target);
+        for (const source of shape.reads)
+            judgeRead(source, false);
+        if (bin === null)
+            continue;
+        // `-t DIR` / `--target-directory=DIR` names the destination up front.
+        const targetDirFlag = () => {
+            for (const [at, arg] of shape.args.entries()) {
+                if (arg === "-t")
+                    return shape.args[at + 1] ?? null;
+                if (arg.startsWith("--target-directory="))
+                    return arg.slice("--target-directory=".length);
+            }
+            return null;
+        };
+        if (WRITE_EVERY_OPERAND.has(bin)) {
+            for (const operand of operands)
+                judgeWrite(operand);
+        }
+        else if (WRITE_LAST_OPERAND.has(bin)) {
+            const targetDir = targetDirFlag();
+            const sources = targetDir === null ? operands.slice(0, -1) : operands.filter((operand) => operand !== targetDir);
+            const destination = targetDir ?? operands[operands.length - 1];
+            for (const source of sources)
+                judgeRead(source, true);
+            if (destination !== undefined) {
+                const expanded = expand(destination);
+                const intoDirectory = targetDir !== null ||
+                    destination.endsWith("/") ||
+                    (!expanded.unresolved &&
+                        cwds.some((from) => isDirectoryPath(canonicalPath(resolvePathSegments(from, expanded.text)))));
+                if (intoDirectory)
+                    judgeWriteInto(destination, sources);
+                else
+                    judgeWrite(destination);
+            }
+        }
+        else if (WRITE_AFTER_FIRST_OPERAND.has(bin)) {
+            for (const operand of operands.slice(1))
+                judgeWrite(operand);
+        }
+        else if (bin === "sed" && shape.args.some((arg) => arg === "--in-place" || /^-[a-zA-Z]*i/u.test(arg))) {
+            const scripted = shape.args.some((arg) => arg === "-e" || arg === "-f");
+            for (const operand of scripted ? operands : operands.slice(1))
+                judgeWrite(operand);
+        }
+        else if (bin === "dd") {
+            for (const arg of shape.args) {
+                if (arg.startsWith("of="))
+                    judgeWrite(arg.slice(3));
+                if (arg.startsWith("if="))
+                    judgeRead(arg.slice(3), false);
+            }
+        }
+        else if (bin === "tar" && isTarExtract(shape.args)) {
+            // Lows: an extraction writes the archive's names into `-C DIR` or the
+            // working directory.
+            judgeExtractInto(flagValue(shape.args, "-C", "--directory") ?? ".");
+        }
+        else if (bin === "unzip") {
+            judgeExtractInto(flagValue(shape.args, "-d", null) ?? ".");
+        }
+        if (segment.class.startsWith("read.") || RECURSIVE_READERS.has(bin)) {
+            for (const operand of operands)
+                judgeRead(operand, RECURSIVE_READERS.has(bin));
+        }
+    }
+    return found;
+}
+/** `*`, `?` or `[` in a path word. */
+function hasGlobChars(text) {
+    return /[*?[]/u.test(text);
+}
+/** A shell glob component as an anchored regular expression. */
+function globRegex(component) {
+    let source = "";
+    for (const char of component) {
+        if (char === "*")
+            source += ".*";
+        else if (char === "?")
+            source += ".";
+        else if (char === "[" || char === "]")
+            source += char;
+        else
+            source += char.replace(/[.+^${}()|\\]/gu, "\\$&");
+    }
+    try {
+        return new RegExp(`^${source}$`, "u");
+    }
+    catch {
+        return /^.*$/u;
+    }
+}
+/** Names a credential file goes by, for a pattern to be tested against. */
+const CREDENTIAL_NAMES = [".env", ".env.local", "auth.json", "env", "vault.enc", "keys"];
+/** Names an organ goes by, beyond the credentials. */
+const ORGAN_NAMES = [
+    ...CREDENTIAL_NAMES,
+    "config.yaml",
+    "config.yml",
+    "shell-hooks-allowlist.json",
+    "shell-hooks-allowlist.json.lock",
+    "agent-hooks",
+    "approval",
+    "scripts",
+];
+/** Could some component of `path`'s pattern name the home or the approval home? */
+function globCouldNameGateHome(path) {
+    return path
+        .split(/[/\\]+/u)
+        .some((component) => hasGlobChars(component) && [".hermes", ".approval"].some((name) => globRegex(component).test(name)));
+}
+/** SF3a: a written pattern that could land on an organ. */
+function globCouldNameOrgan(path) {
+    if (globCouldNameGateHome(path))
+        return true;
+    const last = basename(path);
+    if (!hasGlobChars(last))
+        return false;
+    const pattern = globRegex(last);
+    const parent = dirname(path);
+    const parentIsHome = parent.split(/[/\\]+/u).some((segment) => segment === ".hermes" || segment === ".approval") ||
+        hasGlobChars(parent);
+    return parentIsHome && ORGAN_NAMES.some((name) => pattern.test(name));
+}
+/** SF3b: a read pattern whose directory is unknown, that could name a credential. */
+function globCouldNameCredential(path) {
+    const last = basename(path);
+    if (!hasGlobChars(last))
+        return globCouldNameGateHome(path);
+    const pattern = globRegex(last);
+    return CREDENTIAL_NAMES.some((name) => pattern.test(name)) || globCouldNameGateHome(path);
+}
+/** The entries a final-component glob matches, or `null` when the directory is unknown. */
+function expandGlob(path) {
+    const parent = dirname(path);
+    if (hasGlobChars(parent))
+        return null;
+    try {
+        const pattern = globRegex(basename(path));
+        return readdirSync(canonicalPath(parent))
+            .filter((name) => pattern.test(name))
+            .map((name) => join(parent, name));
+    }
+    catch {
+        return null;
+    }
+}
+function isDirectoryPath(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The gate's own directories (recheck 3, SF1): a Hermes home (or profile home)
+ * root, an approval home, a home's `approval/`, and its `scripts/`. Everything
+ * else under a home (`workspace/`, `skills/`, `memories/`, `sessions/`) is
+ * ordinary work, which matters because a hosted image runs ALL agent work under
+ * `$HERMES_HOME`.
+ */
+function gateRootKind(directory) {
+    const segments = directory.split(/[/\\]+/u).filter((segment) => segment.length > 0);
+    const last = segments[segments.length - 1];
+    const isHome = (at) => segments[at] === ".hermes" ||
+        (segments[at - 2] === ".hermes" && segments[at - 1] === "profiles" && segments[at] !== undefined);
+    if (last === undefined)
+        return null;
+    if (isHome(segments.length - 1))
+        return "home";
+    if (last === ".approval")
+        return "approval-home";
+    if (last === "approval" && isHome(segments.length - 2))
+        return "home-approval";
+    if (last === "scripts" && isHome(segments.length - 2))
+        return "scripts";
+    return null;
+}
+/** A glob or an unknown name written here may be an organ (SF1b). */
+function writesIntoGateRoot(directory) {
+    return gateRootKind(directory) !== null;
+}
+/**
+ * A directory a recursive read of which reads credentials (SF1a): the home
+ * root, the approval home, a home's `approval/`, and any directory under a home
+ * that directly holds a credential file.
+ */
+function holdsCredentials(directory) {
+    if (!isDirectoryPath(directory))
+        return false;
+    const kind = gateRootKind(directory);
+    if (kind === "home" || kind === "approval-home" || kind === "home-approval")
+        return true;
+    if (!directory.split(/[/\\]+/u).some((segment) => segment === ".hermes" || segment === ".approval"))
+        return false;
+    return CREDENTIAL_FILE_NAMES.some((name) => existsSync(join(directory, name)));
+}
+const CREDENTIAL_FILE_NAMES = [
+    ".env",
+    "auth.json",
+    "config.yaml",
+    "config.yml",
+    "shell-hooks-allowlist.json",
+    "shell-hooks-allowlist.json.lock",
+];
+function isTarExtract(args) {
+    const first = args[0] ?? "";
+    return args.some((arg) => arg === "--extract" || arg === "--get" || /^-[a-zA-Z]*x/u.test(arg)) ||
+        (!first.startsWith("-") && first.includes("x"));
+}
+function flagValue(args, short, long) {
+    for (const [at, arg] of args.entries()) {
+        if (arg === short)
+            return args[at + 1] ?? null;
+        if (arg.startsWith(short) && arg.length > short.length && !arg.startsWith("--"))
+            return arg.slice(short.length);
+        if (long !== null && arg.startsWith(`${long}=`))
+            return arg.slice(long.length + 1);
+        if (long !== null && arg === long)
+            return args[at + 1] ?? null;
+    }
+    return null;
+}
+/** Binaries every operand of which is a path they create, change or remove. */
+const WRITE_EVERY_OPERAND = new Set([
+    "touch", "truncate", "mkdir", "rm", "rmdir", "shred", "tee", "unlink",
+]);
+/** Binaries whose LAST operand is the destination and the rest are sources. */
+const WRITE_LAST_OPERAND = new Set(["cp", "mv", "ln", "install", "rsync"]);
+/** Binaries whose first operand is a mode or owner and the rest are paths. */
+const WRITE_AFTER_FIRST_OPERAND = new Set(["chmod", "chown", "chgrp"]);
+/** Readers that walk a directory they are handed. */
+const RECURSIVE_READERS = new Set([
+    "grep", "egrep", "fgrep", "rg", "ag", "ack", "find", "tar", "zip", "du", "tree",
+]);
+/**
+ * `path` resolved through the realpath of its deepest existing ancestor, so a
+ * symlinked parent is judged by where it lands and a path that does not exist
+ * yet is judged by where it would be created (APRV-445 recheck SF2(e)).
+ */
+function canonicalPath(path) {
+    let current = path;
+    const tail = [];
+    for (;;) {
+        try {
+            return resolvePathSegments(realpathSync(current), ...tail.reverse());
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return resolvePathSegments(path);
+            tail.push(basename(current));
+            current = parent;
+        }
+    }
+}
 /** The environment variable that turns the sandbox requirement on (APRV-193). */
 export const REQUIRE_SANDBOX_ENV = "APPROVAL_HOOK_REQUIRE_SANDBOX";
 /**
@@ -3192,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
@@ -3252,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,
@@ -3261,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
@@ -3281,8 +5252,13 @@ 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) {
-    const configurationError = (message) => adapter.kind === "codex" ? deny(streams, "hook-io", message, adapter.kind) : usageError(streams, message);
+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.
+    const configurationError = (message) => adapter.kind === "codex" || adapter.kind === "hermes"
+        ? deny(streams, "hook-io", message, adapter.kind)
+        : usageError(streams, message);
     const parsed = parseFlags(argv, {
         ...COMMON_FLAGS,
         ...POLICY_FLAGS,
@@ -3291,6 +5267,7 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         "--timeout": "string",
         "--interval": "string",
         "--retry-grace": "string",
+        "--harness-cap": "string",
     });
     if (!parsed.ok)
         return configurationError(parsed.message);
@@ -3301,11 +5278,19 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         // Muse gets its own for the same reason and one more: its `.muse/hooks.json`
         // shape is not Claude's file under a different name, and an operator who
         // guessed would get "Hooks: 0 runnable" and a session that looks gated.
+        // Hermes gets its own for a third reason on top of those two (APRV-398):
+        // the file the human commits is YAML, it is not in the repository at all
+        // (`$HERMES_HOME/config.yaml`), and the entry carries the one key that
+        // decides whether this adapter is a gate or a backstop — `fail_closed`. A
+        // reader who copied a JSON block from another harness's help would install
+        // nothing.
         const harnessHelp = adapter.kind === "grok"
             ? HOOK_GROK_HELP
             : adapter.kind === "muse"
                 ? HOOK_MUSE_HELP
-                : HOOK_HELP;
+                : adapter.kind === "hermes"
+                    ? HOOK_HERMES_HELP
+                    : HOOK_HELP;
         streams.out(`${harnessHelp}\n`);
         return EXIT_OK;
     }
@@ -3336,6 +5321,35 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     if (graceMs === null) {
         return configurationError(`--retry-grace expects a duration like 5m, 30s, 1ms, got ${JSON.stringify(graceText)}`);
     }
+    // APRV-423. The ceiling this process runs under, which the hook cannot
+    // discover for itself: the harness spawns it and tells it nothing. The
+    // OPERATOR states the entry timeout they configured, and the adapter
+    // contributes the harness's own documented maximum where its contract has
+    // one. The smaller wins, because a stated cap above a contractual ceiling is
+    // a statement the harness will not honour, and a cap may only ever shorten
+    // the window (SPEC.md §11.1 invariant 4).
+    const capText = stringFlag(parsed.flags, "--harness-cap");
+    const statedCapMs = capText === null ? null : parseDuration(capText);
+    if (capText !== null && statedCapMs === null) {
+        return configurationError(`--harness-cap expects a duration like 300s, 4m, got ${JSON.stringify(capText)}`);
+    }
+    // Second review pass. A stated cap is clamped to the contractual ceiling
+    // (Hermes will not honour an entry above 300 s however it is written); an
+    // absent flag takes the harness's DEFAULT bound where the adapter documents
+    // one, and only then falls back to the ceiling. The default is the stricter
+    // number on purpose: an operator who has said nothing is assumed to run the
+    // harness as shipped, and a runtime that assumed the ceiling instead would
+    // assert a deadline the harness will not keep (APRV-410 with a fictional
+    // T+240 s, which is exactly what the first pass did on a default Hermes).
+    const capMs = effectiveHarnessCapMs(adapter, statedCapMs);
+    // APRV-427 review: charged for the time the call spent before this line,
+    // using the remainder the embedding caller admitted it on, unchanged. See
+    // HookWaitSeam.remainingCapMs.
+    const remainingCapMs = waitSeam?.remainingCapMs;
+    const harnessCapMs = capMs === null || remainingCapMs === undefined
+        ? capMs
+        : Math.max(0, Math.min(capMs, remainingCapMs));
+    const harnessCapStated = statedCapMs !== null;
     const parsedInput = parseHookInput(readStdin(), adapter.camelCaseEnvelope === true);
     if (!parsedInput.ok)
         return deny(streams, "hook-io", parsedInput.detail, adapter.kind);
@@ -3376,7 +5390,7 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     if (adapter.contributorModelGuard === true) {
         const refusal = contributorModelRefusal(input.model);
         if (refusal !== null) {
-            const postEvent = input.hookEventName !== null && POST_TOOL_EVENTS.includes(input.hookEventName);
+            const postEvent = isPostToolEvent(adapter, input.hookEventName);
             return postEvent
                 ? report(streams, MUSE_CONTRIBUTOR_REFUSAL, `${refusal} Nothing was appended.`)
                 : deny(streams, MUSE_CONTRIBUTOR_REFUSAL, refusal, adapter.kind);
@@ -3389,7 +5403,7 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // fall through, so the verdict is one dialect and nothing else, which is the
     // only shape this harness parses.
     if (adapter.passThroughTools?.includes(input.toolName) === true) {
-        const passPostEvent = input.hookEventName !== null && POST_TOOL_EVENTS.includes(input.hookEventName);
+        const passPostEvent = isPostToolEvent(adapter, input.hookEventName);
         if (passPostEvent) {
             return report(streams, "post-tool-not-gated", `${input.toolName} is the harness's own bookkeeping tool, so no execution.started was ever written for it`);
         }
@@ -3405,9 +5419,7 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // harness whose event this runtime does not recognize is a harness about to
     // run a command, and treating an unknown name as a no-op would be an ungated
     // one.
-    const postToolEvent = adapter.kind === "codex"
-        ? input.hookEventName === CODEX_POST_TOOL_EVENT
-        : input.hookEventName !== null && POST_TOOL_EVENTS.includes(input.hookEventName);
+    const postToolEvent = isPostToolEvent(adapter, input.hookEventName);
     if (postToolEvent) {
         // APRV-303. `commandHarnessHook`'s catch turns a throw into a DENY, which is
         // the right answer for a call that has not run yet and exactly the wrong one
@@ -3422,7 +5434,15 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         // path therefore always exits 0. The machine-readable line still goes to
         // stderr; whether Grok shows it is Grok's business, and losing a debug line
         // is a smaller harm than emitting a verdict the protocol will act on.
-        const settle = (code) => (adapter.kind === "grok" ? EXIT_OK : code);
+        //
+        // APRV-398. Hermes joins Grok on that rule, and for the same reason read off
+        // its own contract: Hermes documents exit 2 as BLOCKING, so a visibility
+        // exit here would be a block aimed at a tool call that has already run.
+        // This adapter's whole stance on this harness is that the exit status
+        // carries no verdict (see `HERMES_DENY_EXIT`), and that has to hold on both
+        // halves or it holds nowhere. The machine-readable line still goes to
+        // stderr, and whether Hermes shows it is Hermes's business.
+        const settle = (code) => adapter.kind === "grok" || adapter.kind === "hermes" ? EXIT_OK : code;
         try {
             return settle(runPostToolUse(parsed.flags, streams, cwd, input, actor, adapter));
         }
@@ -3439,7 +5459,46 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     if (adapter.kind === "codex" && input.toolName === "Bash") {
         return deny(streams, "hook-unsupported-execution-context", "Codex Bash is disabled because the native hook contract does not expose the effective per-call working directory; no policy or open window can authorize bytes the hook cannot bind", adapter.kind);
     }
-    if (input.toolName !== adapter.shellTool && !adapter.fileTools.includes(input.toolName)) {
+    // APRV-398, and placed exactly where the Codex refusal above is placed, for
+    // exactly its reason: before the open window, the gate-self path, the carry
+    // and the registration, because none of those can supply a fact the call does
+    // not carry. Hermes's `execute_code` takes a `code` string and nothing else —
+    // no path, no argv, no working directory — so there is nothing for the
+    // classifier to read and nothing a payload could bind. A verdict over
+    // `{code}` would authorize a program this runtime never parsed.
+    //
+    // It is refused rather than classified `hook-opaque` because the repair
+    // differs: an opaque command line can be rewritten, and there is no spelling
+    // of an `execute_code` call that this hook could answer differently. Nothing
+    // appends on this path and no gate lifecycle opens. An OPEN WINDOW does not
+    // reach it either, which is the strict reading a window deserves here: a
+    // window suspends the policy, and this refusal is not a policy question.
+    if (adapter.kind === "hermes" && input.toolName === HERMES_EXECUTE_CODE_TOOL) {
+        return deny(streams, HERMES_EXECUTE_CODE_REFUSAL, `Hermes ${HERMES_EXECUTE_CODE_TOOL} is refused because the call carries a program and nothing else: no path, no argv and no working directory, so no class can be resolved and no payload can bind what it would do. Run the work through the \`${adapter.shellTool}\` tool, where the words are visible to the classifier, or through \`approval run\` with a granted token. No policy or open window authorizes bytes the hook cannot read`, adapter.kind);
+    }
+    // APRV-415, and placed here for the reason the two refusals above are: before
+    // the open window, the gate-self path, the carry and the registration, because
+    // none of those can supply the directory a Hermes call leaves out. The live
+    // probe established that this harness reports NO effective directory for a
+    // call that does not state one — see {@link hermesUnboundDirectory} — so the
+    // refusal is the Codex `Bash` refusal one harness along, narrowed to the calls
+    // that actually withhold the fact.
+    if (adapter.kind === "hermes") {
+        const unbound = hermesUnboundDirectory(input, adapter);
+        if (unbound !== null) {
+            return deny(streams, "hook-unsupported-execution-context", unbound, adapter.kind);
+        }
+    }
+    // APRV-445: a tool the adapter's own rule table gates goes on to the gated
+    // path below; one it reads is allowed here, with no policy load, exactly as
+    // an in-scope read is.
+    const ruledEarly = toolRuleOf(adapter, input);
+    if (ruledEarly?.kind === "read") {
+        return allow(streams, ruledEarly.reason, adapter.kind, codexCommand);
+    }
+    if (ruledEarly === null &&
+        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);
         }
@@ -3460,7 +5519,8 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         // 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 (readToolGate(input.toolName, input.toolInput, resolveReadRoots(cwd, early.root), cwd) === null) {
+        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);
         }
     }
@@ -3493,13 +5553,13 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
     // 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,
@@ -3511,8 +5571,14 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
         timeoutMs,
         intervalMs,
         graceMs,
+        harnessCapMs,
+        harnessCapStated,
+        // The ceiling before the time in line was charged, for the refusal's
+        // wording only: the charged number is the one everything is judged by.
+        ...(harnessCapMs !== capMs && capMs !== null ? { harnessCapCeilingMs: capMs } : {}),
         codexCommand,
         windowRecords: looked.records,
+        waitSeam,
     }));
 }
 /**
@@ -3532,7 +5598,14 @@ function runHarnessHook(argv, streams, cwd, readStdin, adapter) {
  * 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;
+    const harnessCapCeilingMs = decide.harnessCapCeilingMs ?? null;
     // The policy is read BEFORE the command is classified (APRV-107): the
     // protected-path set is built-ins plus `policy.protected_paths`, so what
     // counts as a protected path is a policy question and the classifier cannot be
@@ -3595,6 +5668,7 @@ export function decideHarnessCall(decide) {
         ? codexBinding(input, cwd).task
         : `hook:${input.sessionId}:${input.toolUseId ?? randomBytes(8).toString("hex")}`;
     const run = {
+        waitSeam: decide.waitSeam ?? null,
         logPath,
         options,
         actor,
@@ -3602,6 +5676,13 @@ export function decideHarnessCall(decide) {
         intervalMs,
         graceMs,
         ttlMs: load.durations.approvalTtlMs,
+        harnessCapMs,
+        harnessCapStated,
+        harnessCapCeilingMs,
+        harnessCapRepair: adapter.capRepair ?? null,
+        waitMs: harnessCapMs === null
+            ? timeoutMs
+            : Math.max(0, Math.min(timeoutMs, harnessCapMs - HARNESS_CAP_MARGIN_MS)),
         harness: adapter.kind,
         originApp: adapter.originApp,
         ...(codexCommand === undefined ? {} : { codexCommand }),
@@ -3732,12 +5813,41 @@ export function decideHarnessCall(decide) {
         }
     }
     if (floor === null && autonomies.every((autonomy) => autonomy === "autonomous")) {
+        // APRV-410. The sweep that takes back this actor's abandoned questions used
+        // to live only in `gateHarnessCall`, which an autonomous command never
+        // reaches — so a session whose retry classified autonomously left its
+        // expired question standing until the TTL, and a human's tap on it six
+        // minutes past the grace was recorded as a grant nobody held (log seq
+        // 64473, 2026-09-20). The withdrawal has to be made by the REQUESTER, which
+        // is this actor: `withdraw` refuses a `system:` actor in as many words, and
+        // the event schema's cross-rule binds a `system:` withdrawal to
+        // `policy-drift` alone (APRV-235), so the daemon is not a candidate and the
+        // next invocation of the asking actor is the only one there is.
+        //
+        // `windowRecords` is the verified read `lookupWindow` already performed on
+        // this invocation, so the sweep costs one append when there is something to
+        // take back and nothing at all when there is not. `withdraw` re-reads and
+        // compare-and-appends against its own head (SPEC.md §11.1 invariant 5), so
+        // a question decided between that read and this call refuses
+        // `already-decided` and is passed over rather than overwritten.
+        //
+        // `keepHash` is this invocation's own bytes, exactly as the intake sweep
+        // passes it: a sibling hook process waiting on a question about the same
+        // payload is never taken back from under it.
+        if (windowRecords !== null) {
+            const swept = withdrawAbandoned(run, streams, windowRecords, new Date().toISOString(), payloadHash(payload));
+            if (swept.length > 0) {
+                streams.err(`approval: withdrew ${String(swept.length)} abandoned harness request(s) nothing retried (${swept.join(", ")}); a tap on one of them now authorizes nothing\n`);
+            }
+        }
         // No approval lifecycle: an autonomous action has none (amended SPEC.md
         // §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",
@@ -3753,11 +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) {
+function* commandHarnessHook(argv, streams, cwd, readStdin, adapter, waitSeam) {
+    if (adapter.kind === "hermes") {
+        return yield* hermesFailClosed(argv, streams, cwd, readStdin, adapter, waitSeam);
+    }
     try {
-        return runHarnessHook(argv, streams, cwd, readStdin, adapter);
+        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,
@@ -3767,6 +5880,145 @@ function commandHarnessHook(argv, streams, cwd, readStdin, adapter) {
         return deny(streams, "hook-io", `the hook failed: ${cause instanceof Error ? cause.message : String(cause)}`, adapter.kind);
     }
 }
+/**
+ * The Hermes hook's last line of defence (APRV-445): whatever happened inside,
+ * a `pre_tool_call` answer leaves this function as a verdict Hermes blocks on or
+ * as an explicit allow, and never as anything Hermes would read as an allow by
+ * default.
+ *
+ * Hermes (v2026.9.24, `agent/shell_hooks.py`) blocks on exit 2 whatever stdout
+ * says, and blocks on any other non-zero exit only when stdout carries a block
+ * directive; ANY OTHER NON-ZERO EXIT WITH AN EMPTY STDOUT IS AN ALLOW, with a
+ * warning in a log nobody reads. So this enforces two rules on every path:
+ *
+ * - a non-zero exit always carries the `{action:"block"}` directive on stdout
+ *   and is always exactly 2;
+ * - exit 0 on a pre-event is only ever the adapter's own `{}` allow. A path that
+ *   returned 0 having printed nothing is a path nobody wrote a verdict for, and
+ *   it blocks.
+ *
+ * A post-event is untouched: it never blocks (see the post path), and it prints
+ * nothing on stdout by design. A throw becomes the same block the other
+ * adapters' catch produces.
+ */
+function* hermesFailClosed(argv, streams, cwd, readStdin, adapter, 
+/** APRV-427: serve's wait seam, passed through untouched (null on the CLI). */
+waitSeam) {
+    let stdout = "";
+    const tracked = {
+        out: (text) => {
+            stdout += text;
+            streams.out(text);
+        },
+        err: (text) => streams.err(text),
+    };
+    // The post-event question is answered from the raw input, once, before the
+    // run: the run itself may be what fails to read it.
+    let raw = null;
+    const reading = () => {
+        raw ??= readStdin();
+        return raw;
+    };
+    // A signal before the wait installs its own handler. The default disposition
+    // of SIGTERM and SIGINT is to die with nothing on stdout, which Hermes reads
+    // as an allow, and the wait's handler (which withdraws and prints
+    // `hook-interrupted`) exists only from the moment the hook starts waiting.
+    // This guard covers the whole run before and after that stretch; the wait's
+    // 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, hermesInterruptedDirective(signal));
+            }
+            catch {
+                // stdout is gone; the exit code below is the whole verdict.
+            }
+        }
+        process.exit(HERMES_DENY_EXIT);
+    };
+    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 yield* hermesVerdict();
+    }
+    finally {
+        if (waitSeam === null) {
+            owner[HERMES_SIGNAL_OWNER] = ownerBefore;
+            process.off("SIGTERM", onEarlyTerm);
+            process.off("SIGINT", onEarlyInt);
+        }
+    }
+    function* hermesVerdict() {
+        let code;
+        try {
+            code = yield* runHarnessHook(argv, tracked, cwd, reading, adapter, waitSeam);
+        }
+        catch (cause) {
+            // A post-event never blocks: the call already ran (see the post path).
+            if (raw !== null && isHermesPostEvent(raw))
+                return EXIT_OK;
+            if (stdout.length > 0) {
+                // A verdict was already printed; one more object would be unparseable.
+                return HERMES_DENY_EXIT;
+            }
+            return deny(tracked, "hook-io", `the hook failed: ${cause instanceof Error ? cause.message : String(cause)}`, adapter.kind);
+        }
+        const post = raw !== null && isHermesPostEvent(raw);
+        if (post)
+            return code;
+        const blocked = /"action"\s*:\s*"block"/u.test(stdout);
+        if (code === EXIT_OK && stdout.length > 0)
+            return code;
+        if (code === EXIT_OK || !blocked) {
+            if (stdout.length > 0) {
+                // Something that is not a block is already on stdout, and a second
+                // object after it is unparseable stdout, which `fail_closed` blocks and a
+                // build without it allows. The exit code is the verdict that cannot be
+                // misread, so it carries the block.
+                return HERMES_DENY_EXIT;
+            }
+            return deny(tracked, "hook-io", code === EXIT_OK
+                ? "the hook reached no verdict for this call; nothing authorizes it"
+                : `the hook exited ${String(code)} without a verdict; nothing authorizes this call`, adapter.kind);
+        }
+        return HERMES_DENY_EXIT;
+    }
+}
+/** Is this raw Hermes event a `post_tool_call`? Unreadable input is not. */
+function isHermesPostEvent(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return false;
+        return parsed["hook_event_name"] === HERMES_POST_TOOL_EVENT;
+    }
+    catch {
+        return false;
+    }
+}
 // ===========================================================================
 // Dispatch
 // ===========================================================================
@@ -3774,7 +6026,55 @@ function commandHarnessHook(argv, streams, cwd, readStdin, adapter) {
 function defaultStdin() {
     return readFileSync(0, "utf8");
 }
-export function commandHook(argv, streams, cwd, readStdin = defaultStdin) {
+export function commandHook(argv, streams, cwd, readStdin = defaultStdin, 
+/**
+ * APRV-427: where a harness hook's wait begins and ends, for `approval serve`,
+ * which runs the call off its main thread and releases its store lock while
+ * 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) {
@@ -3788,7 +6088,7 @@ export function commandHook(argv, streams, cwd, readStdin = defaultStdin) {
     // 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]);
+        return yield* commandHarnessHook(rest, streams, cwd, readStdin, HARNESS_ADAPTERS[sub], waitSeam);
     }
     if (sub === "classify")
         return commandClassify(rest, streams, cwd);