approval-md 0.2.0 → 0.4.0

package/dist/src/cli/doctor.js

@@ -54,23 +54,28 @@
  * 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, latestOrganAttestation, policyBytesHash, resolveHumanActor, } from "../core/attest.js";
-import { isGateOrganPath } from "../core/command-class.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";
 import { openObligations } from "../core/audit.js";
+import { SENDER_CHANNELS, SENDER_KEY_ENV, mapsSendersFor, senderKeyFrom, senderMappingForms, } from "../core/sender-identity.js";
 import { classSampling, resolveSampler } from "../core/sampler.js";
 import { checkVault, passphraseEnvFor, passphraseFrom, vaultExists, vaultPathFor, } from "../core/vault.js";
 import { admitSnapshot, logBytes, snapshotPathFor, snapshotSummary, } from "../core/verified-snapshot.js";
@@ -82,9 +87,13 @@ 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 { ScanError, checkBuildFreshness, checkMainBehindOrigin, installationRoot, } from "./preflight.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";
 import { DEFAULT_LOG_PATH, resolvePath } from "./paths.js";
@@ -246,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",
@@ -278,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) {
@@ -289,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",
@@ -332,7 +372,27 @@ function redact(text, token) {
  * operator to set a variable their policy never mentions is the failure mode
  * this parameter removes.
  */
-async function checkTelegram(apiBase, load) {
+/**
+ * Who owns the bot this row is about (APRV-390), as one clause.
+ *
+ * Read from the two ownership records and never from the network: doctor's
+ * `getMe` answers WHICH bot, and this answers WHOSE. An instance that has
+ * never started a listener has no record and gets no clause, because "nothing
+ * has claimed it yet" is a state and printing it on every row would make the
+ * real finding — two instances on one bot — harder to see.
+ */
+function ownershipClause(logPath, botId, apiBase) {
+    const mine = ownedBot(logPath, "telegram");
+    const others = otherOwnersOf(logPath, botId, apiBase);
+    if (others.length > 0) {
+        return `; ALSO claimed on this machine by ${describeOwners(others)}, which is two gates on one bot`;
+    }
+    if (mine !== null && mine.botId === botId) {
+        return `; owned by this instance (${mine.instanceHome}, instance ${mine.instanceId})`;
+    }
+    return "";
+}
+async function checkTelegram(apiBase, load, logPath) {
     const tokenEnv = telegramTokenEnvFor(load);
     const chatEnv = telegramChatEnvFor(load);
     const token = process.env[tokenEnv] ?? "";
@@ -385,11 +445,23 @@ async function checkTelegram(apiBase, load) {
         }
         const result = (envelope["result"] ?? {});
         const username = typeof result["username"] === "string" ? `@${result["username"]}` : "unnamed";
-        const id = result["id"] === undefined ? "unknown id" : `id ${String(result["id"])}`;
+        const botId = result["id"] === undefined ? "" : String(result["id"]);
+        const id = botId.length === 0 ? "unknown id" : `id ${botId}`;
+        // APRV-390. Two gates on one bot is a FAIL, not a note: it is the state in
+        // which an approval tap is answered by whichever listener asked first.
+        const owners = botId.length === 0 ? [] : otherOwnersOf(logPath, botId, base);
+        if (owners.length > 0) {
+            return {
+                check: "telegram",
+                status: "fail",
+                detail: `token valid: ${username} (${id}) via ${base}, chat ${chat} — but this bot is also claimed on this machine by ${describeOwners(owners)}. Both gates long-poll it, their getUpdates offsets acknowledge each other's updates, and an approval tap is answered by whichever listener asked first`,
+                fix: "approval setup channel telegram — give this instance its own bot from @BotFather; `approval channel telegram health` names the current owner of each",
+            };
+        }
         return {
             check: "telegram",
             status: "pass",
-            detail: `token valid: ${username} (${id}) via ${base}, chat ${chat}; no message was sent and no update was consumed`,
+            detail: `token valid: ${username} (${id}) via ${base}, chat ${chat}${botId.length === 0 ? "" : ownershipClause(logPath, botId, base)}; no message was sent and no update was consumed`,
         };
     }
     catch (cause) {
@@ -482,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);
@@ -493,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",
@@ -555,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)
 // ---------------------------------------------------------------------------
@@ -744,11 +910,19 @@ function checkValuesBlock(policyPath, policyFlagged, dir) {
                 detail: oneLine(`${result.message}, so there is no values block to read. The policy file's own absence is reported by the attestation row above.`),
             };
         }
+        // A block of the format APRV-336 replaced is a fixable block rather than a
+        // broken one, so its fix names the two edits instead of the load code.
+        const fix = result.code === "version-unsupported"
+            ? `edit the block in ${result.source?.filename ?? "the policy file"}: fold \`wants:\` into \`like:\`, rename \`responds:\` to \`communication:\`, and set \`version: "0.2"\` with the quotes; then re-attest, since the attestation digests the whole file`
+            : `approval values --json — prints the same failure with its code (${result.code}); fix the block in ${result.source?.filename ?? "the policy file"} and re-attest, since the attestation digests the whole file`;
         return {
             check: "values-block",
             status: "fail",
-            detail: oneLine(`a \`\`\`${VALUES_INFO_STRING} block is present and could not be read (${result.code}): ${result.message}. Nothing about the policy changed — guidance is not enforcement — but the operator's stated values reach no agent until this parses.`),
-            fix: `approval values --json — prints the same failure with its code (${result.code}); fix the block in ${result.source?.filename ?? "the policy file"} and re-attest, since the attestation digests the whole file`,
+            detail: oneLine(
+            // The loader's own message may end in a full stop (the version refusals
+            // are whole sentences), and two of them in a row reads as a typo.
+            `a \`\`\`${VALUES_INFO_STRING} block is present and could not be read (${result.code}): ${result.message.replace(/\.$/u, "")}. Nothing about the policy changed — guidance is not enforcement — but the operator's stated values reach no agent until this parses.`),
+            fix,
         };
     }
     if (!result.present) {
@@ -758,12 +932,160 @@ function checkValuesBlock(policyPath, policyFlagged, dir) {
             detail: `${result.source.filename}: no approval-values block; the operator has declared no values here. That is a declaration rather than a gap, and \`approval values\` says so in those words.`,
         };
     }
