approval-md 0.1.0 → 0.3.0

package/dist/src/cli/doctor.js

@@ -55,15 +55,16 @@
  */
 import { createServer } from "node:net";
 import { closeSync, existsSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, } from "node:fs";
-import { dirname, isAbsolute, join, resolve as resolvePathSegments } from "node:path";
+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, 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 { 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";
@@ -71,6 +72,7 @@ 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";
@@ -84,7 +86,7 @@ import { RESOLVE_DANGLING_COMMAND, lastAdvance, proveDanglingAdvances, } from ".
 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 { 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";
@@ -332,7 +334,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 +407,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) {
@@ -744,11 +778,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 +800,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).`),
     };
 }
 // ---------------------------------------------------------------------------
@@ -1947,15 +2137,123 @@ function checkHarnessWiring(dir) {
         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).`,
     };
 }
+/** The project-local Codex hook files doctor can observe without asking Codex. */
+const CODEX_HOOKS = join(".codex", "hooks.json");
+const CODEX_CONFIG = join(".codex", "config.toml");
+const CODEX_MATCHER = "Bash|apply_patch";
+const CODEX_HOOK_TIMEOUT_SECONDS = 600;
+function isDirectCodexHookCommand(command) {
+    const match = command.match(/^(?:"([^"$`\\\r\n;&|<>]+)"|'([^'\\\r\n;&|<>]+)'|([^\s"'$`\\\r\n;&|<>]+)) hook codex --dir (?:"([^"$`\\\r\n;&|<>]+)"|'([^'\\\r\n;&|<>]+)'|([^\s"'$`\\\r\n;&|<>]+)) --as agent:codex --timeout 9m$/u);
+    if (match === null)
+        return false;
+    const executable = match[1] ?? match[2] ?? match[3] ?? "";
+    const primaryDir = match[4] ?? match[5] ?? match[6] ?? "";
+    return isAbsolute(executable) && basename(executable) === "approval" && isAbsolute(primaryDir);
+}
+function codexEventConfigured(hooks, event) {
+    if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks))
+        return false;
+    const groups = hooks[event];
+    if (!Array.isArray(groups))
+        return false;
+    return groups.some((group) => {
+        if (typeof group !== "object" || group === null || Array.isArray(group))
+            return false;
+        const fields = group;
+        if (fields["matcher"] !== CODEX_MATCHER || !Array.isArray(fields["hooks"]))
+            return false;
+        return fields["hooks"].some((handler) => {
+            if (typeof handler !== "object" || handler === null || Array.isArray(handler))
+                return false;
+            const entry = handler;
+            return (entry["type"] === "command" &&
+                typeof entry["command"] === "string" &&
+                isDirectCodexHookCommand(entry["command"]) &&
+                entry["timeout"] === CODEX_HOOK_TIMEOUT_SECONDS &&
+                (entry["async"] === undefined || entry["async"] === false));
+        });
+    });
+}
+/**
+ * Report only project configuration visible on disk.
+ *
+ * Codex owns hook trust and runtime loading. Neither is inferable from a file,
+ * and no historical log record proves what the current desktop session loaded.
+ */
+export function checkCodexHookWiring(dir) {
+    const check = "codex-hook-wiring";
+    const root = repoRoot(dir);
+    const where = root ?? dir;
+    const hooksPath = join(where, CODEX_HOOKS);
+    const configPath = join(where, CODEX_CONFIG);
+    const hasHooks = existsSync(hooksPath);
+    const hasConfig = existsSync(configPath);
+    if (!hasHooks && !hasConfig) {
+        return {
+            check,
+            status: "skip",
+            detail: `NOT CONFIGURED on disk: ${where} carries neither ${CODEX_HOOKS} nor ${CODEX_CONFIG}. Codex hook trust and observed execution are separate and remain unknown.`,
+        };
+    }
+    if (!hasHooks) {
+        return {
+            check,
+            status: "skip",
+            detail: `${configPath} exists. Doctor does not interpret inline TOML hook tables, so Codex hook configuration, trust and observed execution are undetermined.`,
+            fix: "approval hook codex --help — compare the documented PreToolUse and PostToolUse entries with .codex/config.toml",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(hooksPath, "utf8"));
+    }
+    catch (cause) {
+        return {
+            check,
+            status: "fail",
+            detail: `${hooksPath} cannot be read as JSON (${oneLine(detailOf(cause))}); configured wiring cannot be established, and trust or execution cannot be inferred.`,
+            fix: "approval hook codex --help — compare and repair the project-local hook JSON after human review",
+        };
+    }
+    const hooks = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+        ? parsed["hooks"]
+        : null;
+    const pre = codexEventConfigured(hooks, "PreToolUse");
+    const post = codexEventConfigured(hooks, "PostToolUse");
+    if (!pre || !post) {
+        const missing = [!pre ? "PreToolUse" : null, !post ? "PostToolUse" : null]
+            .filter((value) => value !== null)
+            .join(" and ");
+        return {
+            check,
+            status: "skip",
+            detail: `${hooksPath} is present but does not match the expected APRV-313 profile for ${missing}: synchronous command hooks with matcher ${JSON.stringify(CODEX_MATCHER)}, command \`approval hook codex\`, and timeout ${String(CODEX_HOOK_TIMEOUT_SECONDS)} seconds. Other Codex hook configurations may be valid; this integration's coverage is undetermined. File presence proves neither trust nor observed execution.`,
+            fix: "approval hook codex --help — install the documented pair only after human review",
+        };
+    }
+    if (hasConfig) {
+        return {
+            check,
+            status: "skip",
+            detail: `CONFIGURED in ${hooksPath}: the required PreToolUse and PostToolUse entries are present. ${configPath} also exists and Codex merges hook sources; doctor does not interpret its TOML tables, so the effective configuration is not fully established. Trust and observed execution remain unknown.`,
+            fix: "approval hook codex --help — compare .codex/config.toml with the reviewed hooks.json and keep one representation per layer",
+        };
+    }
+    return {
+        check,
+        status: "pass",
+        detail: `CONFIGURED on disk: ${hooksPath} carries synchronous PreToolUse and PostToolUse \`approval hook codex\` entries for ${CODEX_MATCHER}, each with a ${String(CODEX_HOOK_TIMEOUT_SECONDS)} second outer timeout. This does not establish Codex trust, loading, or observed execution; inspect and trust the exact hook with \`/hooks\`, then run the bounded smoke test.`,
+    };
+}
 // ---------------------------------------------------------------------------
 // harness version provenance (APRV-227)
 // ---------------------------------------------------------------------------
 /** 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];
+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)\b/u;
+const HOOK_COMMAND = /\bapproval["']?\s+hook\s+(claude-code|cursor|codex)\b/u;
 /**
  * Every harness this checkout registers an `approval hook` command for.
  *
@@ -1968,7 +2266,7 @@ const HOOK_COMMAND = /\bapproval\s+hook\s+(claude-code|cursor)\b/u;
  * searched. The row this feeds can only SKIP when the answer is empty, so a
  * miss costs a skip and never a false red.
  */
-function registeredHarnesses(dir) {
+export function registeredHarnesses(dir) {
     const found = new Set();
     for (const relative of HARNESS_SETTINGS) {
         const path = join(dir, relative);
@@ -1986,8 +2284,11 @@ function registeredHarnesses(dir) {
             const node = stack.pop();
             if (typeof node === "string") {
                 const match = HOOK_COMMAND.exec(node);
-                if (match !== null && isHarnessKind(match[1]))
+                if (match !== null &&
+                    isHarnessKind(match[1]) &&
+                    (match[1] !== "codex" || isDirectCodexHookCommand(node))) {
                     found.add(match[1]);
+                }
                 continue;
             }
             if (Array.isArray(node)) {
@@ -2268,6 +2569,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;
@@ -2321,6 +2694,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. */
@@ -2556,7 +3090,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
@@ -2599,6 +3133,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,
@@ -2631,6 +3174,32 @@ export function commandDoctor(argv, streams, cwd) {
             // `.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"),
         ];
         const ok = checks.every((entry) => entry.status !== "fail");
         if (json)