@indigoai-us/hq-cli 5.115.3 → 5.115.5

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 ## [Unreleased]
 
+## [5.115.5] — 2026-09-15
+
+### Fixed
+
+- The setting that turns the end-of-turn checkpoint requirement off,
+  `HQ_CHECKPOINT_GATE`, now works from `.claude/settings.json` on every runtime.
+  Before, only Claude Code passed that setting through to the checkpoint hook,
+  so if you work in Codex or Grok, writing it in the settings file did nothing
+  and there was no sign of why. hq now reads the file itself. As with the other
+  checkpoint settings, `settings.local.json` overrides it, anything you set in
+  your terminal overrides both, and `false` or `0` written as plain JSON works
+  as well as `"0"`. If the value is something the setting does not understand,
+  hq names it and leaves the requirement on rather than guessing.
+
+## [5.115.4] — 2026-09-15
+
+### Changed
+- Search indexing now leaves qmd embeddings for a later pass when CPU or memory
+  use reaches 50%, while still updating the index. Set
+  `HQ_INDEX_MAX_LOAD_PERCENT` to another percentage, or to `0` or `off` to
+  disable this check. After 12 skipped passes or six hours, hq runs an embed
+  despite the load so search results do not fall behind forever.
+- HQ's housekeeping pass (`hq reindex`, which runs after an agent finishes a
+  turn) is much faster on large setups. On a root with 21 companies it took
+  about two and a half minutes even with nothing to do. Two things were to
+  blame. The scan that finds your workers read every folder inside any source
+  code you keep under a company, `node_modules` and `.git` included, which on
+  that root meant reading 83,950 folders to find 126 worker files. It now skips
+  those folders instead of walking them, and takes 0.4 seconds instead of 22.
+  Separately, the hook health check ran every `hq doctor` check in order to
+  read six of them; it now asks only for the group those six live in.
+- `hq doctor` takes `--only <families>`, so you can run one group of checks
+  instead of all of them: `hq doctor --only hooks`. A name it does not
+  recognise is refused rather than quietly checking nothing, and `--json`
+  records which groups ran, so a partial result cannot be read as a verdict on
+  the whole tree.
+
+### Fixed
+
+- When Claude Code's saved login has stopped working, a local bot now says it needs a sign-in and keeps your message for when it works again. Before, the bot relayed Claude Code's own "Failed to authenticate" notice as if it were the model's answer, so HQ never showed the "Sign in again" button.
+
+### Added
+
+- You can now switch off the background helper that tidies HQ after a
+  checkpoint, without giving up checkpoints themselves. Add
+  `"env": { "HQ_CHECKPOINT_AGENT": "0" }` to `.claude/settings.json` in your HQ
+  folder and the helper stops running; your checkpoint notes are still saved.
+  Set it back to `"1"` to turn it on again. It works the same whether you use
+  Claude Code, Codex or Grok, and `settings.local.json` overrides it if you
+  keep one. If the value is something the setting does not understand, hq says
+  so rather than quietly leaving the helper on.
+
 ## [5.115.3] — 2026-09-15
 
 ### Changed

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -5,6 +5,12 @@
 
 set -uo pipefail
 
+# The main block ends with `} 2>/dev/null`: a Stop hook must not spray
+# diagnostics into a session. Keep one copy of the real stderr so a
+# misconfigured operator switch — the one failure the operator alone can fix,
+# and otherwise invisible — still has somewhere to be said.
+exec 3>&2
+
 {
   self_hq="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." 2>/dev/null && pwd)"
   HQ="${CLAUDE_PROJECT_DIR:-${HQ_ROOT:-$self_hq}}"
@@ -49,6 +55,88 @@ set -uo pipefail
     return 0
   }
 