-    const declared = ["love", "like", "dislike", "wants"].filter((key) => result.values[key] !== undefined);
-    const responds = result.values.responds === undefined ? "" : ", responds";
+    const declared = ["love", "like", "dislike"].filter((key) => result.values[key] !== undefined);
+    const communication = result.values.communication === undefined ? "" : ", communication";
     return {
         check: "values-block",
         status: "pass",
-        detail: `${result.source.filename}: the values block parses and validates (version ${String(result.values.version)}; ${declared.length === 0 ? "no list" : declared.join(", ")}${responds}). It is guidance, so nothing here is enforced; read it with \`approval values\`.`,
+        detail: `${result.source.filename}: the values block parses and validates (version ${JSON.stringify(result.values.version)}; ${declared.length === 0 ? "no list" : declared.join(", ")}${communication}). It is guidance, so nothing here is enforced; read it with \`approval values\`.`,
+    };
+}
+// ---------------------------------------------------------------------------
+// 7e. the deprecated bare `supervised` (APRV-335)
+// ---------------------------------------------------------------------------
+/**
+ * Which rules of this policy still write the deprecated bare `supervised`.
+ *
+ * SPEC.md §5.2 keeps the spelling parsing as `supervised-retro` so that no
+ * published policy breaks, and the loader records a note wherever it appears.
+ * A note is read by whoever happens to run a verb that prints notes; the
+ * deprecation needs a place an operator looks at the state of their repository
+ * on purpose, which is this report. SPEC.md §5.2 asks implementations for
+ * exactly that.
+ *
+ * It is never a `fail` and never a `warn`. The policy says what its author
+ * meant, every gate resolves it identically, and nothing on this machine is
+ * broken by a spelling: a red row here would be doctor going red over prose. A
+ * `skip` is the unreadable policy, whose own failure the attestation and
+ * `policy check` rows report; everything else is a `pass` that either names the
+ * rules to rewrite or says plainly that there are none.
+ */
+function checkAutonomyAlias(policyLoad) {
+    if (!policyLoad.ok) {
+        return {
+            check: "autonomy-alias",
+            status: "skip",
+            detail: `the policy did not load (${policyLoad.code}), so no rule could be read for the deprecated bare \`supervised\`. A failed load resolves every class to \`manual\` and names no level at all; the failure itself is reported by \`approval policy check\`.`,
+        };
+    }
+    // The same walk `aliasNotes` makes in the loader, and deliberately the same
+    // order: `defaults` first, then class patterns sorted, so the row and the
+    // load-time notes name the same places in the same sequence.
+    const where = [];
+    if (policyLoad.policy.defaults?.autonomy === "supervised")
+        where.push("defaults.autonomy");
+    for (const pattern of Object.keys(policyLoad.policy.classes ?? {}).sort()) {
+        if (policyLoad.policy.classes?.[pattern]?.autonomy === "supervised")
+            where.push(pattern);
+    }
+    if (where.length === 0) {
+        return {
+            check: "autonomy-alias",
+            status: "pass",
+            detail: `${policyLoad.source.filename}: no rule uses the deprecated bare \`supervised\`. Every supervised class says which bargain it means, \`supervised-retro\` or \`supervised-live\`, so nothing here changes when a future schema version drops the alias.`,
+        };
+    }
+    return {
+        check: "autonomy-alias",
+        status: "pass",
+        detail: oneLine(`deprecated bare \`supervised\` on ${String(where.length)} rule(s): ${where.join(", ")}. Each parses as \`supervised-retro\` and is enforced as one, so the policy means today what its author meant; the spelling is deprecated and a future version of the policy schema removes it (SPEC.md §5.2, APRV-335).`),
+        // FIX_COMMAND_PREFIXES: the repair is a hand edit of the policy file plus
+        // the re-attestation that edit costs, and `policy amend` is the one verb
+        // that owns both. The prose after it is the edit itself: write
+        // supervised-retro.
+        fix: "approval policy amend — write supervised-retro in place of the bare supervised on the rules above, and re-attest in the same step; the paste-ready draft for this repo is docs/proposals/approval-md-2026-09.md",
+    };
+}
+/**
+ * Which approvers can still be recognized by the channels they are listed for
+ * (APRV-324, `design/channel-sender-identity.md` §5 item 13).
+ *
+ * The row exists for one transition and says which side of it this deployment
+ * is on. Declaring the first `senders` entry for a channel turns enforcement on
+ * for that whole channel: from then on a decision arriving with an account the
+ * policy does not name is REFUSED rather than recorded under the listener's own
+ * identity. An operator who maps themselves and forgets a colleague has built a
+ * gate that will refuse that colleague's next tap, and the file reads as though
+ * both are approvers.
+ *
+ * Three answers, and the verdicts are chosen for what each one actually is:
+ *
+ * - **SKIP** when no approver declares a mapping. That is every installation
+ *   before this key existed and most of them after, it is fully correct, and a
+ *   red row for it would be a red row people learn to skip past.
+ * - **FAIL** for an approver listed for a mapped channel with no id of their
+ *   own on it. Not a state: the policy says that person decides on that
+ *   channel, and the runtime will not honour it.
+ * - **PASS** when every approver the policy can reach on a mapped channel is
+ *   recognizable there.
+ *
+ * It reads the policy and nothing else — no log, no network, no credential —
+ * and it prints the id of nobody: a doctor row is read over a shoulder, the
+ * mapping is in a file the operator can open, and the row's job is to name who
+ * is missing rather than to recite everyone who is not.
+ */
+function checkSenderMapping(policyLoad, env = process.env) {
+    if (!policyLoad.ok) {
+        return {
+            check: "sender-mapping",
+            status: "skip",
+            detail: `the policy did not load (${policyLoad.code}), so no approver roster could be read. A failed load carries no sender mapping either, and a decision arriving with an authenticated sender is refused \`sender-unmapped\` until the file parses again — the \`attestation\` row above and \`approval policy check\` say what is wrong with it.`,
+        };
+    }
+    const approvers = policyLoad.policy.approvers;
+    const mapped = SENDER_CHANNELS.filter((channel) => mapsSendersFor(approvers, channel));
+    if (mapped.length === 0) {
+        return {
+            check: "sender-mapping",
+            status: "skip",
+            detail: `${policyLoad.source.filename}: no approver declares a \`senders\` block, so every decision is recorded against the identity the deciding process was launched with (\`--as\` / APPROVAL_HUMAN), exactly as it was before the mapping existed. Anyone who can reach a configured channel decides as that identity; map an approver's account id to record who actually tapped (SPEC.md §5.2, APRV-324).`,
+        };
+    }
+    // APRV-370. Which FORM each mapped channel is written in, and for a keyed one
+    // whether the key this process would compare with resolves at all. The row
+    // reports the form because an operator reading it cannot otherwise tell a
+    // gate that publishes its accounts from one that does not, and it reports the
+    // key because a keyed channel without one refuses every tap on it.
+    const key = senderKeyFrom(env);
+    const keyed = mapped.filter((channel) => senderMappingForms(approvers, channel).keyed);
+    const mixed = keyed.filter((channel) => senderMappingForms(approvers, channel).raw);
+    const forms = keyed.length === 0
+        ? "raw account ids"
+        : mixed.length > 0
+            ? `both forms (${mixed.join(", ")} carries raw ids beside keyed ones)`
+            : `the keyed form (${SENDER_KEY_ENV})`;
+    if (keyed.length > 0 && key === null) {
+        return {
+            check: "sender-mapping",
+            status: "fail",
+            detail: oneLine(`${policyLoad.source.filename} maps ${keyed.join(", ")} senders in the keyed form and ${SENDER_KEY_ENV} is unset or empty in this process, so no account on those channels can be resolved at all and EVERY decision there is refused \`sender-key-unavailable\`. Without the key the runtime can compute no digest, so it cannot tell a mapped account from an unmapped one and will not guess; there is no fallback to a raw comparison, by design.`),
+            fix: `approval setup sender-key mints and stores the key; \`eval "$(approval env)"\` establishes it in the shell that starts the listener, and the listener has to be restarted to pick it up. \`approval env --check\` says where the value lives and prints no values`,
+        };
+    }
+    const gaps = [];
+    for (const channel of mapped) {
+        for (const id of Object.keys(approvers ?? {}).sort()) {
+            const entry = approvers?.[id];
+            if (entry === undefined)
+                continue;
+            if (!entry.channels.includes(channel))
+                continue;
+            if (entry.senders?.[channel] === undefined)
+                gaps.push(`${id} on ${channel}`);
+        }
+    }
+    if (gaps.length > 0) {
+        return {
+            check: "sender-mapping",
+            status: "fail",
+            detail: oneLine(`${policyLoad.source.filename} maps ${mapped.join(", ")} senders in ${forms}, and ${String(gaps.length)} approver(s) listed for a mapped channel carry no id there: ${gaps.join(", ")}. A decision from an account this file does not name is refused \`sender-unmapped\` and nothing is recorded, so the policy currently says those people may decide on a channel where their taps will not be honoured.`),
+            fix: "approval policy amend — give each approver above a `senders` entry for that channel, or drop the channel from their `channels` list if they are not meant to decide there; the mapping is attested policy, so the edit is inoperative until it is re-attested",
+        };
+    }
+    return {
+        check: "sender-mapping",
+        status: "pass",
+        detail: oneLine(`${policyLoad.source.filename} maps ${mapped.join(", ")} senders in ${forms}, and every approver listed for a mapped channel carries an id there.${keyed.length === 0 ? "" : ` ${SENDER_KEY_ENV} resolves, so the keyed ids can be compared.`} Each decision on those channels is recorded against the person the operator attested that account to; an account this file does not name is refused rather than attributed to the listener (SPEC.md §10.3, APRV-324, APRV-370).`),
     };
 }
 // ---------------------------------------------------------------------------
@@ -1508,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)
 // ---------------------------------------------------------------------------
 /**
@@ -1745,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)?
@@ -1782,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";
@@ -1814,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;
+        }
+        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;
-        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 (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
@@ -1884,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);
@@ -1922,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. */
@@ -2060,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.
  *
@@ -2078,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));
+                }
             }
         }
     }
@@ -2178,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";
@@ -2188,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) {
@@ -2212,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.`,
         };
     }
@@ -2225,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("; ")}`}`,
     };
 }
 // ---------------------------------------------------------------------------
@@ -2325,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));
@@ -2379,6 +3306,78 @@ function listGateOrgans(root) {
  * configuration here, which is a state and not a fault, exactly as
  * `harness-hook-wiring` treats the same absence.
  */
+// ---------------------------------------------------------------------------
+// 30. codex-auto-reviewer (APRV-378)
+// ---------------------------------------------------------------------------
+/**
+ * How recent a pre-empted question has to be for this row to FAIL.
+ *
+ * The same twenty-four hours `dark-sessions` watches, and for the same reason:
+ * a row that failed forever over a fact an operator has already dealt with is a
+ * row nobody reads. An older record is not forgotten, it is reported in the
+ * detail of a passing row, which is where a durable fact belongs once the thing
+ * it asks for has been done.
+ */
+const AUTO_REVIEWER_WINDOW_MS = DEFAULT_DARK_WINDOW_MS;
+/**
+ * Has something other than this gate answered a question this gate exists to
+ * ask (APRV-378)?
+ *
+ * It reads `audit.question_preempted` and nothing else. There is no
+ * configuration here to inspect: whether Codex's auto-reviewer runs is gated in
+ * the harness's own configuration under a key this repository has no record of,
+ * and a config read written against a guessed key finds nothing and reports a
+ * GREEN row, which is the worst failure direction a health check has. So this
+ * row reports what was OBSERVED, and the only durable record of an observation
+ * is the one `approval codex bridge` appends when it stops.
+ *
+ * Reading this record is a diagnosis and not enforcement: the row authorizes
+ * nothing and refuses nothing, and `tests/question-preempted.test.ts` pins that
+ * no enforcement module reads the type.
+ *
+ * A row that says `pass` is saying the log holds no such record. It is NOT
+ * saying the auto-reviewer is off: nothing on this machine can say that, which
+ * is why the bridge probes rather than reads (APRV-364).
+ */
+function checkCodexAutoReviewer(records, verified) {
+    const check = "codex-auto-reviewer";
+    if (!verified) {
+        return {
+            check,
+            status: "skip",
+            detail: "the chain did not verify, so the records this row reads cannot be trusted; see the log check above",
+        };
+    }
+    const seen = records.filter((record) => record.event === "audit.question_preempted");
+    if (seen.length === 0) {
+        return {
+            check,
+            status: "pass",
+            detail: "no record of anything other than this gate answering a question it exists to ask. That is what the log holds, and it is not a claim that a harness auto-reviewer is off: only a bridge session's own probe can establish that, and only for the question it probed",
+        };
+    }
+    const newest = seen[seen.length - 1];
+    const payload = (newest.payload ?? {});
+    const question = (payload["question"] ?? {});
+    const source = typeof payload["source"] === "string" ? payload["source"] : "an unnamed source";
+    const id = typeof question["id"] === "string" ? question["id"] : "(no id)";
+    const verdict = typeof payload["verdict"] === "string" ? payload["verdict"] : "none stated";
+    const recent = seen.filter((record) => Date.parse(record.ts) >= Date.now() - AUTO_REVIEWER_WINDOW_MS);
+    const where = `${source} answered question ${id} (verdict: ${verdict}) at seq ${String(newest.seq)}`;
+    if (recent.length === 0) {
+        return {
+            check,
+            status: "pass",
+            detail: `${String(seen.length)} record(s), none in the last ${String(Math.round(AUTO_REVIEWER_WINDOW_MS / 3_600_000))}h. The most recent: ${where}`,
+        };
+    }
+    return {
+        check,
+        status: "fail",
+        detail: `${String(recent.length)} of ${String(seen.length)} record(s) in the last ${String(Math.round(AUTO_REVIEWER_WINDOW_MS / 3_600_000))}h: ${where}. A session whose questions something else can answer is a session whose silence means nothing, and the bridge stopped on it`,
+        fix: "approval doctor --verbose, then turn the harness's own auto-reviewer off in its configuration before running `approval codex bridge` again; this runtime cannot turn it off and cannot read whether it is on",
+    };
+}
 function checkGateOrgans(dir, records) {
     const check = "gate-organs";
     const root = repoRoot(dir) ?? dir;
@@ -2387,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 = [];
@@ -2432,6 +3431,167 @@ function checkGateOrgans(dir, records) {
     };
 }
 // ---------------------------------------------------------------------------
+// 31. pending-sign-off (APRV-338)
+// ---------------------------------------------------------------------------
+/**
+ * The marker SPEC.md's amendment-provenance rule puts on unratified text.
+ *
+ * Matched case-insensitively on the words alone rather than on the whole
+ * `(Amended APRV-n, pending sign-off.)` form, because the form is prose a human
+ * writes and a row that missed a hand-typed variant would report a clean file
+ * that is not one. Over-reporting here costs a line of output; under-reporting
+ * costs the thing the marker exists for.
+ */
+const PENDING_SIGN_OFF_MARKER = /pending sign-off/giu;
+/**
+ * Where to look for protected files carrying the marker.
+ *
+ * One level deep and enumerated, exactly as {@link ORGAN_SEARCH} is, and for
+ * the same reason: `core/command-class.ts` decides what IS a protected path
+ * (every candidate found here is put to it), so this list only says where to
+ * look. A repository-wide walk would be a health check that reads the whole
+ * working tree on every run, and the marker lives in governing documents, which
+ * sit at the root or in a directory a policy named.
+ */
+const SIGN_OFF_SEARCH_DIRS = [".", join(".github", "workflows"), "docs", "design"];
+/** How many bytes of a candidate are read before it is skipped as not-prose. */
+const SIGN_OFF_MAX_BYTES = 4 * 1024 * 1024;
+/**
+ * The protected files this checkout carries that doctor will read,
+ * repository-relative and sorted.
+ *
+ * The enumerated directories above, plus every exact path the policy's
+ * `protected_paths` names (a directory entry is enumerated one level deep like
+ * the rest). A candidate is kept only when the classifier calls it `policy.edit`
+ * or a `policy.edit.*` sub-class, which is the same set `approval policy attest
+ * --path` will sign off: a row that listed a file the verb refuses would be
+ * advice nobody can take.
+ */
+function listSignableFiles(root, extra) {
+    const dirs = new Set(SIGN_OFF_SEARCH_DIRS);
+    const exact = new Set();
+    for (const raw of extra) {
+        const entry = typeof raw === "string" ? raw : raw.path;
+        if (typeof entry !== "string" || entry.length === 0)
+            continue;
+        if (entry.includes("..") || isAbsolute(entry))
+            continue;
+        if (/[/\\]$/u.test(entry))
+            dirs.add(entry.replace(/[/\\]+$/u, ""));
+        else
+            exact.add(entry.split(/[/\\]+/u).join("/"));
+    }
+    const found = new Set();
+    const keep = (relative) => {
+        let isFile;
+        try {
+            const stats = statSync(join(root, relative));
+            isFile = stats.isFile() && stats.size <= SIGN_OFF_MAX_BYTES;
+        }
+        catch {
+            return;
+        }
+        if (!isFile)
+            return;
+        const routed = protectedPathClass(relative, extra);
+        if (routed === "policy.edit" || (routed !== null && POLICY_EDIT_SUBCLASS.test(routed))) {
+            found.add(relative);
+        }
+    };
+    for (const dir of dirs) {
+        let names;
+        try {
+            names = readdirSync(join(root, dir));
+        }
+        catch {
+            continue;
+        }
+        const prefix = dir === "." ? "" : `${dir.split(/[/\\]+/u).join("/")}/`;
+        for (const name of names.sort())
+            keep(`${prefix}${name}`);
+    }
+    for (const path of exact)
+        keep(path);
+    return [...found].sort();
+}
+/**
+ * Which protected files carry a pending-sign-off marker that no record
+ * resolves (APRV-338)?
+ *
+ * SPEC.md's amendment-provenance rule says text that reached a protected file
+ * without a grant carries `(Amended APRV-n, pending sign-off.)` and holds no
+ * more authority than a proposal until a human ratifies it. Since APRV-338 the
+ * ratification is a record, `gate.path.signed_off`, so the state is finally
+ * answerable: a file whose CURRENT bytes carry a sign-off is ratified as it
+ * stands, and one that carries the marker with no such record is a debt
+ * somebody owes.
+ *
+ * **This row never moves the exit code**, for the reasons `gate-organs` does
+ * not. Nothing on this machine is broken by unratified prose; what the row buys
+ * is that the debt is visible at the terminal rather than discovered when a
+ * pull request fails. And a marker is a human's own sentence about their own
+ * text: a health check that failed on one would be the runtime grading prose.
+ */
+function checkPendingSignOff(dir, records, policyLoad) {
+    const check = "pending-sign-off";
+    const root = repoRoot(dir) ?? dir;
+    // A policy that did not load contributes no entries, which narrows the set
+    // doctor reads rather than widening it — the same direction every other
+    // reader of `protected_paths` takes when it cannot have the list.
+    const extra = policyLoad.ok ? (policyLoad.policy.protected_paths ?? []) : [];
+    const files = listSignableFiles(root, extra);
+    const pending = [];
+    const ratified = [];
+    const unreadable = [];
+    for (const file of files) {
+        let text;
+        let sha256;
+        try {
+            const bytes = readFileSync(join(root, file));
+            text = bytes.toString("utf8");
+            sha256 = policyBytesHash(bytes);
+        }
+        catch (cause) {
+            unreadable.push(`${file} (${detailOf(cause)})`);
+            continue;
+        }
+        const markers = text.match(PENDING_SIGN_OFF_MARKER)?.length ?? 0;
+        if (markers === 0)
+            continue;
+        const plural = markers === 1 ? "" : "s";
+        if (findPathSignOff(records, file, sha256) !== null) {
+            ratified.push(`${file} (${String(markers)} marker${plural}, signed off at these bytes)`);
+            continue;
+        }
+        const previous = latestPathSignOff(records, file);
+        pending.push(previous === null
+            ? `${file} (${String(markers)} marker${plural}, never signed off, live ${sha256.slice(0, 12)}…)`
+            : `${file} (${String(markers)} marker${plural}, edited since seq ${previous.record.seq}: signed ${previous.sha256.slice(0, 12)}…, live ${sha256.slice(0, 12)}…)`);
+    }
+    if (pending.length === 0 && unreadable.length === 0) {
+        return {
+            check,
+            status: "pass",
+            detail: ratified.length === 0
+                ? `no protected file in ${root} carries a pending-sign-off marker (${String(files.length)} file(s) read)`
+                : `every pending-sign-off marker in ${root} sits in a file a human has signed off at its current bytes: ${ratified.join("; ")}`,
+        };
+    }
+    const parts = [];
+    if (pending.length > 0)
+        parts.push(`AWAITING SIGN-OFF: ${pending.join("; ")}`);
+    if (unreadable.length > 0)
+        parts.push(`unreadable: ${unreadable.join("; ")}`);
+    const first = (pending[0] ?? "<path>").split(" ")[0] ?? "<path>";
+    return {
+        check,
+        // Never a fail: see the note above.
+        status: "skip",
+        detail: `${parts.join(". ")}. Text carrying that marker holds no more authority than a proposal until a human ratifies it (SPEC.md §5.2), and the ratification is a gate.path.signed_off record over the file's exact bytes. A marker whose text was later granted through the gate should lose the suffix instead; signing off is for text that reached the file without a grant`,
+        fix: `approval policy attest --path ${first} --as human:<id> — after READING the file as it now stands`,
+    };
+}
+// ---------------------------------------------------------------------------
 // 28. sealed-keys (APRV-285)
 // ---------------------------------------------------------------------------
 /** The exact line doctor tells an operator to add for the sealed-token key store. */
