approval-md 0.3.0 → 0.4.0

package/dist/src/cli/doctor.js

@@ -54,20 +54,23 @@
  * precisely what this command reports, so they are check failures (exit 1).
  */
 import { createServer } from "node:net";
-import { closeSync, existsSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync, } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve as resolvePathSegments } from "node:path";
 import { WEB_DEFAULT_PORT } from "../channels/web.js";
 import { TELEGRAM_DEFAULT_API_BASE, telegramChatEnvFor, telegramTokenEnvFor, } from "../channels/telegram.js";
-import { HUMAN_ACTOR_ENV, checkAttestation, findOrganAttestation, findPathSignOff, latestOrganAttestation, latestPathSignOff, policyBytesHash, resolveHumanActor, } from "../core/attest.js";
+import { HUMAN_ACTOR_ENV, attesterAt, checkAttestation, findOrganAttestation, findPathSignOff, latestOrganAttestation, latestPathSignOff, policyBytesHash, resolveHumanActor, } from "../core/attest.js";
 import { isGateOrganPath, POLICY_EDIT_SUBCLASS, protectedPathClass, } from "../core/command-class.js";
 import { VALUES_INFO_STRING, loadValues } from "../core/values.js";
 import { KEYSTORE_DEFERRED, NON_RESOLVING_RUNNER, envFilePathFor, resolveEnvironment, } from "../core/env-file.js";
 import { readTaskFile } from "../core/frontmatter.js";
+import { derivedDaemonId, resolveDaemonAllowlist, resolveDaemonId, } from "../core/daemon-host.js";
+import { DAEMON_ID_ENV } from "../core/daemon-identity.js";
 import { instanceFindings, instanceHomeFor, instanceIdFor } from "../core/instance.js";
 import { describeOwners, otherOwnersOf, ownedBot } from "../core/channel-owner.js";
 import { checkLogAnchor } from "./log-anchor.js";
 import { checkLogCheckpoints, checkpointPolicyOf } from "../core/checkpoint.js";
-import { payloadStoreCensus } from "../core/payload-census.js";
+import { payloadIntegrity, payloadStoreCensus } from "../core/payload-census.js";
 import { payloadStoreDirFor } from "../core/payload-store.js";
 import { DEFAULT_TASKS_DIR, latestRegistration } from "../core/registration.js";
 import { POLICY_FILENAMES, loadPolicy } from "../core/policy-load.js";
@@ -84,8 +87,12 @@ import { policyWebPort } from "./channel-web.js";
 import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
 import { RESOLVE_DANGLING_COMMAND, lastAdvance, proveDanglingAdvances, } from "../core/advance-cycle.js";
 import { DEFAULT_DARK_WINDOW_MS, reportDarkSessions, } from "../core/dark-session.js";
-import { HARNESS_BINARY, HARNESS_KINDS, installedHarnessVersion, isHarnessKind, readHarnessProvenance, } from "../core/harness-version.js";
-import { git, repoPath, repoRoot } from "./git-scope.js";
+import { HARNESS_BINARY, HARNESS_KINDS, HERMES_FAIL_CLOSED_FLOOR, hermesFailClosedSupport, installedHarnessVersion, installedHarnessVersionRaw, isHarnessKind, readHarnessProvenance, } from "../core/harness-version.js";
+import { git, primaryRoot, repoPath, repoRoot } from "./git-scope.js";
+// APRV-408: the gated tool roster of the `harness-hook-wiring` row is READ from
+// the adapter that answers the calls, never restated here. No new export; the
+// map has been exported since APRV-398.
+import { HARNESS_ADAPTERS } from "./hook.js";
 import { ScanError, checkAttestedPolicyOnMain, checkBuildFreshness, checkMainBehindOrigin, installationRoot, } from "./preflight.js";
 import { publishedState } from "./log-advance.js";
 import { DOCTOR_HELP } from "./help.js";