+  # checkpoint_gate_trim — strips only the edges. Deleting interior whitespace
+  # would quietly repair a typo: "f alse" would become a valid `false` and
+  # disable the gate the operator was trying to keep on.
+  checkpoint_gate_trim() {
+    local s="$1"
+    s="${s#"${s%%[![:space:]]*}"}"
+    s="${s%"${s##*[![:space:]]}"}"
+    printf '%s' "$s"
+  }
+
+  # checkpoint_gate_setting — one operator switch, resolved the way hq-cli
+  # resolves it: the process environment first, then the HQ root's
+  # `.claude/settings.json` `env` block (overlaid by `settings.local.json`, the
+  # order Claude Code merges them).
+  #
+  # Reading the file matters because only Claude Code exports that block into
+  # hook processes. Under Codex or grok the variable is never set, so an
+  # operator who wrote the switch into settings.json would have had it silently
+  # ignored on exactly the runtimes where they cannot see why. Fail-open: any
+  # missing file, absent jq, or unreadable value leaves the gate at its default.
+  #
+  # Prints the raw value and returns 0 when one resolves. Returns 1 when the
+  # highest-priority file that mentions the key holds something unreadable — a
+  # present key stops the lookup rather than falling through, so a stale `"0"`
+  # further down cannot be promoted by a typo in the file above it. Same
+  # precedence the TypeScript resolver uses.
+  checkpoint_gate_setting() {
+    local key="$1" value="" file raw
+    eval "value=\${$key:-}"
+    value="$(checkpoint_gate_trim "$value")"
+    if [ -n "$value" ]; then
+      printf '%s' "$value"
+      return 0
+    fi
+    command -v jq >/dev/null 2>&1 || return 0
+    for file in "$HQ/.claude/settings.local.json" "$HQ/.claude/settings.json"; do
+      [ -r "$file" ] || continue
+      # Strings, and JSON's own true/false/0/1 — the literal an operator reaches
+      # for first — all resolve; null, an object, or an array does not. The
+      # leading marker separates "absent" (no output) from "present but
+      # unreadable" (`-`), which a bare value could not encode.
+      raw="$(jq -r --arg k "$key" '
+        try (
+          if (.env | type) == "object" and (.env | has($k))
+          then (.env[$k]
+                | if type == "string" or type == "boolean" or type == "number"
+                  then "+" + tostring
+                  else "-" end)
+          else empty end
+        ) catch empty' "$file" 2>/dev/null || true)"
+      case "$raw" in
+        "") continue ;;
+        -*) ;;
+        +*)
+          value="$(checkpoint_gate_trim "${raw#+}")"
+          if [ -n "$value" ]; then
+            printf '%s' "$value"
+            return 0
+          fi
+          ;;
+      esac
+      printf 'checkpoint-stop-gate: ignoring %s in %s (not a value it can read; expected a string such as "0" or "1")\n' \
+        "$key" "$file" >&3 2>/dev/null
+      return 1
+    done
+    return 0
+  }
+
+  # Normalizes one switch to 0, 1, or empty (= not set). An unreadable value is
+  # named on stderr rather than passed over: the operator asked for something.
+  checkpoint_gate_switch() {
+    local key="$1" raw
+    raw="$(checkpoint_gate_setting "$key" 2>/dev/null)" || return 0
+    [ -n "$raw" ] || return 0
+    case "$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')" in
+      0|false|off|no) printf '0' ;;
+      1|true|on|yes) printf '1' ;;
+      *) printf 'checkpoint-stop-gate: ignoring %s=%s (expected 0/1, false/true, off/on or no/yes)\n' "$key" "$raw" >&3 2>/dev/null ;;
+    esac
+    return 0
+  }
+
   input="$(cat 2>/dev/null || printf '{}')"
   input_fields="$(printf '%s' "$input" | jq -r '[.transcript_path // "", .session_id // ""] | @tsv' 2>/dev/null)" || exit 0
   IFS=$'\t' read -r transcript_path session_id <<<"$input_fields" || exit 0
@@ -57,6 +145,15 @@ set -uo pipefail
   # recursively demand another checkpoint of itself.
   [ "${HQ_CHECKPOINT_SIBLING:-}" = "1" ] && exit 0
 
+  # Resolved once: every branch below reads this instead of the raw variable.
+  gate_switch="$(checkpoint_gate_switch HQ_CHECKPOINT_GATE)"
+  # That was the only diagnostic, so drop the duplicate before anything is
+  # spawned. The detached `nohup ... &` commands below redirect fds 1 and 2
+  # only: a surviving fd 3 would be inherited by them and hold the hook
+  # runner's stderr pipe open, so a runner that reads stderr to EOF would wait
+  # on the supposedly detached checkpoint instead of on this shell.
+  exec 3>&-
+
   # Company-scope gate ---------------------------------------------------------
   # An OPT-IN requirement layered onto this Stop hook: for an operator whose
   # email domain is listed in HQ_CHECKPOINT_SCOPE_GATE_DOMAINS (comma-separated,