@@ -2478,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:
@@ -2530,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`,
             };
         }
@@ -2667,7 +3828,7 @@ export function commandDoctor(argv, streams, cwd) {
             checkIdentity(),
             checkAttestationHealth(verified.records, policyPath),
             checkLog(logPath, verified.result),
-            await checkTelegram(apiBase, policyLoad),
+            await checkTelegram(apiBase, policyLoad, logPath),
             await checkWebPort(port ?? WEB_DEFAULT_PORT),
             checkPayloadStore(logPath, verified.records),
             // APRV-271: asks the running daemon for the one half of this answer that
@@ -2710,6 +3871,15 @@ export function commandDoctor(argv, streams, cwd) {
             // network to be more accurate would be acting on its own account, so the
             // answer is as fresh as the operator's last fetch and says so.
             checkMainBehindOrigin(logPath, queuePath, root),
+            // APRV-342: the interregnum between an attestation and its pull request
+            // merging. `attestation` above asks whether the LOCAL policy is attested;
+            // this asks whether the attested policy is on the remote, which is the
+            // question a fresh checkout of main answers with `policy-not-attested`.
+            checkAttestedPolicyOnMain({
+                policyPath,
+                records: verified.records,
+                root: repoRoot(dirname(logPath)),
+            }),
             // APRV-227: appended, fourteenth time, same reason. The only row that
             // asks a question about a binary OUTSIDE this repository, and it asks it
             // the one way a log can: what the last record said the harness was,
@@ -2738,13 +3908,43 @@ 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.
             checkCodexHookWiring(dir),
+            // APRV-335: appended, twentieth time, same reason. The health-report half
+            // of the alias deprecation SPEC.md §5.2 now states: the loader's note is
+            // seen by whoever runs a verb that prints notes, and this is the surface
+            // an operator opens to read the state of their own repository.
+            checkAutonomyAlias(policyLoad),
+            // APRV-338: appended, twenty-first time, same reason. The terminal half
+            // of the sign-off record: which protected files still carry SPEC.md's
+            // pending-sign-off marker with no record ratifying their current bytes.
+            // Informational and never a fail, exactly as gate-organs is — nothing on
+            // this machine is broken by unratified prose, and a health check that
+            // graded prose would be the runtime marking a human's homework.
+            checkPendingSignOff(dir, verified.records, policyLoad),
+            // APRV-324: appended, twenty-second time, same reason. The row design
+            // §5 item 13 asks for, and the one an operator needs BEFORE the first
+            // tap is refused: declaring a `senders` entry turns enforcement on for
+            // that whole channel, so an approver left out of it is a person the
+            // policy still lists and the gate will no longer honour.
+            checkSenderMapping(policyLoad),
+            // APRV-378: appended, twenty-third time, same reason. The terminal half
+            // of `audit.question_preempted`: the bridge stops the session that saw
+            // 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)