@@ -248,12 +255,17 @@ function resolvePolicyPath(policyFlag, dir, cwd) {
 function checkAttestationHealth(records, policyPath) {
     const status = checkAttestation(records, policyPath);
     switch (status.status) {
-        case "attested":
+        case "attested": {
+            // APRV-449: WHO set the policy in force, from the verified record at that
+            // seq and never from the file. A hosted tenant reads this row to learn
+            // whether their starting policy is the operator's or their own.
+            const by = attesterAt(records, status.seq);
             return {
                 check: "attestation",
                 status: "pass",
-                detail: `${policyPath} is attested at seq ${status.seq} (sha256 ${status.sha256.slice(0, 12)}…)`,
+                detail: `${policyPath} is attested at seq ${status.seq}${by === null ? "" : ` by ${by}`} (sha256 ${status.sha256.slice(0, 12)}…)`,
             };
+        }
         case "not-attested":
             return {
                 check: "attestation",
@@ -280,6 +292,14 @@ function checkAttestationHealth(records, policyPath) {
 // ---------------------------------------------------------------------------
 // 4. log
 // ---------------------------------------------------------------------------
+/**
+ * A path as one POSIX shell word: bare when it holds only characters no shell
+ * interprets, single-quoted otherwise (`'` closed, escaped and reopened), so a
+ * fix command pasted from a row names the file the row is about.
+ */
+function shellWord(path) {
+    return /^[A-Za-z0-9_./@:+-]+$/.test(path) ? path : `'${path.split("'").join(`'\\''`)}'`;
+}
 /** The chain verdict, in doctor's vocabulary. Reads; never writes. */
 function checkLog(logPath, result) {
     switch (result.status) {
@@ -291,13 +311,31 @@ function checkLog(logPath, result) {
                     ? `${logPath} is empty (an audit trail that has recorded nothing is clean, not missing)`
                     : `${logPath} verifies: ${result.records} record(s), head seq ${result.head.seq} ${result.head.hash.slice(0, 12)}…`,
             };
-        case "torn-tail":
+        case "torn-tail": {
+            const file = shellWord(logPath);
+            const keep = String(result.intactBytes);
+            // What the truncation removes, from the file's own size: verify counts
+            // the tail's DECODED bytes, which overstates a tail holding invalid UTF-8.
+            let drop = result.tornBytes;
+            try {
+                drop = statSync(logPath).size - result.intactBytes;
+            }
+            catch {
+                // Unreadable now: the verify count stands.
+            }
             return {
                 check: "log",
                 status: "fail",
-                detail: `${logPath} ends with an unterminated final line — the signature of a crashed write, not of tampering; records 1..${result.intactThroughSeq} verify clean`,
-                fix: "approval log verify — the full report; nothing here truncates the torn line, because that is a human decision",
+                detail: result.tear === "nul-filled"
+                    ? `${logPath} ends with ${String(result.tornBytes)} NUL byte(s) after record ${String(result.intactThroughSeq)}, the crash-before-writeback signature: the file grew but its data never reached the disk before the machine stopped, so nothing was tampered and whatever was appended there is lost; records 1..${String(result.intactThroughSeq)} verify clean`
+                    : `${logPath} ends with an unterminated line of ${String(result.tornBytes)} byte(s) after record ${String(result.intactThroughSeq)}, the signature of a crashed write (a writer that died mid-line), not of tampering; records 1..${String(result.intactThroughSeq)} verify clean`,
+                // APRV-440: which bytes, exactly. The line still opens with the read,
+                // because truncating is a human decision taken after it, and the
+                // truncation is spelled in `node` because `truncate(1)` is not on
+                // macOS and node is wherever this CLI runs. Doctor truncates nothing.
+                fix: `approval log verify — read the full report; then, if you decide to repair, keep the first ${keep} byte(s) of ${logPath} and drop the final ${String(drop)}: \`node -e "require('fs').truncateSync(process.argv[1], ${keep})" ${file}\`. Nothing here truncates, because that is a human decision`,
             };
+        }
         case "corrupt":
             return {
                 check: "log",
@@ -516,8 +554,12 @@ const PAYLOAD_STORE_WARNING = "the store holds the bytes approvals bind to, keye
  * The probe is a real create-and-remove in the store directory, not a `statSync`
  * mode test: mode bits do not answer the question on a read-only mount, under an
  * ACL, or in a container whose uid mapping differs from the one that made the
- * directory. Nothing is left behind, and no payload file is read, written or
- * verified here.
+ * directory. Nothing is left behind, and no payload file is written here.
+ *
+ * Since APRV-457 the bound payloads are read back and verified (see
+ * {@link payloadDamageCheck}): a store that is writable but holds a torn,
+ * missing or tampered payload a verified record binds fails, each reading with
+ * its own text.
  */
 function checkPayloadStore(logPath, records) {
     const storeDir = payloadStoreDirFor(logPath);
@@ -527,6 +569,14 @@ function checkPayloadStore(logPath, records) {
     }
     catch (cause) {
         if (cause.code === "ENOENT") {
+            // APRV-457: an absent store is only "not created yet" when no verified
+            // record proves the store already held bytes. When one does, the whole
+            // directory is missing under it: the crash signature of a first store
+            // whose directory entry never reached the disk, or a store not carried
+            // with the log. Every such binding reads as lost.
+            const damage = payloadIntegrity(records, storeDir);
+            if (damage.length > 0)
+                return payloadDamageCheck(damage);
             return {
                 check: "payload-store",
                 status: "pass",
@@ -589,12 +639,94 @@ function checkPayloadStore(logPath, records) {
     const residue = census.awaitingRemoval === 0
         ? ""
         : `, ${census.awaitingRemoval} already recorded as pruned and awaiting removal by the daemon`;
+    // APRV-457: the bytes verified records bind, read back. Only a damaged store
+    // changes the row; an intact one reads exactly as it did before.
+    const damage = payloadIntegrity(records, storeDir);
+    if (damage.length > 0)
+        return payloadDamageCheck(damage);
     return {
         check: "payload-store",
         status: "pass",
         detail: `${storeDir} is writable and holds ${files} payload file(s), ${census.pruned} pruned by the log, ${census.orphans} bound to no record${residue}; ${PAYLOAD_STORE_WARNING}`,
     };
 }
+/** At most this many payloads are named per kind; the count covers the rest. */
+const DAMAGE_NAMED = 5;
+function namedDamage(items, describe) {
+    const named = items.slice(0, DAMAGE_NAMED).map(describe).join("; ");
+    const more = items.length > DAMAGE_NAMED ? `; and ${String(items.length - DAMAGE_NAMED)} more` : "";
+    return `${named}${more}`;
+}
+/**
+ * The payload-store row when bound payloads are not intact (APRV-457).
+ *
+ * Two readings, kept apart because they call for opposite reactions:
+ *
+ * - **The crash-before-writeback signature.** A file that is empty or all NUL
+ *   (`torn`), or a file that is absent although its record proves the store
+ *   held it (`lost`). A crash leaves exactly these and nothing else: it can drop
+ *   bytes and names, never write bytes nobody wrote. Before APRV-457 the store
+ *   did not fsync, so a platform kill could keep the (fsynced) record and drop
+ *   its payload. Nothing was tampered; the bytes are gone from this store.
+ * - **Tampering or corruption** (`mismatch`). The file holds at least one
+ *   non-NUL byte and does not verify. That is not the pure crash shape, so it is never
+ *   read as one (a partial writeback, valid prefix and NUL tail, lands here too: the stricter reading), and its fix moves the file aside for investigation.
+ *
+ * The torn reading cannot swallow a tampered file that still carries content:
+ * it requires every byte to be NUL. A file someone zeroed by hand reads as torn,
+ * which is honest, because its bytes say nothing either way and the material is
+ * lost either way. A partially written payload (valid prefix, NUL tail) is
+ * reported as a mismatch, the stricter of the two readings.
+ *
+ * Doctor moves, restores and deletes nothing; every fix is the operator's.
+ */
+function payloadDamageCheck(damage) {
+    const torn = damage.filter((item) => item.kind === "torn");
+    const lost = damage.filter((item) => item.kind === "lost");
+    const mismatch = damage.filter((item) => item.kind === "mismatch");
+    const unreadable = damage.filter((item) => item.kind === "unreadable");
+    const short = (hash) => `${hash.slice(0, 12)}…`;
+    const parts = [];
+    if (mismatch.length > 0) {
+        parts.push(`${String(mismatch.length)} payload(s) a verified record binds hold bytes that do not hash to their name and are NOT the crash signature (that is an empty or all-NUL file; a partial writeback can also leave a valid prefix with a NUL tail, so the stricter reading applies until shown otherwise): treat them as tampered or corrupted (${namedDamage(mismatch, (item) => `${short(item.hash)} bound at seq ${String(item.seq)}`)}); every read re-verifies, so no channel renders them`);
+    }
+    if (torn.length > 0) {
+        parts.push(`${String(torn.length)} payload(s) a verified record binds are empty or NUL-filled, the crash-before-writeback signature: the name reached the disk and the bytes did not, so nothing was tampered and the material is lost from this store (${namedDamage(torn, (item) => `${short(item.hash)} bound at seq ${String(item.seq)}, ${String(item.bytes)} NUL byte(s)`)})`);
+    }
+    if (lost.length > 0) {
+        parts.push(`${String(lost.length)} payload(s) are missing although the record that bound them proves the store held them (${namedDamage(lost, (item) => `${short(item.hash)}, ${item.event} at seq ${String(item.seq)}`)}): the crash-before-writeback signature when this store has always lived beside this log (the name never reached the disk), or a store that was not carried with the log`);
+    }
+    if (unreadable.length > 0) {
+        parts.push(`${String(unreadable.length)} payload(s) a verified record binds could not be read (${namedDamage(unreadable, (item) => `${short(item.hash)} bound at seq ${String(item.seq)}: ${item.detail}`)})`);
+    }
+    // One command leads the fix, for the reading that matters most: suspected
+    // tampering first, then a torn file (which must be moved before a copy can go
+    // back), then a lost one, then an unreadable one.
+    const restore = (hash, path) => `restore ${hash}.json from wherever else it lives (another checkout, a backup, the git history of the store) once \`approval payload hash\` prints ${hash} for the copy, and put it at ${path}; the log records the binding and never the material, so nothing rebuilds it`;
+    let fix;
+    const firstMismatch = mismatch[0];
+    const firstTorn = torn[0];
+    const firstLost = lost[0];
+    if (firstMismatch !== undefined) {
+        fix = `mv ${shellWord(firstMismatch.path)} ${shellWord(`${firstMismatch.path}.suspect`)} — move each payload that does not verify aside (do not delete it), find out what wrote it, and ${restore(firstMismatch.hash, firstMismatch.path)}`;
+    }
+    else if (firstTorn !== undefined) {
+        fix = `mv ${shellWord(firstTorn.path)} ${shellWord(`${firstTorn.path}.torn`)} — move each torn payload aside (the nonmanual intake refuses to replace a file that does not verify), then ${restore(firstTorn.hash, firstTorn.path)}`;
+    }
+    else if (firstLost !== undefined) {
+        fix = `approval payload hash <copy> — ${restore(firstLost.hash, firstLost.path)}`;
+    }
+    else {
+        const first = unreadable[0];
+        fix = `chmod u+r ${shellWord(first.path)} — make each payload readable by the user running approval, check its ownership and the disk, then run approval doctor again`;
+    }
+    return {
+        check: "payload-store",
+        status: "fail",
+        detail: `${parts.join("; ")}; ${PAYLOAD_STORE_WARNING}`,
+        fix: `${fix}. Doctor moves, restores and deletes nothing`,
+    };
+}
 // ---------------------------------------------------------------------------
 // 7b. the verified-head snapshot (APRV-188)
 // ---------------------------------------------------------------------------
@@ -1698,6 +1830,80 @@ function checkKeychainScope(logPath, load) {
     };
 }
 // ---------------------------------------------------------------------------
+// 32. daemon-identity (APRV-383)
+// ---------------------------------------------------------------------------
+/**
+ * Which daemon would write here, and whether the attested policy admits it
+ * (APRV-383).
+ *
+ * The sibling of `keychain-scope` above, one layer along: that row answers
+ * "whose CREDENTIALS is this instance using", this one answers "whose NAME would
+ * this instance's daemon write onto every record it appends". Both derive from the
+ * same instance id, which is the point — an operator comparing `daemon-3f2a9c11`
+ * in a record against `approval-tg-token-3f2a9c11` in `.approval/env` is looking
+ * at one gate.
+ *
+ * ## The verdict rule
+ *
+ * - **FAIL** for an `APPROVAL_DAEMON_ID` in this shell that is not a usable id.
+ *   That is a broken launch environment wherever it is read from: a daemon started
+ *   from this shell would refuse every append, and the repair is one variable.
+ * - **SKIP**, named and loud, for an id the policy's `daemons` list does not
+ *   admit. Deliberately not a fail, and the reason is the one `keychain-scope`
+ *   states for the legacy item: under the deployment this key exists FOR, the
+ *   tenant's policy names a daemon id belonging to somebody else's machine, so a
+ *   red row here would be red on every tenant's laptop forever, and a red row on
+ *   every installation is a red row people learn to skip past. The line says
+ *   plainly that a daemon started HERE would write nothing.
+ * - **PASS** when the list names this id, and when there is no list at all, which
+ *   is every installation that never adopts the key.
+ *
+ * It reads a policy and an environment variable's SHAPE. No value is printed on
+ * any path, because the only value involved is an id, which the policy and the log
+ * both carry in the open.
+ */
+function checkDaemonIdentity(logPath, records, load) {
+    const resolved = resolveDaemonId(logPath);
+    if (!resolved.ok) {
+        return {
+            check: "daemon-identity",
+            status: "fail",
+            detail: `${resolved.message}. A daemon started from this shell would be refused \`daemon-id-invalid\` on every append, so it would read, render and report while writing nothing`,
+            fix: `unset ${DAEMON_ID_ENV} to use the derived id ${derivedDaemonId(logPath)}, or set it to a usable one: lowercase letters, digits, \`.\`, \`-\` and \`_\`, starting with a letter or digit`,
+        };
+    }
+    const head = `a daemon run against ${instanceHomeFor(logPath)} writes \`daemon: ${resolved.id}\` onto every record it appends (${resolved.source === "environment" ? `declared in ${DAEMON_ID_ENV}` : "derived from this instance, the same id the keychain-scope row names"})`;
+    const allowlist = resolveDaemonAllowlist(records, load);
+    if (!allowlist.ok) {
+        return {
+            check: "daemon-identity",
+            status: "pass",
+            detail: `${head}. No \`daemons\` allowlist is in force (${allowlist.detail}), so any daemon may write, exactly as before the key existed`,
+        };
+    }
+    const allowed = allowlist.allowed;
+    if (allowed === null) {
+        return {
+            check: "daemon-identity",
+            status: "pass",
+            detail: `${head}. The attested policy lists no allowed daemon ids, so any daemon may write — which is what every policy written before this key looked like`,
+        };
+    }
+    if (!allowed.includes(resolved.id)) {
+        return {
+            check: "daemon-identity",
+            status: "skip",
+            detail: `${head}. The attested policy's \`daemons\` list admits ${allowed.length === 0 ? "no daemon at all" : allowed.join(", ")}, so a daemon started HERE would be refused \`daemon-not-allowed\` on every append and would write nothing. Expected where the daemon for this log runs on another machine; wrong if that daemon is meant to be this one`,
+            fix: `add ${resolved.id} to \`daemons\` and re-attest the policy, or run the daemon whose id the list already names`,
+        };
+    }
+    return {
+        check: "daemon-identity",
+        status: "pass",
+        detail: `${head}, and the attested policy's \`daemons\` list admits it (${allowed.join(", ")}). Being listed grants nothing beyond the ability to write: no verdict, budget, floor, draw or token reads this id`,
+    };
+}
+// ---------------------------------------------------------------------------
 // 12. log-drift (APRV-125)
 // ---------------------------------------------------------------------------
 /**
@@ -1935,28 +2141,180 @@ function checkAdvanceCadence(logPath, records) {
 // ---------------------------------------------------------------------------
 /** Where Claude Code keeps the hook registration a human commits. */
 const CLAUDE_SETTINGS = join(".claude", "settings.json");
-/** Does any `hooks.<event>` entry run this CLI's harness hook? */
-function registersApprovalHook(hooks, event) {
+/** This runtime's own Claude Code hook adapter, the roster both rows read. */
+const CLAUDE_HOOK_ADAPTER = HARNESS_ADAPTERS["claude-code"];
+/**
+ * The tools a protected-path write can arrive as, DERIVED (APRV-408).
+ *
+ * Until APRV-408 this was a hand list, `["Edit", "Write", "Bash"]`, and it had
+ * drifted: the adapter gates `Bash` plus `Edit`, `Write`, `MultiEdit` and
+ * `NotebookEdit`, so a matcher of `Bash|Edit|Write` passed the wiring row while
+ * a `MultiEdit` to a protected path reached the file system unclassified. Two
+ * lists of the same fact is one list too many, so there is now one: the
+ * adapter's, because the adapter is what actually answers the call.
+ */
+function gatedClaudeTools() {
+    return [CLAUDE_HOOK_ADAPTER.shellTool, ...CLAUDE_HOOK_ADAPTER.fileTools];
+}
+/**
+ * Anything that makes a command line mean something other than its own words.
+ *
+ * Deliberately generous. A command carrying any of these is reported as
+ * unresolved rather than parsed on a best guess, because the question this
+ * parse answers — which checkout does the gate resolve its policy and log from
+ * — has no safe approximation. Fail closed: SPEC §11.
+ */
+const SHELL_OPAQUE = /[$`\\;&|<>(){}\r\n*?[\]]/u;
+/**
+ * The `hook claude-code` verb named anywhere in a command, however wrapped.
+ *
+ * The VERB and not the executable, because the executable is exactly what a
+ * wrapper hides: `$(which approval) hook claude-code` and `bash -lc "approval
+ * hook claude-code …"` both name this handler and neither carries the word
+ * `approval` in a position any parse could trust. Naming the verb is what makes
+ * such an entry `unresolved` (reported, never a pass) instead of `foreign`
+ * (invisible, which is how a wrapped handler would read as "no hook
+ * registered"). Another harness's entry parked in this file — `approval hook
+ * cursor` — does not name it, and stays foreign.
+ */
+const CLAUDE_HOOK_MENTION = /\bhook\s+claude-code\b/u;
+/**
+ * Split a command line into words, honouring simple quotes.
+ *
+ * Only ever reached for a command {@link SHELL_OPAQUE} has already cleared, so
+ * there is no expansion, no escape and no operator left to get wrong; `null` is
+ * an unclosed quote.
+ */
+function shellWords(command) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let started = false;
+    for (const character of command) {
+        if (quote !== null) {
+            if (character === quote)
+                quote = null;
+            else
+                current += character;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            started = true;
+            continue;
+        }
+        if (/\s/u.test(character)) {
+            if (started)
+                tokens.push(current);
+            current = "";
+            started = false;
+            continue;
+        }
+        current += character;
+        started = true;
+    }
+    if (quote !== null)
+        return null;
+    if (started)
+        tokens.push(current);
+    return tokens;
+}
+/**
+ * Read a registered command as an `approval hook claude-code` invocation
+ * (APRV-408).
+ *
+ * Modelled on {@link isDirectCodexHookCommand}, which the Codex rows have had
+ * since APRV-313, and which the Claude Code rows had no counterpart of: they
+ * matched the substring `approval hook`, so a wrapper script, a different
+ * harness's entry and a handler bound to a checkout that does not exist on this
+ * machine all read the same. Tolerant of flag order and of `--as`/`--timeout`
+ * being absent, because those do not decide anything this row reports; strict
+ * about the three facts that do — the executable is `approval`, the verb is
+ * `hook claude-code`, and the `--dir` is whatever it is.
+ */
+function parseClaudeHookCommand(command) {
+    const mentioned = CLAUDE_HOOK_MENTION.test(command);
+    const unreadable = (reason) => mentioned ? { kind: "unresolved", reason } : { kind: "foreign" };
+    if (SHELL_OPAQUE.test(command)) {
+        return unreadable("it carries shell metacharacters, so what it runs depends on a shell rather than on these words");
+    }
+    const tokens = shellWords(command);
+    if (tokens === null)
+        return unreadable("its quoting does not close");
+    const executable = tokens[0] ?? "";
+    if (tokens[1] !== "hook" || tokens[2] !== "claude-code") {
+        // `approval hook cursor` in this file is another harness's entry, and a
+        // wrapper name with the verb buried inside it is ours and unreadable.
+        return unreadable("its first words are not `approval hook claude-code`");
+    }
+    if (basename(executable) !== "approval") {
+        return unreadable(`its executable ${JSON.stringify(executable)} is not \`approval\``);
+    }
+    if (executable.includes("/") && !isAbsolute(executable)) {
+        return unreadable(`its executable ${JSON.stringify(executable)} is a relative path, so which binary runs depends on the working directory`);
+    }
+    let dir = null;
+    for (let index = 3; index < tokens.length; index += 1) {
+        const token = tokens[index] ?? "";
+        if (token.startsWith("--dir=")) {
+            dir = token.slice("--dir=".length);
+            continue;
+        }
+        if (token !== "--dir")
+            continue;
+        const value = tokens[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            return unreadable("its `--dir` flag names no value");
+        }
+        dir = value;
+        index += 1;
+    }
+    return { kind: "handler", dir };
+}
+/**
+ * Every `hooks.<event>` entry of this file that is OURS (APRV-408).
+ *
+ * One reading for both harness rows, so `harness-hook-outcomes` and
+ * `harness-hook-wiring` cannot disagree about which entries they are talking
+ * about. An unresolved entry counts as ours here — it names the verb, and a
+ * command this file cannot read is a reason to report less confidently rather
+ * than to report that no hook is registered.
+ */
+function claudeHookEntries(hooks, event) {
     if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks))
-        return false;
-    const matchers = hooks[event];
-    if (!Array.isArray(matchers))
-        return false;
-    for (const matcher of matchers) {
-        if (typeof matcher !== "object" || matcher === null)
+        return [];
+    const groups = hooks[event];
+    if (!Array.isArray(groups))
+        return [];
+    const found = [];
+    for (const group of groups) {
+        if (typeof group !== "object" || group === null)
             continue;
-        const entries = matcher["hooks"];
+        const entries = group["hooks"];
         if (!Array.isArray(entries))
             continue;
+        const pattern = group["matcher"];
         for (const entry of entries) {
             if (typeof entry !== "object" || entry === null)
                 continue;
             const command = entry["command"];
-            if (typeof command === "string" && /\bapproval hook\b/u.test(command))
-                return true;
+            if (typeof command !== "string")
+                continue;
+            const parse = parseClaudeHookCommand(command);
+            if (parse.kind === "foreign")
+                continue;
+            found.push({
+                matcher: typeof pattern === "string" ? pattern : "",
+                command,
+                parse,
+            });
         }
     }
-    return false;
+    return found;
+}
+/** Does any `hooks.<event>` entry run this CLI's Claude Code hook? */
+function registersApprovalHook(hooks, event) {
+    return claudeHookEntries(hooks, event).length > 0;
 }
 /**
  * Is the harness registered for the event that reports outcomes (APRV-145)?
@@ -1972,6 +2330,12 @@ function registersApprovalHook(hooks, event) {
  * `policy.core` in this taxonomy — a file that configures the gate is part of
  * the gate — so the repair is a line for a human to commit, printed by
  * `approval instructions hook`.
+ *
+ * Which entries are OURS is read by {@link claudeHookEntries} since APRV-408,
+ * the same reading `harness-hook-wiring` uses, so the two rows cannot come
+ * apart on the question. Before that this row matched the substring `approval
+ * hook`, which counted another harness's entry parked in Claude Code's own
+ * settings file as a post-execution reporter for Claude Code.
  */
 function checkHarnessOutcomes(dir) {
     const check = "harness-hook-outcomes";
@@ -2004,53 +2368,138 @@ function checkHarnessOutcomes(dir) {
         return {
             check,
             status: "skip",
-            detail: `${path} registers no \`approval hook\` entry, so this checkout is not gated by the harness hook at all`,
+            detail: `${path} registers no \`approval hook claude-code\` entry, so this checkout is not gated by the harness hook at all`,
         };
     }
     if (!post) {
         return {
             check,
             status: "fail",
-            detail: `${path} registers \`approval hook\` for PreToolUse and not for PostToolUse, so no tool call ever reports an outcome: every harness execution.started stays delegated, and the loop escalation of SPEC.md §10.2 cannot accrue on this path`,
+            detail: `${path} registers \`approval hook claude-code\` for PreToolUse and not for PostToolUse, so no tool call ever reports an outcome: every harness execution.started stays delegated, and the loop escalation of SPEC.md §10.2 cannot accrue on this path`,
             fix: "approval hook claude-code --help — prints the PostToolUse entry to add, which a human commits (.claude/settings.json is policy.core)",
         };
     }
     return {
         check,
         status: "pass",
-        detail: `${path} registers \`approval hook\` for the ${pre ? "pre-execution and " : ""}post-execution event, so tool call outcomes reach the log and loop escalation can accrue`,
+        detail: `${path} registers \`approval hook claude-code\` for the ${pre ? "pre-execution and " : ""}post-execution event, so tool call outcomes reach the log and loop escalation can accrue`,
     };
 }
 // ---------------------------------------------------------------------------
 // harness hook wiring in THIS worktree (APRV-151)
 // ---------------------------------------------------------------------------
-/** The tool names a protected-path write can arrive as. */
-const GATED_TOOLS = ["Edit", "Write", "Bash"];
-/** The `matcher` strings of every `approval hook` entry registered for `event`. */
-function approvalHookMatchers(hooks, event) {
-    if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks))
-        return [];
-    const matchers = hooks[event];
-    if (!Array.isArray(matchers))
-        return [];
-    const found = [];
-    for (const matcher of matchers) {
-        if (typeof matcher !== "object" || matcher === null)
+/** The repair every wiring verdict but the two absences points at. */
+const HOOK_ENTRY_FIX = "approval instructions hook — prints the PreToolUse entry a human commits";
+/** A tool name as a `matcher` may spell it: no regex syntax anywhere in it. */
+const MATCHER_TOOL_NAME = /^[A-Za-z0-9_-]+$/u;
+/**
+ * The tools a `matcher` names, or `"pattern"` when it is not a plain list
+ * (APRV-408).
+ *
+ * Claude Code treats `matcher` as a regular expression, and this file will not
+ * evaluate one: a regex is answered by matching it against candidate strings,
+ * and the candidates here are "every tool name that exists", which is not a set
+ * this runtime holds. So the only shape read is the documented one — tool names
+ * joined by `|` — and everything else is reported as unresolved coverage rather
+ * than guessed at. An empty matcher is `"pattern"` too: it selects every tool
+ * in Claude Code, which is a coverage claim this row would rather see written
+ * down than infer.
+ *
+ * Nothing here compiles the pattern, so a hostile one (`(a+)+$` and its kin)
+ * costs one anchored character-class test per alternative and cannot make
+ * `doctor` hang.
+ */
+function matcherTools(pattern) {
+    if (pattern.trim().length === 0)
+        return "pattern";
+    const parts = pattern.split("|");
+    if (parts.some((part) => !MATCHER_TOOL_NAME.test(part)))
+        return "pattern";
+    return parts;
+}
+/** `realpathSync` that answers the path itself when it cannot be resolved. */
+function realOrSelf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * Which checkout the registered handler resolves policy and log from
+ * (APRV-408).
+ *
+ * The committed entry in this repository hardcodes one absolute `--dir`, which
+ * is correct on the machine it was written on and names a directory that does
+ * not exist in a clone anywhere else; nothing checked. A handler bound to
+ * another checkout is not a weaker gate, it is a DIFFERENT gate: another
+ * policy, another log, another open window. That is the one thing this row
+ * fails on.
+ *
+ * `primaryRoot` first and `repoRoot` as the fallback, because the documented
+ * `--dir` names the PRIMARY checkout: in a linked worktree the two differ, and
+ * the primary is the one the gate must answer from.
+ */
+function describeBinding(entries, dir, fallbackRoot) {
+    const primary = primaryRoot(dir);
+    const expected = primary ?? fallbackRoot;
+    const expectedName = primary === null ? "repository root" : "primary root";
+    const rank = { pass: 0, skip: 1, fail: 2 };
+    const reports = [];
+    for (const entry of entries) {
+        const parse = entry.parse;
+        // `claudeHookEntries` keeps no foreign entry, and the narrowing is written
+        // out anyway: a reader of this loop should not have to hold that invariant.
+        if (parse.kind === "foreign")
             continue;
-        const entries = matcher["hooks"];
-        if (!Array.isArray(entries))
+        if (parse.kind === "unresolved") {
+            reports.push({
+                status: "skip",
+                clause: `BINDING UNRESOLVED: the PreToolUse command ${JSON.stringify(entry.command)} cannot be read as an \`approval hook claude-code\` invocation (${parse.reason}), so which checkout it would gate is not established here — and unresolved is never a pass.`,
+            });
+            continue;
+        }
+        const declared = parse.dir;
+        if (declared === null) {
+            reports.push({
+                status: "skip",
+                clause: `BINDING UNSTATED: the PreToolUse command names no \`--dir\`, so the hook resolves its policy and log from wherever the harness happens to run it (APRV-101) rather than from a directory this row can read. The ${expectedName} here is ${expected ?? "unknown to git"}.`,
+            });
             continue;
-        for (const entry of entries) {
-            if (typeof entry !== "object" || entry === null)
-                continue;
-            const command = entry["command"];
-            if (typeof command !== "string" || !/\bapproval hook\b/u.test(command))
-                continue;
-            const pattern = matcher["matcher"];
-            found.push(typeof pattern === "string" ? pattern : "");
         }
+        if (!isAbsolute(declared)) {
+            reports.push({
+                status: "skip",
+                clause: `BINDING RELATIVE: the PreToolUse command binds \`--dir ${declared}\`, which names a different directory from every working directory it could be launched in. The ${expectedName} here is ${expected ?? "unknown to git"}.`,
+            });
+            continue;
+        }
+        if (expected === null) {
+            reports.push({
+                status: "skip",
+                clause: `BINDING UNCHECKED: the PreToolUse command binds \`--dir ${declared}\`, and git could not say what checkout ${dir} belongs to, so the two cannot be compared here.`,
+            });
+            continue;
+        }
+        if (realOrSelf(declared) !== realOrSelf(expected)) {
+            reports.push({
+                status: "fail",
+                clause: `MISBOUND: the PreToolUse command binds \`--dir ${declared}\`, and this checkout's ${expectedName} is ${expected}. A hook answering from another checkout answers another checkout's policy, log and open window, so a call gated here is not gated by the gate a reader of this repository is looking at.`,
+            });
+            continue;
+        }
+        reports.push({
+            status: "pass",
+            clause: `BOUND to ${expected}, this checkout's ${expectedName}, by the \`--dir\` the PreToolUse command carries.`,
+        });
     }
-    return found;
+    if (reports.length === 0) {
+        return { status: "skip", clause: "BINDING UNRESOLVED: no PreToolUse command to read." };
+    }
+    const status = reports.reduce((worst, report) => (rank[report.status] > rank[worst] ? report.status : worst), "pass");
+    const clauses = [...new Set(reports.map((report) => report.clause))];
+    return { status, clause: clauses.join(" ") };
 }
 /**
  * Does the settings file THIS worktree carries register the pre-execution hook
@@ -2074,11 +2523,25 @@ function approvalHookMatchers(hooks, event) {
  * CI-side, over the committed log, in `core/protected-path-guard.ts`: it does
  * not trust session wiring, and this row does not claim to establish it.
  *
- * Advisory, so it never fails the run. Doctor reads and never writes; the file
- * is `policy.edit` and its repair is a line for a human to commit.
+ * Advisory, so it never fails the run — with the single exception APRV-408
+ * added: a handler POSITIVELY bound to a different checkout. That is not a
+ * weaker report of the same gate, it is a statement that the entry on disk
+ * answers from somewhere else, which this row can establish from the file
+ * alone. Everything else it learned in APRV-408 only ADDS lines from disk
+ * facts: the gated roster comes from the adapter rather than a hand list, the
+ * read tools the adapter declares and the matcher leaves out are named as the
+ * documented default they are, and a matcher tool the adapter does not handle
+ * is named as the `allow` it will actually receive. None of those feeds a
+ * verdict, and none of them asks the session anything about itself (SPEC §11:
+ * a self-reported field never reduces scrutiny, and this row reads no
+ * self-report at all).
+ *
+ * Doctor reads and never writes; the file is `policy.core` and its repair is a
+ * line for a human to commit.
  */
 function checkHarnessWiring(dir) {
     const check = "harness-hook-wiring";
+    const gated = gatedClaudeTools();
     const root = repoRoot(dir);
     const where = root === null ? dir : root;
     const path = join(where, CLAUDE_SETTINGS);
@@ -2112,29 +2575,72 @@ function checkHarnessWiring(dir) {
     const hooks = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
         ? parsed["hooks"]
         : null;
-    const matchers = approvalHookMatchers(hooks, "PreToolUse");
-    if (matchers.length === 0) {
+    const entries = claudeHookEntries(hooks, "PreToolUse");
+    if (entries.length === 0) {
         return {
             check,
             status: "skip",
-            detail: `NOT WIRED: ${path} registers no \`approval hook\` entry for PreToolUse, so a protected-path Edit, Write or Bash call in this checkout reaches the file system unclassified.`,
-            fix: "approval instructions hook — prints the PreToolUse entry a human commits",
+            detail: `NOT WIRED: ${path} registers no \`approval hook claude-code\` entry for PreToolUse, so a protected-path write arriving through ${gated.join(", ")} in this checkout reaches the file system unclassified.`,
+            fix: HOOK_ENTRY_FIX,
         };
     }
-    const covered = GATED_TOOLS.filter((tool) => matchers.some((pattern) => pattern.length === 0 || pattern.split("|").includes(tool)));
-    const missing = GATED_TOOLS.filter((tool) => !covered.includes(tool));
+    const matchers = entries.map((entry) => entry.matcher);
+    const named = new Set();
+    const patterns = [];
+    for (const matcher of matchers) {
+        const tools = matcherTools(matcher);
+        if (tools === "pattern") {
+            patterns.push(matcher);
+            continue;
+        }
+        for (const tool of tools)
+            named.add(tool);
+    }
+    const binding = describeBinding(entries, dir, root);
+    const wired = `${path} registers \`approval hook claude-code\` for PreToolUse with matcher ${JSON.stringify(matchers.join(", "))}`;
+    const notProof = `This is the file being present, NOT proof this session loaded it — the APRV-151 bypasses happened in worktrees carrying exactly this entry. The check that does not trust session wiring is the CI-side grant cross-check over the committed log, which asks whether the CHANGE was granted rather than whether the path ever was (APRV-202).`;
+    // A matcher this file will not read leaves every coverage question open, so
+    // the roster, read-tool and passthrough lines are withheld rather than
+    // computed against a set that may be incomplete. The binding is independent
+    // of the matcher and is still reported (and can still fail).
+    if (patterns.length > 0) {
+        return {
+            check,
+            status: binding.status === "fail" ? "fail" : "skip",
+            detail: `MATCHED BY PATTERN: ${wired}. ${patterns
+                .map((pattern) => JSON.stringify(pattern))
+                .join(" and ")} is not a plain \`|\`-joined list of tool names, and this row does not evaluate a regular expression, so which of ${gated.join(", ")} it covers is not resolved here. ${binding.clause} ${notProof}`,
+            fix: HOOK_ENTRY_FIX,
+        };
+    }
+    const missing = gated.filter((tool) => !named.has(tool));
     if (missing.length > 0) {
         return {
             check,
-            status: "skip",
-            detail: `NOT WIRED for every tool: ${path} registers \`approval hook\` for PreToolUse with matcher ${JSON.stringify(matchers.join(", "))}, which does not cover ${missing.join(", ")}. A protected-path write arriving through ${missing[0]} is never classified.`,
-            fix: "approval instructions hook — prints the PreToolUse entry a human commits",
+            status: binding.status === "fail" ? "fail" : "skip",
+            detail: `NOT WIRED for every tool: ${wired}, which does not cover ${missing.join(", ")}. This runtime's Claude Code adapter gates ${gated.join(", ")}, so a protected-path write arriving through ${missing[0]} is never classified. ${binding.clause}`,
+            fix: HOOK_ENTRY_FIX,
         };
     }
+    // Informational, both of them, and neither is ever a verdict.
+    const held = CLAUDE_HOOK_ADAPTER.readTools.filter((tool) => !named.has(tool));
+    const readLine = held.length === 0
+        ? ""
+        : ` READ TOOLS HELD BY DESIGN: the adapter also knows ${held.join(", ")}, and the matcher leaves ${held.length === 1 ? "it" : "them"} out, so a read is answered without reaching the gate. That is the documented default rather than a gap — see "The read scope" in docs/claude-code-hook.md, where the \`Bash|Edit|Write|MultiEdit|NotebookEdit|Read|Glob|Grep\` matcher is printed and deliberately left out of the installed one, because a read is the most frequent tool call a session makes and every matched call is a Node process start. This line never fails this row.`;
+    const handled = new Set([
+        ...gated,
+        ...CLAUDE_HOOK_ADAPTER.readTools,
+        ...(CLAUDE_HOOK_ADAPTER.passThroughTools ?? []),
+    ]);
+    const unhandled = [...named].filter((tool) => !handled.has(tool));
+    const passthroughLine = unhandled.length === 0
+        ? ""
+        : ` MATCHED AND NOT CLASSIFIED: ${unhandled.join(", ")} ${unhandled.length === 1 ? "is" : "are"} in the matcher and this runtime's Claude Code adapter handles ${unhandled.length === 1 ? "it" : "them"} as neither a shell, file nor read tool, so every such call spawns the hook and is answered \`allow\` with "is not a gated tool". The cost is real and the coverage is not.`;
     return {
         check,
-        status: "pass",
-        detail: `WIRED on disk: ${path} registers \`approval hook\` for PreToolUse over ${GATED_TOOLS.join(", ")}. This is the file being present, NOT proof this session loaded it — the APRV-151 bypasses happened in worktrees carrying exactly this entry. The check that does not trust session wiring is the CI-side grant cross-check over the committed log, which asks whether the CHANGE was granted rather than whether the path ever was (APRV-202).`,
+        status: binding.status,
+        detail: `WIRED on disk: ${path} registers \`approval hook claude-code\` for PreToolUse over ${gated.join(", ")}, the tools this runtime's own adapter gates. ${binding.clause}${readLine}${passthroughLine} ${notProof}`,
+        ...(binding.status === "pass" ? {} : { fix: HOOK_ENTRY_FIX }),
     };
 }
 /** The project-local Codex hook files doctor can observe without asking Codex. */
@@ -2250,10 +2756,138 @@ export function checkCodexHookWiring(dir) {
 // ---------------------------------------------------------------------------
 /** The Cursor counterpart of {@link CLAUDE_SETTINGS}. */
 const CURSOR_HOOKS = join(".cursor", "hooks.json");
-/** Where a harness hook registration can be written, one file per harness. */
-const HARNESS_SETTINGS = [CLAUDE_SETTINGS, CURSOR_HOOKS, CODEX_HOOKS];
-/** `approval hook <kind>` inside a command string, whichever file shape holds it. */
-const HOOK_COMMAND = /\bapproval["']?\s+hook\s+(claude-code|cursor|codex)\b/u;
+/**
+ * The environment variable Hermes Agent resolves its own configuration root
+ * from, and the default it falls back to (APRV-398).
+ *
+ * Read here for ONE purpose: to know where to look for a registration this
+ * checkout cannot hold. Hermes documents no project-local configuration
+ * directory, so a repository-relative search for a Hermes hook would be empty on
+ * every machine and the row would never be able to say anything true.
+ *
+ * Reading an environment variable is acceptable here in the narrow way it is
+ * acceptable in `sandboxRequirement`: it moves where a DIAGNOSTIC looks, and the
+ * row it feeds can only SKIP when it finds nothing and only ADD a line when it
+ * finds something. Nothing an agent can set makes a red line go away, which is
+ * the only property §11.1 invariant 4 asks of a self-reported input.
+ */
+const HERMES_HOME_ENV = "HERMES_HOME";
+const HERMES_HOME_DEFAULT = ".hermes";
+/**
+ * Where each harness's `approval hook` registration can be written.
+ *
+ * A `Record<HarnessKind, …>` since APRV-398, and the type is the point, exactly
+ * as it is for `HARNESS_ADAPTERS`: a kind added to {@link HARNESS_KINDS} with no
+ * entry here fails to compile, and `tests/harness-enum.test.ts` pins the keys
+ * set-equal to that list. Before this it was a flat array of three paths and a
+ * regex naming three kinds, so `grok` and `muse` shipped adapters that this row
+ * could not see — the same class of miss APRV-358 was filed for, in the one
+ * place APRV-358 did not reach.
+ *
+ * An empty list is a statement rather than a gap, and `codex` has one on
+ * purpose: `.codex/hooks.json` is already read by the Codex-specific rows above
+ * ({@link CODEX_HOOKS}), and this list is consulted by `registeredHarnesses`,
+ * whose behaviour for the three harnesses that were already in it must not
+ * change by a byte in this task. Codex is therefore listed with the file it
+ * always had and nothing new.
+ */
+export const HARNESS_SETTINGS = {
+    "claude-code": [{ file: CLAUDE_SETTINGS }],
+    cursor: [{ file: CURSOR_HOOKS }],
+    codex: [{ file: CODEX_HOOKS }],
+    // APRV-243: Grok Build installs a PreToolUse entry per file under
+    // `.grok/hooks/`, so the directory is scanned rather than one name guessed.
+    // It also READS `.claude/settings.json` and `.cursor/hooks.json` for
+    // compatibility, and both of those are already scanned above; a Grok session
+    // hosted by this repository's claude-code entry is the hazard
+    // `docs/grok-hook.md` opens with, not a registration this row should claim.
+    grok: [{ dir: join(".grok", "hooks") }],
+    // APRV-350, observed: the installed build reads `.muse/hooks.json`.
+    // `.muse/settings.json` is listed for the reason the classifier lists it —
+    // Meta documents a user-level `settings.json` `hooks` block, so a
+    // project-level copy would be the same organ under a second name — and an
+    // entry for a file Muse does not read costs a miss rather than a false row.
+    muse: [{ file: join(".muse", "hooks.json") }, { file: join(".muse", "settings.json") }],
+    // APRV-398: not in the checkout at all. See {@link HERMES_HOME_ENV}.
+    hermes: [
+        { home: "hermes", file: "config.yaml", text: true },
+        { home: "hermes", file: "config.yml", text: true },
+    ],
+};
+/**
+ * `approval hook <kind>` inside a command string, whichever file shape holds it.
+ *
+ * DERIVED from {@link HARNESS_KINDS} since APRV-398 rather than spelled, so a
+ * new adapter cannot ship with the pattern left behind — which is what happened
+ * to `grok` and `muse`. Longest alternative first: the alternation is tried left
+ * to right, and a kind that is a prefix of another kind would otherwise match
+ * the shorter spelling and leave the rest of the name outside the capture.
+ */
+const HOOK_COMMAND = new RegExp(`\\bapproval["']?\\s+hook\\s+(${[...HARNESS_KINDS]
+    .sort((left, right) => right.length - left.length)
+    .join("|")})\\b`, "u");
+/**
+ * The places {@link registeredHarnesses} looked, for the row that found nothing.
+ *
+ * Every location of every kind, in kind order, so the line a reader gets names
+ * the file they have to write rather than three of the six. A home-resolved
+ * location is printed with its `$HERMES_HOME/` prefix rather than expanded: the
+ * expansion is this machine's answer, and the instruction is the general one.
+ */
+function harnessSettingNames() {
+    return HARNESS_KINDS.flatMap((kind) => HARNESS_SETTINGS[kind].map((location) => {
+        const name = location.file ?? `${location.dir ?? "?"}/`;
+        return location.home === "hermes" ? `$HERMES_HOME/${name}` : name;
+    })).join(" or ");
+}
+/**
+ * A fresh copy of {@link HOOK_COMMAND}, for the suite that pins it (APRV-398).
+ *
+ * A function rather than the constant, so a caller cannot carry state into this
+ * module's own matching: the pattern is not global today, and a test that shared
+ * the object would silently break on the day somebody adds a flag to it.
+ */
+export function hookCommandPattern() {
+    return new RegExp(HOOK_COMMAND.source, HOOK_COMMAND.flags);
+}
+/** Hermes's configuration root, from the environment or its documented default. */
+function hermesHome(env = process.env) {
+    const declared = env[HERMES_HOME_ENV];
+    if (typeof declared === "string" && declared.trim() !== "")
+        return declared;
+    return join(homedir(), HERMES_HOME_DEFAULT);
+}
+/** Every file a location names that exists on disk, absolute. */
+function settingFiles(dir, location) {
+    const base = location.home === "hermes" ? hermesHome() : dir;
+    if (location.file !== undefined) {
+        const path = join(base, location.file);
+        return existsSync(path) ? [path] : [];
+    }
+    if (location.dir === undefined)
+        return [];
+    let names;
+    try {
+        names = readdirSync(join(base, location.dir));
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names.sort()) {
+        if (location.prefix !== undefined && !name.startsWith(location.prefix))
+            continue;
+        const path = join(base, location.dir, name);
+        try {
+            if (statSync(path).isFile())
+                found.push(path);
+        }
+        catch {
+            continue;
+        }
+    }
+    return found;
+}
 /**
  * Every harness this checkout registers an `approval hook` command for.
  *
@@ -2268,35 +2902,52 @@ const HOOK_COMMAND = /\bapproval["']?\s+hook\s+(claude-code|cursor|codex)\b/u;
  */
 export function registeredHarnesses(dir) {
     const found = new Set();
-    for (const relative of HARNESS_SETTINGS) {
-        const path = join(dir, relative);
-        if (!existsSync(path))
-            continue;
-        let parsed;
-        try {
-            parsed = JSON.parse(readFileSync(path, "utf8"));
-        }
-        catch {
-            continue;
-        }
-        const stack = [parsed];
-        while (stack.length > 0) {
-            const node = stack.pop();
-            if (typeof node === "string") {
-                const match = HOOK_COMMAND.exec(node);
-                if (match !== null &&
-                    isHarnessKind(match[1]) &&
-                    (match[1] !== "codex" || isDirectCodexHookCommand(node))) {
-                    found.add(match[1]);
+    const locations = HARNESS_KINDS.flatMap((kind) => HARNESS_SETTINGS[kind]);
+    for (const location of locations) {
+        for (const path of settingFiles(dir, location)) {
+            let parsed;
+            if (location.text === true) {
+                // A YAML document has no JSON leaves to walk, so the whole text is the
+                // haystack. Only the hermes location asks for this; the three that were
+                // here before this task keep the JSON walk they have always had, which
+                // is what keeps their behaviour byte-identical.
+                let text;
+                try {
+                    text = readFileSync(path, "utf8");
+                }
+                catch {
+                    continue;
                 }
+                const match = HOOK_COMMAND.exec(text);
+                if (match !== null && isHarnessKind(match[1]))
+                    found.add(match[1]);
                 continue;
             }
-            if (Array.isArray(node)) {
-                stack.push(...node);
+            try {
+                parsed = JSON.parse(readFileSync(path, "utf8"));
+            }
+            catch {
                 continue;
             }
-            if (typeof node === "object" && node !== null) {
-                stack.push(...Object.values(node));
+            const stack = [parsed];
+            while (stack.length > 0) {
+                const node = stack.pop();
+                if (typeof node === "string") {
+                    const match = HOOK_COMMAND.exec(node);
+                    if (match !== null &&
+                        isHarnessKind(match[1]) &&
+                        (match[1] !== "codex" || isDirectCodexHookCommand(node))) {
+                        found.add(match[1]);
+                    }
+                    continue;
+                }
+                if (Array.isArray(node)) {
+                    stack.push(...node);
+                    continue;
+                }
+                if (typeof node === "object" && node !== null) {
+                    stack.push(...Object.values(node));
+                }
             }
         }
     }
@@ -2368,6 +3019,20 @@ function recordedHarnessVersions(records) {
  * has nothing to compare against, and inventing a baseline would be inventing
  * the fact); and no such binary on PATH, since doctor may be running somewhere
  * the harness is not installed, which is a state and not a fault.
+ *
+ * ## The Hermes fail-closed floor rides in this row (APRV-415)
+ *
+ * One harness has a second version question, and it is graver than the first. A
+ * Hermes below `HERMES_FAIL_CLOSED_FLOOR` does not know `fail_closed` and ignores
+ * it silently, so every broken hook PROCEEDS and the session looks gated while it
+ * is not. That belongs here rather than in a row of its own because both findings
+ * answer one question — is the binary hosting this hook in a state where the gate
+ * is known to fire — and a reader who sees this row green has been told both. It
+ * is read from `<binary> --version` rather than from a record, because Hermes's
+ * build stamp sits behind a non-ASCII separator that the write boundary refuses,
+ * so no record can ever carry it. The comparison is on the BUILD DATE and the
+ * upstream commit: the two builds that differ on this behaviour report the same
+ * semver.
  */
 function checkHarnessVersion(dir, records) {
     const check = "harness-version-unverified";
@@ -2378,13 +3043,41 @@ function checkHarnessVersion(dir, records) {
         return {
             check,
             status: "skip",
-            detail: `${where} registers no \`approval hook\` command in ${HARNESS_SETTINGS.join(" or ")}, so no harness hosts the hook here and there is no installed version for the log to be behind`,
+            detail: `${where} registers no \`approval hook\` command in ${harnessSettingNames()}, so no harness hosts the hook here and there is no installed version for the log to be behind`,
         };
     }
     const recorded = recordedHarnessVersions(records);
     const mismatched = [];
     const matched = [];
     const unknown = [];
+    // APRV-415. The VERSION FLOOR, which is a different question from the rest of
+    // this row and belongs to it for one reason: both ask whether the binary
+    // hosting this hook is in a state where the gate is known to fire. The row
+    // above asks whether the binary CHANGED without the gate being exercised
+    // since; this asks whether the binary is old enough that a broken hook would
+    // not have stopped anything in the first place.
+    //
+    // It is read off the INSTALLED build rather than off a record, and that is not
+    // a shortcut: Hermes prints its build stamp behind a non-ASCII separator, so
+    // the write boundary's printable-ASCII rule (SPEC.md §11.1 invariant 3) refuses
+    // the whole line and no record ever carries a Hermes version. The floor would be
+    // permanently unknown if it waited for one.
+    const floor = [];
+    const belowFloor = [];
+    if (kinds.includes("hermes")) {
+        const raw = installedHarnessVersionRaw("hermes");
+        const support = hermesFailClosedSupport(raw);
+        const quoted = raw === null ? "(no answer)" : JSON.stringify(raw);
+        if (support === "ignores") {
+            belowFloor.push(`the installed Hermes is BELOW the fail_closed floor: \`${HARNESS_BINARY["hermes"]} --version\` says ${quoted}, and the floor is ${HERMES_FAIL_CLOSED_FLOOR.statement}. On a build that does not know the key, a hook crash, a hook timeout and unparseable hook output all PROCEED, silently, so every gated tool call in this checkout is a backstop rather than a gate and nothing in the session says so`);
+        }
+        else if (support === "honours") {
+            floor.push(`hermes ${quoted} is at or above the fail_closed floor (${HERMES_FAIL_CLOSED_FLOOR.statement}), so a broken hook blocks rather than proceeding`);
+        }
+        else {
+            floor.push(`hermes: the fail_closed floor could not be established from ${quoted} (no build date and not the floor's own commit; two commits cannot be ordered without a repository), so check it by hand — the floor is ${HERMES_FAIL_CLOSED_FLOOR.statement}`);
+        }
+    }
     for (const kind of kinds) {
         const last = recorded.get(kind);
         if (last === undefined) {
@@ -2402,12 +3095,26 @@ function checkHarnessVersion(dir, records) {
         }
         mismatched.push(`${kind} is installed at ${JSON.stringify(installed)} and the last hook-written record (seq ${String(last.seq)}) was issued by ${JSON.stringify(last.version)}`);
     }
+    // APRV-415: the floor is reported FIRST when it is breached, because it is the
+    // graver of the two findings. An unverified change means nobody has checked
+    // whether the gate still fires; a build below the floor means a broken hook does
+    // not stop anything, which is established rather than unchecked.
+    if (belowFloor.length > 0) {
+        return {
+            check,
+            status: "fail",
+            detail: `${belowFloor.join("; ")}${mismatched.length === 0
+                ? ""
+                : `. And the harness binary changed with no gate exercised since: ${mismatched.join("; ")}`}`,
+            fix: `hermes update (or reinstall from main), then \`approval doctor\` again. The installed version is self-reported, so this row can only ask for a look: it never widens a verdict, and the adapter's own refusals are the same on every build.`,
+        };
+    }
     if (mismatched.length > 0) {
         const first = kinds[0];
         return {
             check,
             status: "fail",
-            detail: `the harness binary changed and the gate has not been exercised since: ${mismatched.join("; ")}. A release can change the hook envelope semantics, so until one record is written under the new binary nothing here shows the hook still fires. The recorded version is self-reported and reduces nothing: a match would not have proved the hook fired either, and what a mismatch says is that nobody has looked.`,
+            detail: `the harness binary changed and the gate has not been exercised since: ${mismatched.join("; ")}. A release can change the hook envelope semantics, so until one record is written under the new binary nothing here shows the hook still fires. The recorded version is self-reported and reduces nothing: a match would not have proved the hook fired either, and what a mismatch says is that nobody has looked.${floor.length === 0 ? "" : ` Separately: ${floor.join("; ")}.`}`,
             fix: `approval hook ${first} --dir ${where} < one PreToolUse event for a supervised-class command — the self-test in docs/${first === "cursor" ? "cursor" : "claude-code"}-hook.md. It prompts nobody and writes one task.registered carrying the installed version.`,
         };
     }
@@ -2415,13 +3122,13 @@ function checkHarnessVersion(dir, records) {
         return {
             check,
             status: "pass",
-            detail: `${matched.join("; ")}${unknown.length === 0 ? "" : `; ${unknown.join("; ")}`}. A match is not proof the hook fired; it is the absence of the one thing this row can see, an unverified change of the binary hosting it.`,
+            detail: `${matched.join("; ")}${unknown.length === 0 ? "" : `; ${unknown.join("; ")}`}. A match is not proof the hook fired; it is the absence of the one thing this row can see, an unverified change of the binary hosting it.${floor.length === 0 ? "" : ` ${floor.join("; ")}.`}`,
         };
     }
     return {
         check,
         status: "skip",
-        detail: `${where} registers ${kinds.join(", ")} and no comparison could be made: ${unknown.join("; ")}`,
+        detail: `${where} registers ${kinds.join(", ")} and no comparison could be made: ${unknown.join("; ")}${floor.length === 0 ? "" : `. ${floor.join("; ")}`}`,
     };
 }
 // ---------------------------------------------------------------------------
@@ -2515,16 +3222,46 @@ function checkDarkSessions(logPath, dir, policyPath, records, verified) {
  * is reported); this list only says where to look, so a directory nobody uses
  * costs nothing and a file nobody named is not invented.
  */
-const ORGAN_SEARCH = [
-    { dir: ".claude", prefix: "settings" },
-    { dir: ".cursor", prefix: "hooks.json" },
-    { dir: join(".cursor", "hooks") },
-    { dir: join(".cursor", "agents") },
-];
+export const ORGAN_SEARCH = {
+    "claude-code": [{ dir: ".claude", prefix: "settings" }],
+    cursor: [
+        { dir: ".cursor", prefix: "hooks.json" },
+        { dir: join(".cursor", "hooks") },
+        { dir: join(".cursor", "agents") },
+    ],
+    // EMPTY ON PURPOSE, and this is the one entry in the record that is a decision
+    // rather than a list. `.codex/config.toml` and `.codex/hooks.json` are organs
+    // by `core/command-class.ts`'s own word, and adding them here would change
+    // what the `gate-organs` row reports in every Codex checkout — a change
+    // APRV-398 has no business making while adding a different harness. The row
+    // they belong in is their own task. What this record buys meanwhile is that
+    // the omission is now VISIBLE and typed rather than an absence nobody could
+    // see: a reader of this table can tell that codex was considered.
+    codex: [],
+    // APRV-243 and APRV-350: the organs the classifier has recognised since those
+    // tasks, which this list never learned about. `.grok/hooks/` and
+    // `.muse/hooks.json` are where each harness's hook is installed, so a
+    // hand-edited one nobody attested is exactly what this row exists to report.
+    grok: [
+        { dir: ".grok", prefix: "hooks.json" },
+        { dir: join(".grok", "hooks") },
+    ],
+    muse: [{ dir: ".muse", prefix: "hooks" }, { dir: ".muse", prefix: "settings" }],
+    // APRV-398. Hermes's real organ is `$HERMES_HOME/config.yaml` in the user
+    // home, and this row is about THIS CHECKOUT, so what is listed is the
+    // repository-relative directory the classifier would call an organ if a
+    // checkout carried one. A directory nobody uses costs nothing (see the header),
+    // and every candidate found here is put to the classifier before it is
+    // reported, so nothing is invented. The home file is reached by the
+    // harness-version row above, through {@link HARNESS_SETTINGS}.
+    hermes: [{ dir: ".hermes", prefix: "config" }, { dir: join(".hermes", "agent-hooks") }],
+};
+/** Every organ directory to look in, across harnesses, in kind order. */
+const ORGAN_SEARCH_ENTRIES = HARNESS_KINDS.flatMap((kind) => ORGAN_SEARCH[kind]);
 /** The organ files this checkout actually carries, repository-relative, sorted. */
 function listGateOrgans(root) {
     const found = [];
-    for (const entry of ORGAN_SEARCH) {
+    for (const entry of ORGAN_SEARCH_ENTRIES) {
         let names;
         try {
             names = readdirSync(join(root, entry.dir));
@@ -2649,7 +3386,7 @@ function checkGateOrgans(dir, records) {
         return {
             check,
             status: "skip",
-            detail: `${root} carries no gate organ files (${ORGAN_SEARCH.map((entry) => entry.dir).join(", ")}), so there is nothing here for a human to have attested`,
+            detail: `${root} carries no gate organ files (${ORGAN_SEARCH_ENTRIES.map((entry) => entry.dir).join(", ")}), so there is nothing here for a human to have attested`,
         };
     }
     const unattested = [];
@@ -2901,10 +3638,11 @@ function trackedPrivateKeys(root, keyDir) {
  * `token_sealed` for as long as the token is unspent and inside its TTL, so the
  * whole design of sealed delivery rests on the key never being committed.
  *
- * Nothing enforced that. `.approval/payloads/` is deliberately TRACKED (evidence
- * belongs in the history), so `.approval/` is a directory an operator adds from
- * during a records or ceremony commit, and a key store with no ignore line is
- * swept in by the same `git add` that carries the payloads.
+ * Nothing enforced that. `.approval/payloads/` was TRACKED by default until
+ * APRV-445 (and still is wherever an operator keeps it in history, as this
+ * repository does), so `.approval/` is a directory an operator adds from during
+ * a records or ceremony commit, and a key store with no ignore line is swept in
+ * by the same `git add` that carries the payloads.
  *
  * Two questions, in the order of what stays wrong the longest, the same reading
  * the vault and environment rows use:
@@ -2953,7 +3691,7 @@ function checkSealedKeys(logPath, dir) {
             return {
                 check,
                 status: "fail",
-                detail: `${String(present.length)} sealed-delivery private key(s) in ${keyDir} are NOT gitignored in ${dir}: one \`git add .approval/\` — the command a records or ceremony commit uses, because \`.approval/payloads/\` is deliberately tracked — publishes a live key beside the ciphertext it opens`,
+                detail: `${String(present.length)} sealed-delivery private key(s) in ${keyDir} are NOT gitignored in ${dir}: one \`git add .approval/\` — the command a records or ceremony commit uses, wherever \`.approval/payloads/\` is kept in history — publishes a live key beside the ciphertext it opens`,
                 fix: `echo '${KEYS_IGNORE_LINE}' >> ${join(dir, ".gitignore")} — the line \`approval init\` writes; and treat every action whose token is still unspent inside its TTL as disclosed`,
             };
         }
@@ -3170,9 +3908,10 @@ export function commandDoctor(argv, streams, cwd) {
             checkGateOrgans(dir, verified.records),
             // APRV-285: appended, eighteenth time, same reason. The sibling of the
             // vault and environment rows for the one file under `.approval/` that is
-            // a raw private key: `.approval/payloads/` is tracked on purpose, so
-            // `.approval/` is a directory people `git add` from, and the key store had
-            // nothing telling them it must not come along.
+            // a raw private key: wherever `.approval/payloads/` is tracked (the
+            // default before APRV-445, and this repository's choice), `.approval/` is
+            // a directory people `git add` from, and the key store had nothing
+            // telling them it must not come along.
             checkSealedKeys(logPath, dir),
             // APRV-313: appended, nineteenth time, same reason. Configuration on
             // disk is distinct from Codex trust, loading and observed execution.
@@ -3200,6 +3939,12 @@ export function commandDoctor(argv, streams, cwd) {
             // one, and this is where an operator finds out it happened without
             // reading the log by hand.
             checkCodexAutoReviewer(verified.records, verified.result.status === "clean"),
+            // APRV-383: appended, twenty-fourth time, same reason. The sibling of
+            // `keychain-scope` one layer along — that row says whose credentials this
+            // instance uses, this one says whose name its daemon writes onto every
+            // record — and the row an operator wiring up a hosted daemon needs BEFORE
+            // anything is running.
+            checkDaemonIdentity(logPath, verified.records, policyLoad),
         ];
         const ok = checks.every((entry) => entry.status !== "fail");
         if (json)