@@ -69,7 +166,7 @@ set -uo pipefail
   # alongside the checkpoint gate. Binding is a single recoverable call, so the
   # block loops only until the operator declares a scope.
   gate_domains="${HQ_CHECKPOINT_SCOPE_GATE_DOMAINS:-}"
-  case "${HQ_CHECKPOINT_GATE:-}" in
+  case "$gate_switch" in
     0) ;;
     *)
       gate_session_id="$(printf '%s' "$input" | jq -r '.session_id // ""' 2>/dev/null || true)"
@@ -120,7 +217,7 @@ set -uo pipefail
             *) [ -d "$gate_root/companies/$bound_co" ] && gate_bound=1 ;;
           esac
           if [ "$gate_bound" = 0 ]; then
-            company_reason="$(printf 'This session has not declared its scope, and a scope is required before the turn can end. Decide where this work belongs, then bind the session and finish the turn with your user-facing reply as the final text after the command output:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug <company-slug>\n\nUse a real tenant slug from companies/manifest.yaml — the company this session is actually working in, never an invented one. If this session does no company-scoped work, bind it to the reserved personal scope instead:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug personal\n\nAn operator can also disable this requirement for the run by exporting HQ_CHECKPOINT_GATE=0.' "$gate_root" "$gate_session_id" "$gate_root" "$gate_session_id")"
+            company_reason="$(printf 'This session has not declared its scope, and a scope is required before the turn can end. Decide where this work belongs, then bind the session and finish the turn with your user-facing reply as the final text after the command output:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug <company-slug>\n\nUse a real tenant slug from companies/manifest.yaml — the company this session is actually working in, never an invented one. If this session does no company-scoped work, bind it to the reserved personal scope instead:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug personal\n\nAn operator can also disable this requirement for the run by exporting HQ_CHECKPOINT_GATE=0, or for every runtime by putting \"env\": {\"HQ_CHECKPOINT_GATE\": \"0\"} in .claude/settings.json.' "$gate_root" "$gate_session_id" "$gate_root" "$gate_session_id")"
             printf '{"decision":"block","reason":%s}\n' "$(printf '%s' "$company_reason" | hq_json_encode)"
             exit 0
           fi
@@ -133,7 +230,7 @@ set -uo pipefail
 
   # Operator switches precede runtime and identity eligibility. A forced gate
   # intentionally bypasses the rollout rules for local trials and tests.
-  case "${HQ_CHECKPOINT_GATE:-}" in
+  case "$gate_switch" in
     0) exit 0 ;;
     1) enforce=true ;;
     *)
@@ -151,7 +248,7 @@ set -uo pipefail
 
   refresh_eligibility() {
     command -v hq >/dev/null 2>&1 || return 0
-    (nohup env HQ_CHECKPOINT_RUNTIME="$runtime" hq core checkpoint --gate-probe >/dev/null 2>&1 &)
+    (nohup env HQ_CHECKPOINT_RUNTIME="$runtime" hq core checkpoint --gate-probe >/dev/null 2>&1 3>&- &)
   }
 
   if [ "$runtime" = "codex" ] && [ "$enforce" = false ]; then
@@ -511,7 +608,7 @@ set -uo pipefail
        --trigger stop-gate-auto \
        --transcript "$transcript_path" \
        --summary "turn ended with its user-facing reply already delivered" \
-       >/dev/null 2>&1 &)
+       >/dev/null 2>&1 3>&- &)
     rm -f "$block_count_file" 2>/dev/null || true
     exit 0
   fi

package/dist/command-catalog.generated.d.ts

@@ -4534,7 +4534,7 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "touch stamps without a checkpoint";
         }, {
             readonly flags: "--no-agent";
-            readonly description: "do not spawn the maintenance sibling";
+            readonly description: "do not spawn the maintenance sibling (set it off for good with \"env\": {\"HQ_CHECKPOINT_AGENT\": \"0\"} in .claude/settings.json)";
         }, {
             readonly flags: "--backend <auto|claude|codex|grok|none>";
             readonly description: "sibling backend";
@@ -4952,6 +4952,9 @@ export declare const COMMAND_CATALOG: readonly [{
     }, {
         readonly flags: "--company <slug>";
         readonly description: "Company slug for integrations checks (otherwise resolves your single active company).";
+    }, {
+        readonly flags: "--only <families>";
+        readonly description: "Run only these comma-separated check families (e.g. hooks). Unknown names are rejected; --json then records the scope.";
     }, {
         readonly flags: "--fix";
         readonly description: "Apply the allowlisted safe repairs (backs up first; read-only without this flag).";

package/dist/command-catalog.generated.js

@@ -5867,7 +5867,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--no-agent",
-                        "description": "do not spawn the maintenance sibling"
+                        "description": "do not spawn the maintenance sibling (set it off for good with \"env\": {\"HQ_CHECKPOINT_AGENT\": \"0\"} in .claude/settings.json)"
                     },
                     {
                         "flags": "--backend <auto|claude|codex|grok|none>",
@@ -6392,6 +6392,10 @@ export const COMMAND_CATALOG = [
                 "flags": "--company <slug>",
                 "description": "Company slug for integrations checks (otherwise resolves your single active company)."
             },
+            {
+                "flags": "--only <families>",
+                "description": "Run only these comma-separated check families (e.g. hooks). Unknown names are rejected; --json then records the scope."
+            },
             {
                 "flags": "--fix",
                 "description": "Apply the allowlisted safe repairs (backs up first; read-only without this flag)."

package/dist/commands/core-checkpoint.d.ts

@@ -59,6 +59,13 @@ export declare function writeStamps(liveRoot: string, sessionId: string | undefi
  * tested directly.
  */
 export declare function autoBackendPreference(): SpawnableBackend[];
+/**
+ * Whether the maintenance sibling may run at all. The process environment wins
+ * over the settings file, so a one-off `HQ_CHECKPOINT_AGENT=0 hq core
+ * checkpoint …` still works and a host that exports the settings `env` block
+ * (Claude Code does) agrees with a host that does not.
+ */
+export declare function siblingEnabledBySetting(liveRoot: string): boolean;
 export declare function siblingArgs(backend: SpawnableBackend, prompt: string): string[];
 /** Attach the native checkpoint command to the hidden `hq core` group. */
 export declare function registerCoreCheckpointCommand(core: Command): void;

package/dist/commands/core-checkpoint.js

@@ -32,6 +32,31 @@ const GROK_SIBLING_MAX_TURNS = "100";
  * unavailable, unresponsive, out of credits (surfaces as a crashed run), or
  * simply unknown. First healthy candidate wins.
  */
+/**
+ * Durable opt-out for the maintenance sibling, read from the HQ root's
+ * `.claude/settings.json` (overlaid by `settings.local.json`, the same order
+ * Claude Code merges them):
+ *
+ *   { "env": { "HQ_CHECKPOINT_AGENT": "0" } }
+ *
+ * `--no-agent` and `--backend none` already turn the sibling off, but only for
+ * one invocation — no help when the checkpoint is fired by the Stop gate,
+ * where the user has no command line to edit. The sibling is the expensive
+ * half of a checkpoint (an unattended agent turn per Stop), so the off switch
+ * has to be somewhere a user can set it once. The `env` block is that place:
+ * Claude Code already exports it into hook processes, and reading the file
+ * directly means the setting also holds for the Codex and grok gates, whose
+ * hosts never read it.
+ */
+const SIBLING_SETTING = "HQ_CHECKPOINT_AGENT";
+/**
+ * The Stop gate's own switch. Resolved through the same settings file as the
+ * sibling switch so it reaches Codex and grok, whose hosts never export the
+ * `.claude/settings.json` `env` block into a hook process.
+ */
+const GATE_SETTING = "HQ_CHECKPOINT_GATE";
+const SIBLING_SETTING_OFF = new Set(["0", "false", "off", "no"]);
+const SIBLING_SETTING_ON = new Set(["1", "true", "on", "yes"]);
 const FALLBACK_BACKEND_ORDER = ["claude", "codex", "grok"];
 /** A backend that cannot answer `--version` this fast is treated as broken. */
 const BACKEND_PROBE_TIMEOUT_MS = 10_000;
@@ -426,12 +451,13 @@ function checkpointGateRuntime() {
         return runtime;
     return "other";
 }
-function gateEligibility(runtime) {
-    const forced = process.env.HQ_CHECKPOINT_GATE;
-    if (forced === "0")
-        return false;
-    if (forced === "1")
-        return true;
+function gateEligibility(runtime, liveRoot) {
+    // An operator switch precedes runtime and identity eligibility, and is read
+    // from the settings file as well as the environment: under Codex and grok the
+    // environment is the one place the operator cannot reach.
+    const forced = resolveSwitchSetting(liveRoot, GATE_SETTING);
+    if (forced !== undefined)
+        return forced;
     if (runtime === "claude")
         return true;
     if (runtime !== "codex")
@@ -453,7 +479,7 @@ function writeGateVerdict(liveRoot) {
     const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
     fs.mkdirSync(stateDir, { recursive: true });
     const runtime = checkpointGateRuntime();
-    const eligible = gateEligibility(runtime);
+    const eligible = gateEligibility(runtime, liveRoot);
     fs.writeFileSync(path.join(stateDir, `checkpoint-gate-eligible-${runtime}`), eligible ? "1" : "0");
     printResult(eligible ? "eligible" : "ineligible");
 }
@@ -578,10 +604,95 @@ export function autoBackendPreference() {
         return [...FALLBACK_BACKEND_ORDER];
     return [caller, ...FALLBACK_BACKEND_ORDER.filter((name) => name !== caller)];
 }
-function resolveBackend(requested, liveRoot) {
+function settingsEnvValue(liveRoot, key) {
+    // settings.local.json wins, matching Claude Code's own merge order.
+    for (const file of ["settings.local.json", "settings.json"]) {
+        const settingsPath = path.join(liveRoot, ".claude", file);
+        let contents;
+        try {
+            contents = fs.readFileSync(settingsPath, "utf8");
+        }
+        catch {
+            continue; // absent overlay or no .claude directory at all
+        }
+        let env;
+        try {
+            env = JSON.parse(contents)?.env;
+        }
+        catch {
+            printError(`checkpoint: ignoring ${settingsPath} (not valid JSON)`);
+            continue;
+        }
+        if (!env || typeof env !== "object" || !(key in env))
+            continue;
+        const raw = env[key];
+        if (typeof raw === "string") {
+            const trimmed = raw.trim();
+            // An empty string is not a deferral to the next file: the key is here and
+            // says nothing, which is a mistake worth naming.
+            return trimmed
+                ? { kind: "value", value: trimmed, source: settingsPath }
+                : { kind: "invalid", source: settingsPath, raw };
+        }
+        // Claude Code's env block takes strings, but JSON's own `false`/`0` is what
+        // a user reaches for first. Honour it rather than ignoring the intent.
+        if (typeof raw === "boolean" || typeof raw === "number") {
+            return { kind: "value", value: String(raw), source: settingsPath };
+        }
+        return { kind: "invalid", source: settingsPath, raw };
+    }
+    return { kind: "absent" };
+}
+/** Maps one resolved value onto the switch, reporting a vocabulary it cannot read. */
+function parseSwitchSetting(key, raw, source) {
+    const value = raw.toLowerCase();
+    if (SIBLING_SETTING_OFF.has(value))
+        return false;
+    if (SIBLING_SETTING_ON.has(value))
+        return true;
+    printError(`checkpoint: ignoring ${key}=${raw} from ${source} ` +
+        "(expected 0/1, false/true, off/on or no/yes)");
+    return undefined;
+}
+/**
+ * One operator switch: the process environment first, then the HQ root's
+ * Claude settings. `undefined` means nobody set it — distinct from a setting
+ * that says "off", and distinct from one this cannot read (reported, then
+ * treated as unset so a typo never silently flips a default).
+ */
+function resolveSwitchSetting(liveRoot, key) {
+    const fromEnv = process.env[key]?.trim();
+    if (fromEnv)
+        return parseSwitchSetting(key, fromEnv, "the environment");
+    const lookup = settingsEnvValue(liveRoot, key);
+    if (lookup.kind === "absent")
+        return undefined;
+    if (lookup.kind === "invalid") {
+        printError(`checkpoint: ignoring ${key} in ${lookup.source}: ` +
+            `${JSON.stringify(lookup.raw) ?? String(lookup.raw)} is not a value it can read ` +
+            '(expected a string such as "0" or "1")');
+        return undefined;
+    }
+    return parseSwitchSetting(key, lookup.value, lookup.source);
+}
+/**
+ * Whether the maintenance sibling may run at all. The process environment wins
+ * over the settings file, so a one-off `HQ_CHECKPOINT_AGENT=0 hq core
+ * checkpoint …` still works and a host that exports the settings `env` block
+ * (Claude Code does) agrees with a host that does not.
+ */
+export function siblingEnabledBySetting(liveRoot) {
+    return resolveSwitchSetting(liveRoot, SIBLING_SETTING) ?? true;
+}
+/** Rejects an unknown `--backend` without paying for the probe that resolves one. */
+function assertKnownBackend(requested) {
     const value = requested ?? "auto";
     if (!BACKENDS.has(value))
         usage(`checkpoint: unknown backend: ${value}`);
+    return value;
+}
+function resolveBackend(requested, liveRoot) {
+    const value = assertKnownBackend(requested);
     // An explicitly named backend is honoured as given; only `auto` shops around.
     if (value !== "auto")
         return value;
@@ -869,7 +980,12 @@ function runCheckpoint(options, command, group) {
     if (!input.summary?.trim()) {
         usage("checkpoint: --summary is required unless --idle or --gate-probe is used");
     }
-    const backend = resolveBackend(options.backend, liveRoot);
+    // Resolved before resolveBackend so an opted-out run pays for no backend
+    // probe: `--backend auto` shells out to every installed CLI for a version.
+    const siblingOptOut = options.agent === false || !siblingEnabledBySetting(liveRoot);
+    // Validated even when nothing will spawn, so `--backend bogus` is still an error.
+    const requestedBackend = assertKnownBackend(options.backend);
+    const backend = siblingOptOut ? "none" : resolveBackend(requestedBackend, liveRoot);
     const now = new Date();
     const threadId = `T-${formatTimestamp(now)}-auto-${summarySlug(input.summary)}`;
     const threadPath = path.join(liveRoot, "workspace", "threads", `${threadId}.json`);
@@ -890,7 +1006,7 @@ function runCheckpoint(options, command, group) {
                 worker: input.worker,
             },
             stamps: stampPaths.map((stampPath) => path.relative(liveRoot, stampPath)),
-            sibling: options.agent === false ? null : { backend },
+            sibling: siblingOptOut ? null : { backend },
         });
         return;
     }
@@ -926,7 +1042,10 @@ function runCheckpoint(options, command, group) {
     // requested backend that is not installed).
     try {
         if (options.agent !== false) {
-            if (backend === "none") {
+            if (siblingOptOut) {
+                printResult(`checkpoint: sibling disabled (${SIBLING_SETTING})`);
+            }
+            else if (backend === "none") {
                 printResult("checkpoint: sibling disabled (backend none)");
             }
             else {
@@ -966,7 +1085,7 @@ export function registerCoreCheckpointCommand(core) {
         .option("--transcript <path>", "session transcript path")
         .option("--payload <file|->", "JSON payload file, or - for stdin")
         .option("--idle", "touch stamps without a checkpoint")
-        .option("--no-agent", "do not spawn the maintenance sibling")
+        .option("--no-agent", `do not spawn the maintenance sibling (set it off for good with "env": {"${SIBLING_SETTING}": "0"} in .claude/settings.json)`)
         .option("--backend <auto|claude|codex|grok|none>", "sibling backend", "auto")
         .option("--gate-probe", "write the local Stop-hook eligibility verdict")
         .option("--hq-root <path>", "HQ installation to operate on")

package/dist/commands/doctor.d.ts

@@ -89,6 +89,16 @@ export interface RunDoctorOptions {
     company?: string;
     /** Internal test seam; production CLI always runs integrations checks. */
     integrations?: boolean;
+    /**
+     * Run only these check families (`--only`). Omitted or empty runs them all.
+     *
+     * This exists for callers that need one family's verdict and nothing else —
+     * `core/scripts/check-hq-hooks.sh` reads six hook check ids, and `hq reindex`
+     * runs that checker on every pass. Without scoping they pay for every other
+     * family too, which on a large tree is dominated by the per-company sync
+     * journal scan. An unknown id is an error, never a silent empty run.
+     */
+    only?: readonly string[];
 }
 /** The outcome of a doctor run, returned rather than thrown so it is testable. */
 export interface RunDoctorResult {

package/dist/commands/doctor.js

@@ -93,7 +93,25 @@ export async function runDoctor(options = {}) {
             `  Run hq doctor from inside your HQ root.\n`);
         return { exitCode: 1, hqRoot: null, families: [] };
     }
-    const registry = options.registry ?? createDefaultRegistry();
+    const fullRegistry = options.registry ?? createDefaultRegistry();
+    const requested = options.only && options.only.length > 0 ? [...options.only] : undefined;
+    let registry = fullRegistry;
+    let scope;
+    if (requested) {
+        const selection = fullRegistry.select(requested);
+        // The deep families are appended by `--deep-test` rather than registered,
+        // so they are addressable only when that flag is present — naming one
+        // without it is the same mistake as naming a family that does not exist.
+        const appendable = options.deepTest ? [DEEP_FAMILY_ID, PARITY_FAMILY_ID] : [];
+        const unknown = selection.unknown.filter((id) => !appendable.includes(id));
+        if (unknown.length > 0) {
+            writeErr(`hq doctor --only: unknown check ${unknown.length === 1 ? "family" : "families"}: ${unknown.join(", ")}\n` +
+                `  Available: ${[...fullRegistry.ids(), ...appendable].join(", ")}\n`);
+            return { exitCode: 1, hqRoot, families: [] };
+        }
+        registry = selection.registry;
+        scope = [...registry.ids(), ...appendable.filter((id) => requested.includes(id))];
+    }
     const platform = options.platform ?? UNKNOWN_PLATFORM;
     // The detected platform and the session id are exposed to every check so the
     // host-specific runtime probe (US-006) can decide UNKNOWN vs FAIL vs UNTESTED.
@@ -111,7 +129,11 @@ export async function runDoctor(options = {}) {
     // own family. Run only when asked — appending here, not in the default
     // registry, is what keeps `hq doctor` from ever spawning a hook without the
     // flag. Any FAIL/UNKNOWN it produces flows through computeExitCode below.
-    if (options.deepTest) {
+    // The deep families are appended here rather than registered, so the `--only`
+    // filter has to be applied to them explicitly — otherwise
+    // `--only hooks --deep-test` would still sandbox-fire every hook.
+    const inScope = (id) => !requested || requested.includes(id);
+    if (options.deepTest && inScope(DEEP_FAMILY_ID)) {
         const deepResults = await runDeepGuardTests(context);
         // US-009: side-effecting hooks (autocommit, checkpoint, journal, reindex, …)
         // cannot be verified by verdict, so they run in throwaway sandboxes and their
@@ -122,10 +144,12 @@ export async function runDoctor(options = {}) {
             family: { id: DEEP_FAMILY_ID, title: DEEP_FAMILY_TITLE },
             results: [...deepResults, ...effectResults],
         });
-        // Cross-platform parity replay (US-010): replay every pure-guard fixture
-        // case through the Claude, Codex, and Grok adapters and compare verdicts, so
-        // platform drift surfaces as a test result. Also gated behind --deep-test,
-        // and it too runs only in its own sandbox — never the live tree.
+    }
+    // Cross-platform parity replay (US-010): replay every pure-guard fixture
+    // case through the Claude, Codex, and Grok adapters and compare verdicts, so
+    // platform drift surfaces as a test result. Also gated behind --deep-test,
+    // and it too runs only in its own sandbox — never the live tree.
+    if (options.deepTest && inScope(PARITY_FAMILY_ID)) {
         const parityResults = await runParityReplay(context);
         families.push({
             family: { id: PARITY_FAMILY_ID, title: PARITY_FAMILY_TITLE },
@@ -133,7 +157,7 @@ export async function runDoctor(options = {}) {
         });
     }
     if (options.json) {
-        write(renderJson(buildDoctorJson({ hqRoot, families, platform })));
+        write(renderJson(buildDoctorJson({ hqRoot, families, platform, scope })));
     }
     else {
         write(renderText({
@@ -160,10 +184,24 @@ export function registerDoctorCommand(program) {
         .option("--deep-test", "Also fire pure-guard hooks through the real gate under all three profiles (sandboxed).")
         .option("--live-runtimes", "Also probe each installed AI CLI (claude, codex, grok) with a one-line prompt to verify login and subscription (networked; uses your subscriptions).")
         .option("--company <slug>", "Company slug for integrations checks (otherwise resolves your single active company).")
+        .option("--only <families>", "Run only these comma-separated check families (e.g. hooks). Unknown names are rejected; --json then records the scope.")
         .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
         .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
         .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
         .action(async (opts) => {
+        // `--fix` repairs the whole tree from its own allowlist and has no
+        // notion of a check family, so a scope passed alongside it could only
+        // be ignored. Ignoring it silently is the dangerous reading: an
+        // operator who wrote `--only sync --fix` would believe they had scoped
+        // hook configuration out of a write, and `--only typo --fix` would slip
+        // past the unknown-family rejection. Refuse the combination instead.
+        if (opts.fix === true && parseOnly(opts.only) !== undefined) {
+            process.stderr.write(`hq doctor: --only cannot be combined with --fix.\n` +
+                `  --fix applies the allowlisted repairs across the whole tree; it has no family scope.\n` +
+                `  Inspect with \`hq doctor --only ${parseOnly(opts.only)?.join(",")}\`, then repair with \`hq doctor --fix\`.\n`);
+            process.exitCode = 1;
+            return;
+        }
         // `--fix` is the only write path. It resolves the tree, applies the
         // allowlisted repairs behind a backup + confirmation, and returns its own
         // exit code; the read-only report below never runs in this branch.
@@ -208,6 +246,7 @@ export function registerDoctorCommand(program) {
             deepTest: opts.deepTest === true,
             liveRuntimes: opts.liveRuntimes === true,
             company: opts.company,
+            only: parseOnly(opts.only),
         });
         // Set the exit code rather than calling process.exit, so the CLI's
         // normal shutdown (telemetry flush) still runs. Non-zero means either an
@@ -215,6 +254,19 @@ export function registerDoctorCommand(program) {
         process.exitCode = result.exitCode;
     });
 }
+/**
+ * Split `--only` into family ids. Blank entries are dropped so a trailing comma
+ * or a quoted empty string reads as "no scope" rather than as a family named "".
+ */
+function parseOnly(value) {
+    if (value === undefined)
+        return undefined;
+    const ids = value
+        .split(",")
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0);
+    return ids.length > 0 ? ids : undefined;
+}
 /**
  * Interactive y/N confirmation for `--fix`. Resolves false on a non-TTY stdin
  * (so a piped run without `--yes` writes nothing) and on anything other than an

package/dist/commands/index-cmd.d.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { type RunQmdOptions, type SearchCollection, type QmdProcessResult } from '../lib/search-index/index.js';
 import { type BackgroundDependencies, type BackgroundResult, type BackgroundStatus } from '../lib/search-index/background.js';
 import { type EmbedLockDependencies } from '../lib/search-index/embed-lock.js';
+import { type LoadGateDependencies } from '../lib/search-index/load-gate.js';
 export type SearchIndexDependencies = {
     reconcileCollections: (hqRoot: string) => unknown;
     /** Apply the per-document size cap to qmd's config before the update reads anything. */
@@ -16,6 +17,8 @@ export type SearchIndexDependencies = {
     backgroundStatus?: (dependencies: BackgroundDependencies) => BackgroundStatus;
     /** Test seams for the lock shared by every hq-cli embed entry point. */
     embedLockDependencies?: EmbedLockDependencies;
+    /** Test seams for the host load gate consulted while the embed lock is held. */
+    loadGateDependencies?: LoadGateDependencies;
     writeStderr?: (text: string) => void;
 };
 export type SyncSearchIndexResult = {