@indigoai-us/hq-cli 5.99.0 → 5.99.2

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [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
 
 ### Added

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/commands/core-checkpoint.js

@@ -552,7 +552,7 @@ export function siblingArgs(backend, prompt) {
                 // journal helper, the queue-draining `mv` — hits an approval gate with
                 // no human attached; headless `claude -p` then denies it and the run
                 // stalls having written no report. `bypassPermissions` is the same
-                // unattended posture codex gets from `-s workspace-write` and grok from
+                // unattended posture codex gets from `-s danger-full-access` and grok from
                 // `--always-approve --sandbox workspace`. Hooks still fire natively —
                 // this only removes the interactive approval gate, not the hook chain.
                 "--permission-mode",
@@ -570,7 +570,7 @@ export function siblingArgs(backend, prompt) {
                 // scan, the journal helper — then hits an approval gate with no human
                 // attached, and grok cancels the whole run: `stopReason: cancelled,
                 // cancellationCategory: PermissionCancelled`. Unattended approval plus
-                // a sandbox is the same posture codex gets from `-s workspace-write`.
+                // a sandbox is the same posture codex gets from `-s danger-full-access`.
                 "--always-approve",
                 "--sandbox",
                 "workspace",
@@ -581,8 +581,16 @@ export function siblingArgs(backend, prompt) {
             return [
                 "exec",
                 "--skip-git-repo-check",
+                // danger-full-access, NOT workspace-write. `-s workspace-write` force-
+                // enables Codex's restrictive sandbox, which denies the temp/cache/socket
+                // writes the maintenance sibling needs on macOS (git/Xcode cache, zsh/asdf
+                // heredocs) and cannot even initialize bubblewrap on some Linux hosts
+                // (`bwrap: loopback: Failed RTM_NEWADDR`) — HQ harness finding 2.3, which
+                // wedged the sibling before it wrote any report. HQ's safety boundary is
+                // its hooks, which still fire here via --dangerously-bypass-hook-trust;
+                // the sandbox is not what guards the HQ root.
                 "-s",
-                "workspace-write",
+                "danger-full-access",
                 "--dangerously-bypass-hook-trust",
                 "-m",
                 CODEX_SIBLING_MODEL,

package/dist/commands/core.js

@@ -44,6 +44,8 @@ import { createWorktree } from "../lib/core-utils/worktree.js";
 import { runCodexSkillBridgeCommand } from "../lib/core-utils/codex-skill-bridge-entry.js";
 import { archiveOldThreads } from "../lib/core-utils/archive-old-threads.js";
 import { qmdReindexAfterSync } from "../lib/core-utils/qmd-reindex-after-sync.js";
+import { softTimeoutCommand } from "../lib/core-utils/soft-timeout.js";
+import { timeoutGuardCommand } from "../lib/core-utils/timeout-guard.js";
 /**
  * These commands are now native implementations. Their retained shell assets
  * are deliberately claimed in SCAFFOLD_ONLY_ASSETS: loose HQ trees still ship
@@ -421,6 +423,39 @@ export function registerCoreCommands(program) {
             runCommand(entry, args, cmd);
         });
     }
+    // `hq core soft-timeout <interval> [--hard-cap <spec>] [--label <name>] -- <cmd…>`
+    // Async and bespoke (the NATIVE_UTILITY_COMMANDS table is synchronous), since
+    // it spawns a child and warns over time. Warn-don't-kill primitive for
+    // finding 2.1 — the CLI-hosted twin of core/scripts/lib/soft-timeout.sh.
+    core
+        .command("soft-timeout")
+        .description("Run a command under a soft (warn, don't kill) timeout")
+        // Passthrough: the wrapped command owns everything after `--`.
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .helpOption(false)
+        .argument("[args...]", "<interval> [--hard-cap <spec>] [--label <name>] -- <cmd...>")
+        .action(async (args = [], _opts, cmd) => {
+        const operands = cmd.args.length > 0 ? cmd.args : args;
+        const code = await softTimeoutCommand(operands);
+        if (code !== 0)
+            process.exit(code);
+    });
+    // `hq core timeout-guard` — PreToolUse decision for the foreground-timeout
+    // guard (finding 2.1). Reads the hook JSON on stdin and exits 2 to block, 0
+    // to allow. The shipped .claude hook is a thin shim over this.
+    core
+        .command("timeout-guard")
+        .description("PreToolUse guard: block over-ceiling foreground timeouts (reads hook JSON on stdin)")
+        .helpOption(false)
+        .action(async () => {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        const code = timeoutGuardCommand(Buffer.concat(chunks).toString("utf8"));
+        if (code !== 0)
+            process.exit(code);
+    });
     return core;
 }
 //# sourceMappingURL=core.js.map

package/dist/lib/core-utils/soft-timeout.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `hq core soft-timeout <interval> [--hard-cap <spec>] [--label <name>] -- <cmd…>`
+ *
+ * Run a command under a SOFT timeout: WARN, don't kill. This is the CLI-hosted
+ * form of the shell primitive `core/scripts/lib/soft-timeout.sh`, so HQ scripts
+ * and hooks can call `hq core soft-timeout …` directly instead of shelling out
+ * to a bundled script.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events):
+ * a fixed deadline SIGTERMs an operation still making progress and loses the
+ * in-flight work. The fix is warn-and-continue — on each interval the command
+ * keeps running and a SOFT-TIMEOUT notice is written to stderr so whoever is
+ * watching decides (wait / background / kill), instead of the runner deciding
+ * by killing progressing work.
+ *
+ * Contract (identical to the shell primitive):
+ *   - `<interval>` — warn every interval. Bare number = seconds; 90s / 2m / 1h.
+ *   - `--hard-cap <spec>` — OPTIONAL safety ceiling for unattended callers.
+ *     Pure soft has no cap and never terminates. At the cap the command is
+ *     SIGTERM'd, then SIGKILL'd after a short grace, and the exit code is 124.
+ *   - `--label <name>` — name shown in the notice (default: the command basename).
+ *   - Exit status: the command's own, verbatim — except 124 on a hard-cap.
+ *     A soft warning alone never changes the exit status.
+ */
+import { spawn } from "node:child_process";
+/** Parse a duration spec (Ns / Nm / Nh / bare N=seconds) to integer seconds. */
+export declare function parseDurationSecs(spec: string): number | null;
+export interface ParsedSoftTimeoutArgs {
+    intervalSecs: number;
+    hardCapSecs: number | null;
+    label: string | null;
+    command: string[];
+}
+/** Parse the `hq core soft-timeout` argv. Throws a plain Error on misuse. */
+export declare function parseSoftTimeoutArgs(argv: string[]): ParsedSoftTimeoutArgs;
+export interface RunSoftTimeoutDeps {
+    spawnFn?: typeof spawn;
+    stderr?: NodeJS.WritableStream;
+    now?: () => Date;
+    /** Signal a whole process group by (leader) pid. Defaults to process.kill(-pid). */
+    killGroup?: (pid: number, sig: NodeJS.Signals) => void;
+}
+/**
+ * Execute the command under the soft timeout. Resolves to the exit code the
+ * process should exit with. Never rejects on a timeout — a warning is only a
+ * stderr line. Rejects only on spawn failure.
+ */
+export declare function runSoftTimeout(parsed: ParsedSoftTimeoutArgs, deps?: RunSoftTimeoutDeps): Promise<number>;
+/**
+ * Entry point for the `hq core soft-timeout` command. Parses argv, runs, and
+ * returns the exit code (never throws for a timeout; throws only on misuse or
+ * spawn failure, which the caller maps to a non-zero exit).
+ */
+export declare function softTimeoutCommand(argv: string[]): Promise<number>;
+//# sourceMappingURL=soft-timeout.d.ts.map

package/dist/lib/core-utils/soft-timeout.js

@@ -0,0 +1,205 @@
+/**
+ * `hq core soft-timeout <interval> [--hard-cap <spec>] [--label <name>] -- <cmd…>`
+ *
+ * Run a command under a SOFT timeout: WARN, don't kill. This is the CLI-hosted
+ * form of the shell primitive `core/scripts/lib/soft-timeout.sh`, so HQ scripts
+ * and hooks can call `hq core soft-timeout …` directly instead of shelling out
+ * to a bundled script.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events):
+ * a fixed deadline SIGTERMs an operation still making progress and loses the
+ * in-flight work. The fix is warn-and-continue — on each interval the command
+ * keeps running and a SOFT-TIMEOUT notice is written to stderr so whoever is
+ * watching decides (wait / background / kill), instead of the runner deciding
+ * by killing progressing work.
+ *
+ * Contract (identical to the shell primitive):
+ *   - `<interval>` — warn every interval. Bare number = seconds; 90s / 2m / 1h.
+ *   - `--hard-cap <spec>` — OPTIONAL safety ceiling for unattended callers.
+ *     Pure soft has no cap and never terminates. At the cap the command is
+ *     SIGTERM'd, then SIGKILL'd after a short grace, and the exit code is 124.
+ *   - `--label <name>` — name shown in the notice (default: the command basename).
+ *   - Exit status: the command's own, verbatim — except 124 on a hard-cap.
+ *     A soft warning alone never changes the exit status.
+ */
+import { spawn } from "node:child_process";
+import { basename } from "node:path";
+import { constants as osConstants } from "node:os";
+/** Parse a duration spec (Ns / Nm / Nh / bare N=seconds) to integer seconds. */
+export function parseDurationSecs(spec) {
+    const m = /^([0-9]+)([smh]?)$/.exec(spec);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "":
+        case "s":
+            return n;
+        case "m":
+            return n * 60;
+        case "h":
+            return n * 3600;
+        default:
+            return null;
+    }
+}
+/** Parse the `hq core soft-timeout` argv. Throws a plain Error on misuse. */
+export function parseSoftTimeoutArgs(argv) {
+    const args = [...argv];
+    if (args.length === 0 || args[0].startsWith("--")) {
+        throw new Error("soft-timeout: first argument must be the warn interval");
+    }
+    const intervalSecs = parseDurationSecs(args.shift());
+    if (intervalSecs === null || intervalSecs <= 0) {
+        throw new Error("soft-timeout: interval must be a positive duration (e.g. 120, 2m)");
+    }
+    let hardCapSecs = null;
+    let label = null;
+    // Consume our own options; the FIRST non-option token (or an explicit `--`)
+    // begins the wrapped command. `--` is optional because Commander strips a
+    // single leading `--` before these args reach us — so `hq core soft-timeout
+    // 30 -- sleep 60` arrives here as `30 sleep 60`, and treating the first
+    // non-option as the command start makes both forms parse identically.
+    while (args.length > 0) {
+        const tok = args[0];
+        if (tok === "--") {
+            args.shift();
+            break;
+        }
+        if (tok === "--hard-cap") {
+            args.shift();
+            const spec = args.shift();
+            const secs = spec ? parseDurationSecs(spec) : null;
+            if (secs === null || secs <= 0)
+                throw new Error(`soft-timeout: invalid --hard-cap '${spec ?? ""}'`);
+            hardCapSecs = secs;
+        }
+        else if (tok === "--label") {
+            args.shift();
+            label = args.shift() ?? null;
+            if (label === null)
+                throw new Error("soft-timeout: --label needs a value");
+        }
+        else {
+            break; // first non-option token: the wrapped command starts here
+        }
+    }
+    if (args.length === 0) {
+        throw new Error("soft-timeout: no command given (expected: soft-timeout <interval> [...] -- cmd)");
+    }
+    return { intervalSecs, hardCapSecs, label: label ?? null, command: args };
+}
+function hhmmss(now) {
+    return now.toISOString().slice(11, 19);
+}
+/**
+ * Execute the command under the soft timeout. Resolves to the exit code the
+ * process should exit with. Never rejects on a timeout — a warning is only a
+ * stderr line. Rejects only on spawn failure.
+ */
+export function runSoftTimeout(parsed, deps = {}) {
+    const spawnFn = deps.spawnFn ?? spawn;
+    const err = deps.stderr ?? process.stderr;
+    const now = deps.now ?? (() => new Date());
+    const killGroup = deps.killGroup ?? ((pid, sig) => process.kill(-pid, sig));
+    const { intervalSecs, hardCapSecs, command } = parsed;
+    const label = parsed.label ?? basename(command[0]);
+    return new Promise((resolve, reject) => {
+        // detached: the child leads its own process group so a hard cap can signal
+        // the WHOLE group (child + descendants), not just the child — otherwise an
+        // orphaned grandchild (e.g. run-project's builder) keeps running after the
+        // wrapper returns. stdio inherited so the command's stdin/stdout/stderr —
+        // including piped or interactive input — pass through unchanged.
+        const child = spawnFn(command[0], command.slice(1), { stdio: "inherit", detached: true });
+        let capped = false;
+        let ticks = 0;
+        // Signal the child's process group when we can (detached leader), else the
+        // child alone. Guarded: the group may already be gone.
+        const signalTree = (sig) => {
+            try {
+                if (typeof child.pid === "number")
+                    killGroup(child.pid, sig);
+                else
+                    child.kill(sig);
+            }
+            catch {
+                try {
+                    child.kill(sig);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        };
+        const warner = setInterval(() => {
+            ticks += 1;
+            const elapsed = ticks * intervalSecs;
+            err.write(`[${hhmmss(now())}] SOFT-TIMEOUT: ${label} still running after ${elapsed}s ` +
+                `(${ticks}× ${intervalSecs}s window) — exceeded its window; NOT killed. ` +
+                `Decide: wait / background / kill (kill ${child.pid}).\n`);
+        }, intervalSecs * 1000);
+        // The hard cap runs on its OWN timer, independent of the warning interval,
+        // so a cap shorter than (or not a multiple of) the interval still fires on
+        // time rather than at the next interval boundary.
+        let capTimer = null;
+        let killTimer = null;
+        if (hardCapSecs !== null) {
+            capTimer = setTimeout(() => {
+                capped = true;
+                err.write(`[${hhmmss(now())}] SOFT-TIMEOUT: ${label} hit hard cap ${hardCapSecs}s — sending SIGTERM.\n`);
+                signalTree("SIGTERM");
+                killTimer = setTimeout(() => signalTree("SIGKILL"), 5000);
+            }, hardCapSecs * 1000);
+        }
+        const cleanup = () => {
+            clearInterval(warner);
+            if (capTimer)
+                clearTimeout(capTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+        };
+        child.on("error", (e) => {
+            cleanup();
+            reject(e);
+        });
+        child.on("exit", (code, signal) => {
+            cleanup();
+            if (capped) {
+                resolve(124);
+            }
+            else if (code !== null) {
+                resolve(code);
+            }
+            else {
+                // Killed by a signal (external SIGINT/SIGHUP/SIGTERM/…): mirror the
+                // shell convention of 128 + signal number for whichever signal it was,
+                // so callers keep the real termination status (e.g. 130 for SIGINT).
+                const n = signal ? osConstants.signals[signal] : undefined;
+                resolve(typeof n === "number" ? 128 + n : 1);
+            }
+        });
+    });
+}
+/**
+ * Entry point for the `hq core soft-timeout` command. Parses argv, runs, and
+ * returns the exit code (never throws for a timeout; throws only on misuse or
+ * spawn failure, which the caller maps to a non-zero exit).
+ */
+export async function softTimeoutCommand(argv) {
+    let parsed;
+    try {
+        parsed = parseSoftTimeoutArgs(argv);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    try {
+        return await runSoftTimeout(parsed);
+    }
+    catch (e) {
+        process.stderr.write(`soft-timeout: failed to run command: ${e.message}\n`);
+        return 127;
+    }
+}
+//# sourceMappingURL=soft-timeout.js.map

package/dist/lib/core-utils/timeout-guard.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `hq core timeout-guard` — PreToolUse decision for the foreground-timeout guard.
+ *
+ * The hook logic that used to live in
+ * `.claude/hooks/block-foreground-timeout-over-harness-ceiling.sh` now lives
+ * here so it can be maintained (and gated) in one place; the shipped hook is a
+ * thin shim that pipes the PreToolUse JSON to this command and blocks iff it
+ * exits 2.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events): a
+ * FOREGROUND shell tool call is SIGTERM'd at the harness's outer deadline
+ * (~2 min default, 10 min max) regardless of any longer timeout it declares, so
+ * the in-flight work is lost (exit 143). We can't change the harness, so the
+ * guard blocks a long foreground declaration and steers it to a background run
+ * (no outer deadline, auto-notifies). It fires for Claude, Codex, and Grok —
+ * their shell tool calls all reach the hook normalized to `tool_input.command`.
+ *
+ * Rollout gate: for now the guard only acts for `@getindigo.ai` HQ users; every
+ * other identity (and machine identities / logged-out) is allowed through.
+ *
+ * Exit codes: 0 = allow, 2 = block.
+ */
+/**
+ * Worst-case inner deadline (seconds) declared in a command: a `timeout` /
+ * `gtimeout` prefix (matched by executable BASENAME, so `/usr/bin/timeout`
+ * counts) or a `perl -e 'alarm(N)…'` deadline. Segment on shell separators and
+ * only treat a segment's LEADING command word as an invocation, so the word
+ * `timeout` inside a quoted argument (e.g. `printf 'uses timeout 601s'`) does
+ * not trip it.
+ */
+export declare function parseInnerDeadlineSecs(command: string): number;
+export interface TimeoutGuardInput {
+    command: string;
+    toolTimeoutMs?: number;
+    runInBackground?: boolean;
+}
+export interface GuardVerdict {
+    block: boolean;
+    reason?: string;
+}
+/**
+ * Pure decision: does this foreground declaration exceed the deadline it can
+ * actually secure? Compares the inner deadline against the EFFECTIVE ceiling —
+ * the declared tool timeout (capped at the harness max) or the 2-minute default
+ * when none is declared — rather than always against the 10-minute max.
+ */
+export declare function evaluateTimeoutGuard(input: TimeoutGuardInput): GuardVerdict;
+export interface TimeoutGuardDeps {
+    /** Resolve the current HQ user email for the rollout gate. Default: cached id token. */
+    getEmail?: () => string | undefined;
+    env?: NodeJS.ProcessEnv;
+    stderr?: NodeJS.WritableStream;
+}
+/** Whether the guard is active for this identity (rollout gate). */
+export declare function isGatedUser(email: string | undefined): boolean;
+/**
+ * Command entry: read the PreToolUse JSON, apply the gate + short-circuits, and
+ * return the exit code (0 allow / 2 block). Never throws — a parse failure or a
+ * missing identity fails OPEN (allow), because a hook must not break tool calls.
+ */
+export declare function timeoutGuardCommand(stdin: string, deps?: TimeoutGuardDeps): number;
+//# sourceMappingURL=timeout-guard.d.ts.map

package/dist/lib/core-utils/timeout-guard.js

@@ -0,0 +1,207 @@
+/**
+ * `hq core timeout-guard` — PreToolUse decision for the foreground-timeout guard.
+ *
+ * The hook logic that used to live in
+ * `.claude/hooks/block-foreground-timeout-over-harness-ceiling.sh` now lives
+ * here so it can be maintained (and gated) in one place; the shipped hook is a
+ * thin shim that pipes the PreToolUse JSON to this command and blocks iff it
+ * exits 2.
+ *
+ * Finding 2.1 (team harness analysis 2026-08-10 — 1,393 forced-kill events): a
+ * FOREGROUND shell tool call is SIGTERM'd at the harness's outer deadline
+ * (~2 min default, 10 min max) regardless of any longer timeout it declares, so
+ * the in-flight work is lost (exit 143). We can't change the harness, so the
+ * guard blocks a long foreground declaration and steers it to a background run
+ * (no outer deadline, auto-notifies). It fires for Claude, Codex, and Grok —
+ * their shell tool calls all reach the hook normalized to `tool_input.command`.
+ *
+ * Rollout gate: for now the guard only acts for `@getindigo.ai` HQ users; every
+ * other identity (and machine identities / logged-out) is allowed through.
+ *
+ * Exit codes: 0 = allow, 2 = block.
+ */
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { peekIdToken } from "../../utils/id-token.js";
+// Observed Claude Code Bash-tool bounds. The tool `timeout` (ms) raises the
+// deadline up to the max; with none declared the default applies.
+const HARNESS_DEFAULT_MS = 120_000; // 2 min
+const HARNESS_MAX_MS = 600_000; // 10 min
+const GATE_DOMAIN = "@getindigo.ai";
+function basename(token) {
+    const i = token.lastIndexOf("/");
+    return i >= 0 ? token.slice(i + 1) : token;
+}
+/** Duration spec (Ns / Nm / Nh / Nd / bare N=seconds) → seconds, or 0. */
+function durationToSecs(tok) {
+    const m = /^([0-9]+)([smhd]?)$/.exec(tok);
+    if (!m)
+        return 0;
+    const n = Number(m[1]);
+    switch (m[2]) {
+        case "":
+        case "s":
+            return n;
+        case "m":
+            return n * 60;
+        case "h":
+            return n * 3600;
+        case "d":
+            return n * 86400;
+        default:
+            return 0;
+    }
+}
+/**
+ * Worst-case inner deadline (seconds) declared in a command: a `timeout` /
+ * `gtimeout` prefix (matched by executable BASENAME, so `/usr/bin/timeout`
+ * counts) or a `perl -e 'alarm(N)…'` deadline. Segment on shell separators and
+ * only treat a segment's LEADING command word as an invocation, so the word
+ * `timeout` inside a quoted argument (e.g. `printf 'uses timeout 601s'`) does
+ * not trip it.
+ */
+export function parseInnerDeadlineSecs(command) {
+    let worst = 0;
+    for (const rawSeg of command.split(/[;|&()]/)) {
+        const seg = rawSeg.trim();
+        if (!seg)
+            continue;
+        const words = seg.split(/\s+/);
+        let i = 0;
+        while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]))
+            i++; // skip env assigns
+        if (i >= words.length)
+            continue;
+        const cmd = basename(words[i]);
+        if (cmd !== "timeout" && cmd !== "gtimeout")
+            continue;
+        i++;
+        let dur = "";
+        while (i < words.length) {
+            const t = words[i];
+            if (t === "--foreground" || t === "--preserve-status" || t === "-v" || t === "--verbose") {
+                i++;
+                continue;
+            }
+            if (t === "-s" || t === "--signal" || t === "-k" || t === "--kill-after") {
+                i += 2;
+                continue;
+            }
+            if (t.startsWith("-")) {
+                i++;
+                continue;
+            }
+            dur = t;
+            break;
+        }
+        if (dur)
+            worst = Math.max(worst, durationToSecs(dur));
+    }
+    // perl alarm() — spans separators, so match on the raw command.
+    const mMin = /alarm\(\s*([0-9]+)\s*\*\s*60/.exec(command);
+    if (mMin)
+        worst = Math.max(worst, Number(mMin[1]) * 60);
+    else {
+        const mSec = /alarm\(?\s*([0-9]+)/.exec(command);
+        if (mSec)
+            worst = Math.max(worst, Number(mSec[1]));
+    }
+    return worst;
+}
+/**
+ * Pure decision: does this foreground declaration exceed the deadline it can
+ * actually secure? Compares the inner deadline against the EFFECTIVE ceiling —
+ * the declared tool timeout (capped at the harness max) or the 2-minute default
+ * when none is declared — rather than always against the 10-minute max.
+ */
+export function evaluateTimeoutGuard(input) {
+    const { command, toolTimeoutMs } = input;
+    if (input.runInBackground)
+        return { block: false };
+    if (toolTimeoutMs !== undefined && toolTimeoutMs > HARNESS_MAX_MS) {
+        return {
+            block: true,
+            reason: `the Bash tool 'timeout' parameter is ${toolTimeoutMs}ms (> the ${HARNESS_MAX_MS}ms / 10-minute harness ceiling)`,
+        };
+    }
+    const effectiveMs = toolTimeoutMs !== undefined ? Math.min(toolTimeoutMs, HARNESS_MAX_MS) : HARNESS_DEFAULT_MS;
+    const innerSecs = parseInnerDeadlineSecs(command);
+    if (innerSecs > 0 && innerSecs * 1000 > effectiveMs) {
+        const ceilingDesc = toolTimeoutMs !== undefined
+            ? `the declared ${Math.round(effectiveMs / 1000)}s tool deadline`
+            : `the ~${HARNESS_DEFAULT_MS / 1000}s default foreground deadline`;
+        return {
+            block: true,
+            reason: `an inner ${innerSecs}s deadline (timeout/gtimeout/alarm) exceeds ${ceilingDesc}`,
+        };
+    }
+    return { block: false };
+}
+const BLOCK_MESSAGE = (reason) => `BLOCKED: this FOREGROUND command declares a timeout past the harness ceiling —
+${reason}.
+
+A foreground shell tool call is SIGTERM'd at the harness's outer deadline
+(~2 min default, 10 min max) regardless of any longer timeout you declared. It
+will die with exit 143 ("timed out after 10m 0s") and lose whatever it was doing
+— the largest harness-friction cluster in the 2026-08-10 team analysis
+(finding 2.1, 1,393 events).
+
+Do this instead: launch it as a background task (run_in_background: true).
+Background tasks survive turn boundaries, have no outer deadline, and auto-notify
+on completion. (\`hq core soft-timeout\` warns without killing for work you
+supervise yourself.)
+
+Policy: hq-foreground-timeout-killed-by-harness-deadline.
+Bypass for one sanctioned foreground run: prefix HQ_ALLOW_LONG_FOREGROUND=1.`;
+function defaultEmail() {
+    try {
+        const cached = loadCachedTokens();
+        if (!cached)
+            return undefined;
+        const email = peekIdToken(cached.idToken).email;
+        return typeof email === "string" ? email : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the guard is active for this identity (rollout gate). */
+export function isGatedUser(email) {
+    return typeof email === "string" && email.toLowerCase().endsWith(GATE_DOMAIN);
+}
+/**
+ * Command entry: read the PreToolUse JSON, apply the gate + short-circuits, and
+ * return the exit code (0 allow / 2 block). Never throws — a parse failure or a
+ * missing identity fails OPEN (allow), because a hook must not break tool calls.
+ */
+export function timeoutGuardCommand(stdin, deps = {}) {
+    const env = deps.env ?? process.env;
+    const err = deps.stderr ?? process.stderr;
+    let payload;
+    try {
+        payload = JSON.parse(stdin);
+    }
+    catch {
+        return 0;
+    }
+    const ti = payload?.tool_input ?? {};
+    const command = typeof ti.command === "string" ? ti.command : "";
+    if (!command)
+        return 0;
+    // The inline escape hatch and the env escape hatch both bypass.
+    if (env.HQ_ALLOW_LONG_FOREGROUND === "1")
+        return 0;
+    if (/(^|\s)HQ_ALLOW_LONG_FOREGROUND=1(\s|$)/.test(command))
+        return 0;
+    // Rollout gate: only act for @getindigo.ai identities.
+    const getEmail = deps.getEmail ?? defaultEmail;
+    if (!isGatedUser(getEmail()))
+        return 0;
+    const runInBackground = ti.run_in_background === true;
+    const toolTimeoutMs = typeof ti.timeout === "number" ? ti.timeout : undefined;
+    const verdict = evaluateTimeoutGuard({ command, toolTimeoutMs, runInBackground });
+    if (!verdict.block)
+        return 0;
+    err.write(`${BLOCK_MESSAGE(verdict.reason ?? "declared timeout exceeds the harness ceiling")}\n`);
+    return 2;
+}
+//# sourceMappingURL=timeout-guard.js.map

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.0",
+  "version": "5.99.2",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {