@indigoai-us/hq-cli 5.99.1 → 5.99.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [5.99.2] — 2026-08-13
+
+### Fixed
+
+- `hq doctor` now grades the Codex **adapter architecture** instead of only the
+  legacy per-hook mirror model (#369). On a current tree — where
+  `.codex/config.toml` routes every lifecycle event through
+  `hq-codex-hook-adapter.sh` dispatching the canonical `.claude/hooks` scripts —
+  the doctor previously reported dozens of phantom FAILs (missing `hooks.json`,
+  missing per-hook counterparts). It now verifies the adapter, its dispatch
+  library, and per-event registration, flags leftover pre-adapter artifacts for
+  deletion, and skips mirror-parity checks that no longer apply.
+- `hq core hq-session` company-bind hard-policy emission is deduped and budgeted
+  (#370). Sync-conflict copies (`foo 2.md`), `_digest*`, `README`, and
+  `example-policy.md` no longer contribute lines, and the emission is capped by
+  `HQ_COMPANY_BIND_POLICY_CAP` (32) / `HQ_COMPANY_BIND_POLICY_BYTES` (40960)
+  with a non-silent overflow pointer — a large tenant's bind drops from ~298
+  lines to 32 + pointer. Withheld policies re-surface via the reactive policy
+  trigger hook when they apply.
+
 ## [5.99.1] — 2026-08-12
 
 ## [5.99.0] — 2026-08-11

package/assets/scaffold/core/scripts/hq-session.sh

@@ -183,18 +183,31 @@ spawn_work_mesh_register() {
 
 # Print a company's hard-enforcement policies, read directly from the policy
 # files (the pre-built digest was retired — the when/on trigger hook is now the
-# sole policy-surfacing path). Emits one `- [hard] **slug**: rule` line each.
+# sole policy-surfacing path). Emits one `- [hard] **slug**: rule` line each,
+# deduped (digest/README/example/sync-conflict copies are skipped) and budgeted
+# (HQ_COMPANY_BIND_POLICY_CAP lines / HQ_COMPANY_BIND_POLICY_BYTES bytes, with a
+# non-silent pointer for the overflow). An unbounded dump — observed at ~298
+# lines for a large tenant — buries the rules it exists to surface; the
+# reactive trigger hook re-injects any withheld policy when its trigger fires.
 emit_company_hard_policies() {
   local co="$1"
   local dir="$REPO_ROOT/companies/$co/policies"
   [ -d "$dir" ] || return 0
-  # Guard the glob: with no matching files "$dir"/*.md expands literally, awk
-  # exits nonzero, and under `set -e` that would abort an otherwise fine bind.
-  local have=0 f
+  # Collect real policy files only. Skip the generated digest, docs, examples,
+  # and sync-conflict duplicates: policy slugs never contain spaces, so a space
+  # in the basename ("foo 2.md") marks a stray copy whose lines would duplicate
+  # the original's. (Also guards the glob: with no matching files "$dir"/*.md
+  # expands literally and awk would exit nonzero under `set -e`.)
+  local files=() f b
   for f in "$dir"/*.md; do
-    [ -e "$f" ] && { have=1; break; }
+    [ -e "$f" ] || continue
+    b="${f##*/}"
+    case "$b" in
+      _digest*.md|README.md|readme.md|example-policy.md|*.conflict-*|*" "*) continue ;;
+    esac
+    files+=("$f")
   done
-  [ "$have" = 1 ] || return 0
+  [ "${#files[@]}" -gt 0 ] || return 0
   local lines
   lines="$(awk '
     function bn(p,  n,a,b){ n=split(p,a,"/"); b=a[n]; sub(/\.md$/,"",b); return b }
@@ -207,13 +220,31 @@ emit_company_hard_policies() {
     d>=2 && rsec && /^## / { rsec=0 }
     d>=2 && rsec && !rcap && NF { line=$0; gsub(/\*\*/,"",line); if(length(line)>160)line=substr(line,1,157)"..."; rule=line; rcap=1 }
     END { if(seen) flush() }
-  ' "$dir"/*.md 2>/dev/null)"
+  ' "${files[@]}" 2>/dev/null)"
   [ -z "$lines" ] && return 0
+  # Budget the emission: count cap and cumulative byte cap, prefix-stable
+  # (glob order), never silent — overflow is summarized with a pointer so the
+  # withheld policies stay one command away.
+  local cap="${HQ_COMPANY_BIND_POLICY_CAP:-32}"
+  local max_bytes="${HQ_COMPANY_BIND_POLICY_BYTES:-40960}"
   printf '\n<company-policy-digest co="%s">\n' "$co"
   printf '# %s hard-enforcement policies (auto-surfaced on company bind)\n' "$co"
   printf '> Company context just bound mid-session. These HARD rules now apply.\n'
   printf '> Full text: `companies/%s/policies/{slug}.md` (or `qmd get -c %s {slug}`).\n\n' "$co" "$co"
-  printf '%s\n' "$lines"
+  printf '%s\n' "$lines" | awk -v cap="$cap" -v maxb="$max_bytes" -v co="$co" '
+    NF {
+      n++
+      if (!stop) {
+        bytes += length($0) + 1
+        if (n <= cap && bytes <= maxb) { print; kept = n } else stop = 1
+      }
+    }
+    END {
+      dropped = n - kept
+      if (dropped > 0)
+        printf "\n> %d more hard %s not shown (bind budget: %d policies / %d bytes). Full set: `companies/%s/policies/` or `qmd get -c %s {slug}`; matching rules re-surface via the policy trigger hook when they apply.\n", \
+          dropped, (dropped == 1 ? "policy" : "policies"), cap, maxb, co, co
+    }'
   printf '</company-policy-digest>\n'
 }
 

package/dist/lib/doctor/__testing__/fake-hq-tree.d.ts

@@ -91,6 +91,28 @@ export interface FakeHookSpec {
      */
     codex?: FakeCodexMirrorSpec | false;
 }
+/**
+ * Declares the adapter-architecture Codex wiring: `.codex/config.toml` routing
+ * lifecycle events to `hq-codex-hook-adapter.sh`, which dispatches the
+ * `.claude/settings.json` hooks live. When this spec is present the tree models
+ * a current-release root: no `.codex/hooks.json` and no per-hook mirrors are
+ * written by default (declare a hook's `codex` spec explicitly, or set
+ * `legacyHooksJson`, to model pre-adapter leftovers).
+ */
+export interface FakeCodexAdapterSpec {
+    /** Events wired to the adapter in config.toml. Default: the shipped eight. */
+    events?: string[];
+    /** Whether the adapter script is written. Default: true. */
+    adapterPresent?: boolean;
+    /** Whether the adapter script carries the executable bit. Default: true. */
+    adapterExecutable?: boolean;
+    /** Whether `core/scripts/lib/hook-adapter-core.sh` is written. Default: true. */
+    dispatchLibPresent?: boolean;
+    /** Whether a leftover `.codex/hooks.json` is still written. Default: false. */
+    legacyHooksJson?: boolean;
+}
+/** The lifecycle events the shipped `.codex/config.toml` wires. */
+export declare const ADAPTER_DEFAULT_EVENTS: readonly string[];
 /** Declares the `.grok/hooks/` state. */
 export interface FakeGrokSpec {
     /** Whether the `.grok/hooks/` scaffold is created at all. Default: true. */
@@ -110,6 +132,13 @@ export interface FakeHqTreeSpec {
     hooks?: FakeHookSpec[];
     /** Extra top-level keys merged into `.claude/settings.json`. */
     claudeSettings?: Record<string, unknown>;
+    /**
+     * Adapter-architecture Codex wiring. When set (object or `true` for a fully
+     * healthy default), the tree models a current-release root: config.toml +
+     * adapter + dispatch library, and no hooks.json or per-hook mirrors unless
+     * explicitly declared. When omitted, the tree keeps the legacy mirror shape.
+     */
+    codexAdapter?: FakeCodexAdapterSpec | true;
     /** Grok scaffold config, or `false` to omit `.grok/`. Default: healthy. */
     grok?: FakeGrokSpec | false;
     /** Initialise a git repo at the tree root. Default: false. */
@@ -163,6 +192,10 @@ export interface FakeHqTreeManifest {
     codexHooksJsonPath: string;
     codexHooksDir: string;
     codexHookGatePath: string;
+    /** Path of `.codex/config.toml`, or null when no adapter spec was given. */
+    codexConfigTomlPath: string | null;
+    /** Path of the adapter script, or null when no adapter spec was given. */
+    codexAdapterPath: string | null;
     grokDir: string | null;
     grokAdapterPath: string | null;
     grokRegistrationPath: string | null;

package/dist/lib/doctor/__testing__/fake-hq-tree.js

@@ -38,6 +38,17 @@ const DEFAULT_HOOK_BODY = "#!/bin/bash\ncat >/dev/null\nexit 0\n";
 const EXECUTABLE_MODE = 0o755;
 const NON_EXECUTABLE_MODE = 0o644;
 const DEFAULT_PREFIX = "hq-doctor-fake-";
+/** The lifecycle events the shipped `.codex/config.toml` wires. */
+export const ADAPTER_DEFAULT_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "Stop",
+    "SubagentStop",
+    "PreCompact",
+    "SessionEnd",
+];
 // --- Automatic cleanup registry ------------------------------------------------
 const trackedRoots = new Set();
 let exitHandlerRegistered = false;
@@ -90,19 +101,29 @@ export function buildFakeHqTree(spec = {}) {
     // A `core/` directory is what marks this as an HQ tree for later root
     // discovery; cheap to add and keeps the fixture realistic.
     fs.mkdirSync(path.join(root, "core", "scripts"), { recursive: true });
+    const adapterSpec = spec.codexAdapter === true ? {} : (spec.codexAdapter ?? null);
     const hookSpecs = spec.hooks ?? [];
-    const hookEntries = hookSpecs.map((hook) => writeHook(claudeHooksDir, codexHooksDir, hook));
-    // hook-gate.sh (mirrored to both platforms) carries the three profile lists,
-    // aggregated across every hook's `profiles`.
+    const hookEntries = hookSpecs.map((hook) => 
+    // Adapter-architecture trees have no per-hook mirrors unless a hook
+    // explicitly declares one (to model a pre-adapter leftover).
+    writeHook(claudeHooksDir, codexHooksDir, hook, adapterSpec === null));
+    // hook-gate.sh carries the three profile lists, aggregated across every
+    // hook's `profiles`. Legacy trees mirror it to `.codex/hooks/` too; adapter
+    // trees run the Claude gate directly, so no mirror is written there.
     const gateSource = renderHookGate(hookEntries);
     const claudeHookGatePath = path.join(claudeHooksDir, "hook-gate.sh");
     const codexHookGatePath = path.join(codexHooksDir, "hook-gate.sh");
     writeScript(claudeHookGatePath, gateSource, EXECUTABLE_MODE);
-    writeScript(codexHookGatePath, gateSource, EXECUTABLE_MODE);
+    if (adapterSpec === null) {
+        writeScript(codexHookGatePath, gateSource, EXECUTABLE_MODE);
+    }
     const claudeSettingsPath = path.join(root, ".claude", "settings.json");
     fs.writeFileSync(claudeSettingsPath, JSON.stringify(renderClaudeSettings(hookEntries, spec.claudeSettings), null, 2) + "\n");
     const codexHooksJsonPath = path.join(root, ".codex", "hooks.json");
-    fs.writeFileSync(codexHooksJsonPath, JSON.stringify(renderCodexHooksJson(root, hookEntries), null, 2) + "\n");
+    if (adapterSpec === null || adapterSpec.legacyHooksJson) {
+        fs.writeFileSync(codexHooksJsonPath, JSON.stringify(renderCodexHooksJson(root, hookEntries), null, 2) + "\n");
+    }
+    const adapterPaths = writeCodexAdapter(root, codexHooksDir, adapterSpec);
     const grok = writeGrok(root, spec.grok);
     let gitInitialised = false;
     if (spec.git) {
@@ -116,6 +137,8 @@ export function buildFakeHqTree(spec = {}) {
         codexHooksJsonPath,
         codexHooksDir,
         codexHookGatePath,
+        codexConfigTomlPath: adapterPaths.configTomlPath,
+        codexAdapterPath: adapterPaths.adapterPath,
         grokDir: grok.dir,
         grokAdapterPath: grok.adapterPath,
         grokRegistrationPath: grok.registrationPath,
@@ -139,7 +162,7 @@ export function buildFakeHqTree(spec = {}) {
     };
 }
 // --- Hook materialisation ------------------------------------------------------
-function writeHook(claudeHooksDir, codexHooksDir, hook) {
+function writeHook(claudeHooksDir, codexHooksDir, hook, defaultMirror) {
     const claudeBody = hook.body ?? DEFAULT_HOOK_BODY;
     const present = hook.present !== false;
     const registered = hook.registered !== false;
@@ -154,7 +177,7 @@ function writeHook(claudeHooksDir, codexHooksDir, hook) {
         mode = statMode(scriptPath);
         executable = isExecutable(mode);
     }
-    const codex = writeCodexMirror(codexHooksDir, hook, claudeBody);
+    const codex = writeCodexMirror(codexHooksDir, hook, claudeBody, defaultMirror);
     return {
         id: hook.id,
         scriptPath,
@@ -168,10 +191,13 @@ function writeHook(claudeHooksDir, codexHooksDir, hook) {
         codex,
     };
 }
-function writeCodexMirror(codexHooksDir, hook, claudeBody) {
-    // `codex: false` => a Claude hook with no Codex counterpart.
+function writeCodexMirror(codexHooksDir, hook, claudeBody, defaultMirror) {
+    // `codex: false` => a Claude hook with no Codex counterpart. An undeclared
+    // mirror defaults to healthy on legacy trees and to absent on adapter trees.
     if (hook.codex === false)
         return null;
+    if (hook.codex === undefined && !defaultMirror)
+        return null;
     const codexSpec = hook.codex ?? {};
     const present = codexSpec.present !== false;
     const registered = codexSpec.registered !== false;
@@ -292,6 +318,31 @@ ${caseBlock}    *)
   esac
 }`;
 }
+/**
+ * Materialise the adapter-architecture wiring: `.codex/config.toml` routing the
+ * spec'd events to `hq-codex-hook-adapter.sh`, the adapter script itself, and
+ * the `core/scripts/lib/hook-adapter-core.sh` dispatch library it sources —
+ * mirroring the shape the hq-core release ships.
+ */
+function writeCodexAdapter(root, codexHooksDir, spec) {
+    if (spec === null)
+        return { configTomlPath: null, adapterPath: null };
+    const events = spec.events ?? [...ADAPTER_DEFAULT_EVENTS];
+    const adapterPath = path.join(codexHooksDir, "hq-codex-hook-adapter.sh");
+    const command = `exec /bin/bash "$PWD/.codex/hooks/hq-codex-hook-adapter.sh"`;
+    const blocks = events.map((event) => `[[hooks.${event}]]\n\n[[hooks.${event}.hooks]]\ntype = "command"\ncommand = '${command}'\ntimeout = 30\n`);
+    const configTomlPath = path.join(root, ".codex", "config.toml");
+    fs.writeFileSync(configTomlPath, `[features]\nhooks = true\n\n${blocks.join("\n")}`);
+    if (spec.adapterPresent !== false) {
+        writeScript(adapterPath, "#!/bin/bash\ncat >/dev/null\nexit 0\n", spec.adapterExecutable === false ? NON_EXECUTABLE_MODE : EXECUTABLE_MODE);
+    }
+    if (spec.dispatchLibPresent !== false) {
+        const libPath = path.join(root, "core", "scripts", "lib");
+        fs.mkdirSync(libPath, { recursive: true });
+        fs.writeFileSync(path.join(libPath, "hook-adapter-core.sh"), "# fake hook-adapter-core.sh (test fixture)\n");
+    }
+    return { configTomlPath, adapterPath };
+}
 function writeGrok(root, spec) {
     const absent = {
         dir: null,

package/dist/lib/doctor/checks/codex-wiring.d.ts

@@ -1,10 +1,28 @@
 /**
- * Codex hook wiring and Claude-parity checks (US-005).
+ * Codex hook wiring checks (US-005), covering both Codex architectures.
  *
- * Claude and Grok both execute the canonical `.claude/hooks/` scripts; only
- * Codex runs duplicated copies under `.codex/hooks/`, so Codex is the entire
- * drift surface the doctor has to police. This check does three things, all
- * read-only and all against the resolved HQ tree (not the live host):
+ * **Adapter architecture (current releases).** `.codex/config.toml` routes
+ * every Codex lifecycle event to one script,
+ * `.codex/hooks/hq-codex-hook-adapter.sh`, which reads `.claude/settings.json`
+ * live and dispatches the canonical `.claude/hooks/` scripts — one policy
+ * implementation shared by Claude and Codex, no per-hook mirrors. When that
+ * routing is present the doctor grades:
+ *
+ *   1. The adapter script itself (present + executable) and the dispatch
+ *      library it sources (`core/scripts/lib/hook-adapter-core.sh`).
+ *   2. Event coverage — each required lifecycle event in `.codex/config.toml`
+ *      routes through the adapter.
+ *   3. Legacy artifacts — a leftover `.codex/hooks.json` or `.codex/hooks/`
+ *      mirror that shadows a `.claude/hooks/` original is dead code from the
+ *      pre-adapter architecture. Stale copies rot (they keep bugs the Claude
+ *      original has since fixed), so each is a FAIL with a delete remediation.
+ *
+ *   Mirror-model checks (parity, missing counterparts) are not emitted in this
+ *   mode: Codex executes the Claude originals, so there is nothing to mirror.
+ *
+ * **Legacy mirror architecture (pre-adapter roots).** Codex runs duplicated
+ * copies under `.codex/hooks/`, registered in `.codex/hooks.json`, so the
+ * mirrors are the entire drift surface the doctor has to police:
  *
  *   1. Enumerates the registrations in `.codex/hooks.json` and verifies each
  *      referenced script exists and is executable — the Codex analogue of the
@@ -23,10 +41,32 @@
  */
 import { type AllowedDivergenceLoad } from "../allowed-divergence.js";
 import type { CheckContext, CheckResult } from "../types.js";
+/** Basename of the single-adapter script the current architecture routes to. */
+export declare const CODEX_ADAPTER_BASENAME = "hq-codex-hook-adapter.sh";
+/** Library the adapter sources to dispatch `.claude/settings.json` live. */
+export declare const CODEX_DISPATCH_LIB_RELPATH: string;
+/**
+ * Lifecycle events the shipped `.codex/config.toml` routes through the adapter.
+ * A missing event means the Claude hooks for that event never run under Codex.
+ */
+export declare const REQUIRED_ADAPTER_EVENTS: readonly string[];
 /** Options for {@link checkCodexWiring}; all injectable for hermetic tests. */
 export interface CodexWiringOptions {
     /** Pre-loaded allowed-divergence list. Default: loaded from the tree. */
     allowed?: AllowedDivergenceLoad;
+    /** Pre-computed adapter detection. Default: detected from the tree. */
+    adapter?: CodexAdapterDetection;
+}
+/** What {@link detectCodexAdapter} learned about `.codex/config.toml`. */
+export interface CodexAdapterDetection {
+    /** True when at least one config.toml hook command routes to the adapter. */
+    detected: boolean;
+    /** Whether `.codex/config.toml` exists and was readable. */
+    configPresent: boolean;
+    /** TOML parse failure, when the file exists but could not be parsed. */
+    configParseError: string | null;
+    /** Events whose config.toml command references the adapter script. */
+    wiredEvents: string[];
 }
 /**
  * Run the Codex tier of the hooks family against the resolved HQ tree. Never
@@ -34,6 +74,12 @@ export interface CodexWiringOptions {
  * is reported as a result, not an exception.
  */
 export declare function checkCodexWiring(context: CheckContext, options?: CodexWiringOptions): CheckResult[];
+/**
+ * Inspect `.codex/config.toml` for adapter-architecture routing: any hook
+ * command that references `hq-codex-hook-adapter.sh`. A tree with no such
+ * routing (or no parseable config at all) is graded by the legacy mirror model.
+ */
+export declare function detectCodexAdapter(hqRoot: string): CodexAdapterDetection;
 /**
  * Extract the hook ids listed in `is_in_minimal_profile()` from a `hook-gate.sh`
  * source. Scoped to that one function's `{ … }` body so the standard and strict

package/dist/lib/doctor/checks/codex-wiring.js

@@ -1,10 +1,28 @@
 /**
- * Codex hook wiring and Claude-parity checks (US-005).
+ * Codex hook wiring checks (US-005), covering both Codex architectures.
  *
- * Claude and Grok both execute the canonical `.claude/hooks/` scripts; only
- * Codex runs duplicated copies under `.codex/hooks/`, so Codex is the entire
- * drift surface the doctor has to police. This check does three things, all
- * read-only and all against the resolved HQ tree (not the live host):
+ * **Adapter architecture (current releases).** `.codex/config.toml` routes
+ * every Codex lifecycle event to one script,
+ * `.codex/hooks/hq-codex-hook-adapter.sh`, which reads `.claude/settings.json`
+ * live and dispatches the canonical `.claude/hooks/` scripts — one policy
+ * implementation shared by Claude and Codex, no per-hook mirrors. When that
+ * routing is present the doctor grades:
+ *
+ *   1. The adapter script itself (present + executable) and the dispatch
+ *      library it sources (`core/scripts/lib/hook-adapter-core.sh`).
+ *   2. Event coverage — each required lifecycle event in `.codex/config.toml`
+ *      routes through the adapter.
+ *   3. Legacy artifacts — a leftover `.codex/hooks.json` or `.codex/hooks/`
+ *      mirror that shadows a `.claude/hooks/` original is dead code from the
+ *      pre-adapter architecture. Stale copies rot (they keep bugs the Claude
+ *      original has since fixed), so each is a FAIL with a delete remediation.
+ *
+ *   Mirror-model checks (parity, missing counterparts) are not emitted in this
+ *   mode: Codex executes the Claude originals, so there is nothing to mirror.
+ *
+ * **Legacy mirror architecture (pre-adapter roots).** Codex runs duplicated
+ * copies under `.codex/hooks/`, registered in `.codex/hooks.json`, so the
+ * mirrors are the entire drift surface the doctor has to police:
  *
  *   1. Enumerates the registrations in `.codex/hooks.json` and verifies each
  *      referenced script exists and is executable — the Codex analogue of the
@@ -23,7 +41,26 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { parse as parseToml } from "smol-toml";
 import { ALLOWED_DIVERGENCE_RELPATH, loadAllowedDivergence, } from "../allowed-divergence.js";
+/** Basename of the single-adapter script the current architecture routes to. */
+export const CODEX_ADAPTER_BASENAME = "hq-codex-hook-adapter.sh";
+/** Library the adapter sources to dispatch `.claude/settings.json` live. */
+export const CODEX_DISPATCH_LIB_RELPATH = path.join("core", "scripts", "lib", "hook-adapter-core.sh");
+/**
+ * Lifecycle events the shipped `.codex/config.toml` routes through the adapter.
+ * A missing event means the Claude hooks for that event never run under Codex.
+ */
+export const REQUIRED_ADAPTER_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "Stop",
+    "SubagentStop",
+    "PreCompact",
+    "SessionEnd",
+];
 /**
  * Run the Codex tier of the hooks family against the resolved HQ tree. Never
  * throws for a merely-broken tree — a missing or malformed `.codex/hooks.json`
@@ -32,6 +69,7 @@ import { ALLOWED_DIVERGENCE_RELPATH, loadAllowedDivergence, } from "../allowed-d
 export function checkCodexWiring(context, options = {}) {
     const hqRoot = context.hqRoot;
     const allowed = options.allowed ?? loadAllowedDivergence(hqRoot);
+    const adapter = options.adapter ?? detectCodexAdapter(hqRoot);
     const results = [];
     results.push({
         status: "NA",
@@ -39,8 +77,21 @@ export function checkCodexWiring(context, options = {}) {
         target: "codex",
         message: "Codex hook checks are wiring only (registration, executable bit, and Claude parity); live Codex hook execution is verified only when the doctor runs under the Codex host.",
     });
-    results.push(...checkRegistrations(hqRoot));
-    results.push(...checkParity(hqRoot, allowed));
+    if (adapter.detected) {
+        results.push(...checkAdapterWiring(hqRoot, adapter, allowed));
+    }
+    else {
+        if (adapter.configPresent && adapter.configParseError) {
+            results.push({
+                status: "WARN",
+                checkId: "hooks.codex.adapter-config",
+                target: path.join(".codex", "config.toml"),
+                message: `.codex/config.toml exists but could not be parsed as TOML (${adapter.configParseError}); grading Codex wiring by the legacy mirror model instead.`,
+            });
+        }
+        results.push(...checkRegistrations(hqRoot));
+        results.push(...checkParity(hqRoot, allowed));
+    }
     for (const problem of allowed.problems) {
         results.push({
             status: "WARN",
@@ -51,6 +102,190 @@ export function checkCodexWiring(context, options = {}) {
     }
     return results;
 }
+// --- Adapter architecture (current releases) -----------------------------------
+/**
+ * Inspect `.codex/config.toml` for adapter-architecture routing: any hook
+ * command that references `hq-codex-hook-adapter.sh`. A tree with no such
+ * routing (or no parseable config at all) is graded by the legacy mirror model.
+ */
+export function detectCodexAdapter(hqRoot) {
+    const configPath = path.join(hqRoot, ".codex", "config.toml");
+    let source;
+    try {
+        source = fs.readFileSync(configPath, "utf8");
+    }
+    catch {
+        return {
+            detected: false,
+            configPresent: false,
+            configParseError: null,
+            wiredEvents: [],
+        };
+    }
+    let doc;
+    try {
+        doc = parseToml(source);
+    }
+    catch (error) {
+        return {
+            detected: false,
+            configPresent: true,
+            configParseError: error.message,
+            wiredEvents: [],
+        };
+    }
+    const wiredEvents = [];
+    const hooks = doc?.hooks;
+    if (hooks && typeof hooks === "object" && !Array.isArray(hooks)) {
+        for (const [event, entries] of Object.entries(hooks)) {
+            if (!Array.isArray(entries))
+                continue;
+            const routed = entries.some((entry) => {
+                const inner = entry?.hooks;
+                if (!Array.isArray(inner))
+                    return false;
+                return inner.some((hook) => {
+                    const command = hook?.command;
+                    return (typeof command === "string" &&
+                        command.includes(CODEX_ADAPTER_BASENAME));
+                });
+            });
+            if (routed)
+                wiredEvents.push(event);
+        }
+    }
+    return {
+        detected: wiredEvents.length > 0,
+        configPresent: true,
+        configParseError: null,
+        wiredEvents,
+    };
+}
+/**
+ * Grade a tree whose `.codex/config.toml` routes events through the adapter:
+ * the adapter script and its dispatch library, event coverage, leftover legacy
+ * artifacts, and now-obsolete allowed-divergence entries.
+ */
+function checkAdapterWiring(hqRoot, adapter, allowed) {
+    const results = [];
+    const adapterRelPath = path.join(".codex", "hooks", CODEX_ADAPTER_BASENAME);
+    const adapterPath = path.join(hqRoot, adapterRelPath);
+    const adapterState = fileState(adapterPath);
+    if (!adapterState.present) {
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.adapter",
+            target: adapterRelPath,
+            message: `.codex/config.toml routes Codex events to ${CODEX_ADAPTER_BASENAME}, but the adapter script is missing — no HQ hooks run under Codex.`,
+            remediation: `Restore ${adapterRelPath} from the hq-core release.`,
+        });
+    }
+    else if (!adapterState.executable) {
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.adapter",
+            target: adapterRelPath,
+            message: "Codex hook adapter is present but not executable.",
+            remediation: `chmod +x ${adapterPath}`,
+        });
+    }
+    else {
+        results.push({
+            status: "PASS",
+            checkId: "hooks.codex.adapter",
+            target: adapterRelPath,
+            message: "Codex hook adapter is present and executable; it dispatches the .claude/settings.json hooks live, so Claude and Codex share one canonical hook implementation.",
+        });
+    }
+    const dispatchLibPath = path.join(hqRoot, CODEX_DISPATCH_LIB_RELPATH);
+    if (fileState(dispatchLibPath).present) {
+        results.push({
+            status: "PASS",
+            checkId: "hooks.codex.adapter-dispatch",
+            target: CODEX_DISPATCH_LIB_RELPATH,
+            message: "Adapter dispatch library is present.",
+        });
+    }
+    else {
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.adapter-dispatch",
+            target: CODEX_DISPATCH_LIB_RELPATH,
+            message: `${CODEX_DISPATCH_LIB_RELPATH} is missing. The adapter sources it (with \`|| true\`) to dispatch .claude/settings.json hooks, so without it the adapter silently dispatches nothing.`,
+            remediation: `Restore ${CODEX_DISPATCH_LIB_RELPATH} from the hq-core release.`,
+        });
+    }
+    // Event coverage: each required lifecycle event must route through the
+    // adapter; extra wired events (future Codex additions) simply PASS.
+    const wired = new Set(adapter.wiredEvents);
+    for (const event of REQUIRED_ADAPTER_EVENTS) {
+        if (wired.has(event)) {
+            results.push({
+                status: "PASS",
+                checkId: "hooks.codex.registration",
+                target: event,
+                message: `Codex ${event} routes through the hq adapter (.codex/config.toml).`,
+            });
+        }
+        else {
+            results.push({
+                status: "FAIL",
+                checkId: "hooks.codex.registration",
+                target: event,
+                message: `Codex ${event} is not wired to the adapter in .codex/config.toml — the Claude hooks for this event never run under Codex.`,
+                remediation: `Restore the [[hooks.${event}]] block routing to ${CODEX_ADAPTER_BASENAME} from the release .codex/config.toml.`,
+            });
+        }
+    }
+    for (const event of adapter.wiredEvents) {
+        if (REQUIRED_ADAPTER_EVENTS.includes(event))
+            continue;
+        results.push({
+            status: "PASS",
+            checkId: "hooks.codex.registration",
+            target: event,
+            message: `Codex ${event} routes through the hq adapter (.codex/config.toml).`,
+        });
+    }
+    // Legacy artifacts from the pre-adapter mirror architecture. Dead code, but
+    // dangerous dead code: a stale mirror keeps bugs its Claude original has
+    // since fixed, and hooks.json invites tooling to treat mirrors as live.
+    const hooksJsonRelPath = path.join(".codex", "hooks.json");
+    if (fileState(path.join(hqRoot, hooksJsonRelPath)).present) {
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.legacy-artifact",
+            target: hooksJsonRelPath,
+            message: ".codex/hooks.json is a leftover from the pre-adapter mirror architecture — Codex registration now lives in .codex/config.toml and the adapter dispatches .claude/settings.json live.",
+            remediation: `Delete ${hooksJsonRelPath}.`,
+        });
+    }
+    const claudeSet = new Set(listShellScripts(path.join(hqRoot, ".claude", "hooks")));
+    for (const file of listShellScripts(path.join(hqRoot, ".codex", "hooks"))) {
+        if (file === CODEX_ADAPTER_BASENAME)
+            continue;
+        if (!claudeSet.has(file))
+            continue; // Codex-native script — not a mirror.
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.legacy-artifact",
+            target: file,
+            message: `.codex/hooks/${file} is a leftover mirror from the pre-adapter architecture. Codex executes the .claude/hooks original via the adapter; the dead copy only rots.`,
+            remediation: `Delete .codex/hooks/${file}.`,
+        });
+    }
+    // The allowed-divergence list is a mirror-model concept; under the adapter
+    // architecture there are no mirrors left to diverge.
+    for (const entry of allowed.entries) {
+        results.push({
+            status: "WARN",
+            checkId: "hooks.codex.allowed-divergence-stale",
+            target: entry.file,
+            message: `allowed-divergence entry for ${entry.file} is obsolete under the adapter architecture — Codex runs the Claude originals, so no mirror can diverge. Remove it so the list cannot rot.`,
+        });
+    }
+    return results;
+}
 // --- 1. Registration checks ----------------------------------------------------
 function checkRegistrations(hqRoot) {
     const results = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.99.1",
+  "version": "5.99.2",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {