@indigoai-us/hq-cli 5.115.3 → 5.115.4

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## [Unreleased]
 
+## [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/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,25 @@ 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";
+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;
@@ -578,10 +597,86 @@ 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 parseSiblingSetting(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 ${SIBLING_SETTING}=${raw} from ${source} ` +
+        "(expected 0/1, false/true, off/on or no/yes)");
+    return true;
+}
+/**
+ * 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) {
+    const fromEnv = process.env[SIBLING_SETTING]?.trim();
+    if (fromEnv)
+        return parseSiblingSetting(fromEnv, "the environment");
+    const lookup = settingsEnvValue(liveRoot, SIBLING_SETTING);
+    if (lookup.kind === "absent")
+        return true;
+    if (lookup.kind === "invalid") {
+        printError(`checkpoint: ignoring ${SIBLING_SETTING} 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 true;
+    }
+    return parseSiblingSetting(lookup.value, lookup.source);
+}
+/** 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 +964,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 +990,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 +1026,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 +1069,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 = {

package/dist/commands/index-cmd.js

@@ -2,6 +2,7 @@ import { Option } from 'commander';
 import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcileCollections, resolveQmdBin, resolveQmdHome, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
 import { backgroundStatus, defaultBackgroundDependencies, runBackgroundLauncher, runBackgroundWorker, } from '../lib/search-index/background.js';
 import { defaultEmbedLockDependencies, runWithEmbedLock, } from '../lib/search-index/embed-lock.js';
+import { checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from '../lib/search-index/load-gate.js';
 import { applyIndexSizeLimit } from '../lib/search-index/max-doc-bytes.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { QMD_NATIVE_BINDING_REMEDY, isQmdNativeBindingError, } from '../utils/qmd-native-binding-error.js';
@@ -38,10 +39,22 @@ export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
     dependencies.runQmd(['update'], { cwd: hqRoot });
     if (!embed)
         return { embedded: false };
-    const runEmbed = () => dependencies.runQmd(['embed'], { cwd: hqRoot });
     const lockDependencies = dependencies.embedLockDependencies ?? defaultEmbedLockDependencies();
-    const outcome = runWithEmbedLock(resolveQmdHome(lockDependencies.env), lockDependencies, runEmbed);
     const writeStderr = dependencies.writeStderr ?? ((text) => process.stderr.write(text));
+    const home = resolveQmdHome(lockDependencies.env);
+    const loadGateDependencies = dependencies.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
+    const outcome = runWithEmbedLock(home, lockDependencies, () => {
+        const decision = checkEmbedLoad(home, loadGateDependencies);
+        if (decision.action === 'skip') {
+            writeStderr(decision.notice);
+            return 'skipped';
+        }
+        if (decision.forced)
+            writeStderr(decision.notice);
+        dependencies.runQmd(['embed'], { cwd: hqRoot });
+        recordSuccessfulEmbed(home, loadGateDependencies);
+        return undefined;
+    });
     if (outcome === 'busy')
         writeStderr('hq: qmd embed is already running; skipping this pass.\n');
     if (outcome === 'unavailable')

package/dist/commands/reindex.js

@@ -38,6 +38,24 @@ const HOOK_CHECK_RELATIVE_PATH = path.join('core', 'scripts', 'check-hq-hooks.sh
 const WORKTREE_STALE_AFTER_MS = 12 * 60 * 60 * 1_000;
 const WORKTREE_GIT_TIMEOUT_MS = 2_000;
 const WORKTREE_HOOK_SWEEP_BUDGET_MS = 5_000;
+/**
+ * Ceiling for the shipped hook checker. Sized for the SLOWEST legitimate case,
+ * not the fast one: an older core whose checker still runs an unscoped
+ * `hq doctor`, on a loaded host, takes tens of seconds. Undercutting that would
+ * convert a working checker into a permanent timeout. A wedged checker is still
+ * bounded, which is the point.
+ */
+const HOOK_CHECK_TIMEOUT_MS = 60_000;
+/** Ceiling override, in milliseconds. Present so tests need not wait a minute. */
+function hookCheckTimeoutMs() {
+    const raw = process.env.HQ_HOOK_CHECK_TIMEOUT_MS?.trim();
+    if (raw) {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return HOOK_CHECK_TIMEOUT_MS;
+}
 /** Resolve the same root the repair/check commands must operate on. */
 function resolveHqRoot(repoRoot) {
     const root = repoRoot ?? findHqRoot();
@@ -335,16 +353,37 @@ function hasCommandHook(value) {
  * Run the release health checker when it is available. Its diagnostics cover
  * runtime/configuration issues outside the safe repair scope; the JSON check
  * below additionally recognizes UserPromptSubmit, which older checkers omit.
+ *
+ * Bounded, because reindex runs from Stop / PostToolUse lifecycle hooks and the
+ * checker shells into `hq doctor`: an unbounded wait here is an unbounded stall
+ * in front of the agent.
+ *
+ * An overrun is reported as a FAILED check, not as an absent one. Those two
+ * look identical to `spawnSync` (both surface as an error) but mean opposite
+ * things: absent is "this tree ships no checker, nothing more to learn", while
+ * an overrun is "the checker exists and we did not hear back". Collapsing the
+ * second into the first would let the slowest trees — exactly the ones running
+ * an older, unscoped checker — report healthy while the drift only this checker
+ * detects goes unseen.
  */
 function runShippedHookCheck(hqRoot) {
     const checker = path.join(hqRoot, HOOK_CHECK_RELATIVE_PATH);
     if (!fs.existsSync(checker))
         return undefined;
+    const budgetMs = hookCheckTimeoutMs();
     try {
         const result = spawnSync('bash', [checker, '--root', hqRoot], {
             encoding: 'utf8',
             stdio: 'pipe',
+            timeout: budgetMs,
         });
+        if (result.error?.code === 'ETIMEDOUT') {
+            return {
+                status: 1,
+                output: `the shipped ${HOOK_CHECK_RELATIVE_PATH} check did not finish within ` +
+                    `${Math.round(budgetMs / 1000)}s, so hook health could not be determined`,
+            };
+        }
         if (result.error)
             return undefined;
         return {
@@ -356,8 +395,17 @@ function runShippedHookCheck(hqRoot) {
         return undefined;
     }
 }
+/**
+ * Classify the tree's hook configuration, cheapest signal first.
+ *
+ * The shipped checker runs LAST and only when everything else looks healthy.
+ * That ordering is not a micro-optimisation: its result is consulted in exactly
+ * one branch — the final healthy/minor decision — so on a tree that is already
+ * extreme or already minor it is a subprocess whose answer is discarded. Since
+ * reindex fires on every Stop / PostToolUse hook, that was the single most
+ * expensive discarded result in the command.
+ */
 function inspectHookHealth(hqRoot) {
-    const checkerResult = runShippedHookCheck(hqRoot);
     const settingsPath = path.join(hqRoot, '.claude', 'settings.json');
     if (!fs.existsSync(settingsPath)) {
         return { state: 'extreme', reason: '.claude/settings.json is missing' };
@@ -386,6 +434,7 @@ function inspectHookHealth(hqRoot) {
             reason: `missing command hook wiring for ${HOOK_EVENTS.filter((event) => !commandEvents.includes(event)).join(', ')}`,
         };
     }
+    const checkerResult = runShippedHookCheck(hqRoot);
     if (checkerResult !== undefined && checkerResult.status !== 0) {
         return {
             state: 'minor',

package/dist/lib/bot/runtime/messages-stream.js

@@ -23,6 +23,12 @@ export function messagesStreamEvents(line) {
     if (ev.parent_tool_use_id !== null && ev.parent_tool_use_id !== undefined)
         return [];
     const message = ev.message && typeof ev.message === "object" ? ev.message : null;
+    // Claude Code wraps its own notices (a dead login: "Not logged in", "Failed
+    // to authenticate…") in an assistant message from model "<synthetic>". That
+    // is the tool talking, not the model: never post it as progress, so a
+    // sign-in failure is still recognised as one (the result event carries it).
+    if (message?.model === "<synthetic>")
+        return [];
     const content = Array.isArray(message?.content) ? message.content : [];
     const out = [];
     for (const block of content) {

package/dist/lib/core-utils/qmd-reindex-after-sync.d.ts

@@ -1,4 +1,5 @@
 import { type EmbedLockDependencies } from "../search-index/embed-lock.js";
+import { type LoadGateDependencies } from "../search-index/load-gate.js";
 import { type UtilityIo } from "./common.js";
 export type QmdReindexOptions = UtilityIo & {
     cwd?: string;
@@ -14,6 +15,8 @@ export type QmdReindexOptions = UtilityIo & {
     sizeLimit?: (hqRoot: string) => unknown;
     /** 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;
 };
 export declare function qmdReindexAfterSync(args?: string[], options?: QmdReindexOptions): number;
 //# sourceMappingURL=qmd-reindex-after-sync.d.ts.map

package/dist/lib/core-utils/qmd-reindex-after-sync.js

@@ -14,6 +14,7 @@ import * as path from "node:path";
 import { reconcileCollections, resolveQmdBin, resolveQmdHome, runQmd } from "../search-index/index.js";
 import { applyIndexSizeLimit } from "../search-index/max-doc-bytes.js";
 import { defaultEmbedLockDependencies, runWithEmbedLock, } from "../search-index/embed-lock.js";
+import { LoadGateConfigurationError, checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from "../search-index/load-gate.js";
 import { ioFor, line } from "./common.js";
 export function qmdReindexAfterSync(args = [], options = {}) {
     let hqRoot = "";
@@ -66,15 +67,30 @@ export function qmdReindexAfterSync(args = [], options = {}) {
     }
     if (embed) {
         const lockDependencies = options.embedLockDependencies ?? defaultEmbedLockDependencies();
+        const home = resolveQmdHome(lockDependencies.env);
+        const loadGateDependencies = options.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
         try {
-            const outcome = runWithEmbedLock(resolveQmdHome(lockDependencies.env), lockDependencies, () => { run(["embed"], { bin, cwd: hqRoot }); });
+            const outcome = runWithEmbedLock(home, lockDependencies, () => {
+                const decision = checkEmbedLoad(home, loadGateDependencies);
+                if (decision.action === "skip") {
+                    line(stderr, decision.notice.trimEnd());
+                    return "skipped";
+                }
+                if (decision.forced)
+                    line(stderr, decision.notice.trimEnd());
+                run(["embed"], { bin, cwd: hqRoot });
+                recordSuccessfulEmbed(home, loadGateDependencies);
+                return undefined;
+            });
             if (outcome === "busy") {
                 line(stderr, "hq: qmd embed is already running; skipping this pass.");
             }
             if (outcome === "unavailable")
                 line(stderr, "hq: cannot access the qmd embed lock; skipping this pass.");
         }
-        catch {
+        catch (error) {
+            if (error instanceof LoadGateConfigurationError)
+                line(stderr, `hq: ${error.message}`);
             /* embeddings are deferred-cost and optional */
         }
     }

package/dist/lib/doctor/json-output.d.ts

@@ -71,6 +71,14 @@ export interface DoctorJsonDocument {
     summary: StatusCounts;
     /** The exit code this run produced: 0, or 1 when any FAIL/UNKNOWN is present. */
     exitCode: number;
+    /**
+     * The check families this run was restricted to (`--only`), in registration
+     * order. ABSENT on a full run, which is the only reading a consumer may treat
+     * as a verdict on the whole tree: a scoped document reports nothing at all
+     * about the families that never ran, and "no FAILs" in it must not be
+     * mistaken for a healthy tree.
+     */
+    scope?: string[];
     /** The full, flattened result list in family/registration order. */
     results: DoctorJsonResult[];
 }
@@ -82,6 +90,8 @@ export interface BuildDoctorJsonInput {
     families: FamilyRun[];
     /** Detected platform. Defaults to {@link UNKNOWN_PLATFORM}. */
     platform?: DoctorPlatform;
+    /** Families this run was restricted to. Omitted on a full run. */
+    scope?: readonly string[];
 }
 /** Assemble the machine-readable document from a completed run. */
 export declare function buildDoctorJson(input: BuildDoctorJsonInput): DoctorJsonDocument;

package/dist/lib/doctor/json-output.js

@@ -43,6 +43,7 @@ export function buildDoctorJson(input) {
         hqRoot: input.hqRoot,
         summary: summarize(input.families),
         exitCode: computeExitCode(input.families),
+        ...(input.scope && input.scope.length > 0 ? { scope: [...input.scope] } : {}),
         results,
     };
 }

package/dist/lib/doctor/registry.d.ts

@@ -27,6 +27,20 @@ export declare class DoctorRegistry {
     families(): CheckFamily[];
     /** Whether a family with this id is registered. */
     has(id: string): boolean;
+    /** The registered family ids, in registration order. */
+    ids(): string[];
+    /**
+     * A registry holding only the named families, still in REGISTRATION order —
+     * the caller's argument order is a selection, not a reordering, so a scoped
+     * report reads the same way as a full one.
+     *
+     * Unknown ids are returned rather than ignored: running zero checks and
+     * reporting success would describe a tree nothing looked at.
+     */
+    select(ids: readonly string[]): {
+        registry: DoctorRegistry;
+        unknown: string[];
+    };
     /** Run every family in order and collect grouped results. */
     run(context: CheckContext): Promise<FamilyRun[]>;
 }

package/dist/lib/doctor/registry.js

@@ -43,6 +43,28 @@ export class DoctorRegistry {
     has(id) {
         return this.familiesById.has(id);
     }
+    /** The registered family ids, in registration order. */
+    ids() {
+        return [...this.familiesById.keys()];
+    }
+    /**
+     * A registry holding only the named families, still in REGISTRATION order —
+     * the caller's argument order is a selection, not a reordering, so a scoped
+     * report reads the same way as a full one.
+     *
+     * Unknown ids are returned rather than ignored: running zero checks and
+     * reporting success would describe a tree nothing looked at.
+     */
+    select(ids) {
+        const wanted = new Set(ids);
+        const unknown = [...wanted].filter((id) => !this.familiesById.has(id));
+        const registry = new DoctorRegistry();
+        for (const family of this.families()) {
+            if (wanted.has(family.id))
+                registry.register(family);
+        }
+        return { registry, unknown };
+    }
     /** Run every family in order and collect grouped results. */
     async run(context) {
         const runs = [];

package/dist/lib/search-index/background.d.ts

@@ -1,7 +1,8 @@
 import { type StdioOptions } from 'node:child_process';
 import { type QmdProcessResult, type RunQmdOptions } from './index.js';
+import { type LoadGateDependencies } from './load-gate.js';
 export type BackgroundResult = {
-    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed' | 'terminated';
+    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'deferred' | 'completed' | 'update-failed' | 'terminated';
 } | {
     state: 'launched';
     pid: number;
@@ -27,6 +28,9 @@ export type BackgroundDependencies = {
     /** Test seams for signal delivery; production uses the real process. */
     processEvents?: Pick<NodeJS.Process, 'once'>;
     exit?: (code: number) => void;
+    /** Test seams for the host load gate consulted immediately before qmd embed. */
+    loadGateDependencies?: LoadGateDependencies;
+    writeStderr?: (text: string) => void;
 };
 export type BackgroundStatus = {
     lock: 'held' | 'stale' | 'free';

package/dist/lib/search-index/background.js

@@ -5,6 +5,7 @@ import { Sentry } from '../../sentry.js';
 import { reconcileCollections as defaultReconcileCollections, resolveQmdBin as defaultResolveQmdBin, runQmd as defaultRunQmd, } from './index.js';
 import { applyIndexSizeLimit as defaultApplyIndexSizeLimit } from './max-doc-bytes.js';
 import { acquireEmbedLock as acquireLock, installEmbedLockCleanup, lockPath, lockRoot, lockState, releaseEmbedLock as releaseLock, } from './embed-lock.js';
+import { LoadGateConfigurationError, checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from './load-gate.js';
 const COMPLETE_NAME = 'qmd-reindex-bg.completed';
 function errnoInfo(error) {
     const e = error;
@@ -123,6 +124,7 @@ export function defaultBackgroundDependencies(hqRoot) {
         applyIndexSizeLimit: defaultApplyIndexSizeLimit,
         runQmd: defaultRunQmd,
         spawnWorker: defaultSpawnWorker,
+        writeStderr: (text) => process.stderr.write(text),
     };
 }
 /** Match the shell forwarder's hosted-agent markers before looking up qmd. */
@@ -350,8 +352,30 @@ export async function runBackgroundWorker(dependencies) {
         }
         if (await signalWindow())
             return { state: 'terminated' };
+        const loadGateDependencies = dependencies.loadGateDependencies ?? defaultLoadGateDependencies(dependencies.env);
+        let loadDecision;
+        try {
+            loadDecision = checkEmbedLoad(home, loadGateDependencies);
+        }
+        catch (error) {
+            if (error instanceof LoadGateConfigurationError) {
+                (dependencies.writeStderr ?? ((text) => process.stderr.write(text)))(`hq: ${error.message}\n`);
+                cleanup();
+                return { state: 'deferred' };
+            }
+            throw error;
+        }
+        if (loadDecision.action === 'skip') {
+            (dependencies.writeStderr ?? ((text) => process.stderr.write(text)))(loadDecision.notice);
+            writeCompletion(home, dependencies);
+            cleanup();
+            return { state: 'deferred' };
+        }
+        if (loadDecision.forced)
+            (dependencies.writeStderr ?? ((text) => process.stderr.write(text)))(loadDecision.notice);
         try {
             appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot })));
+            recordSuccessfulEmbed(home, loadGateDependencies);
         }
         catch (error) {
             appendWorkerLog(logPath, errorOutput(error)); // a completed embed attempt still permits the stamp

package/dist/lib/search-index/embed-lock.d.ts

@@ -10,7 +10,7 @@ export type EmbedLockDependencies = {
 export type EmbedLockProcessEvents = Pick<NodeJS.Process, 'once'> & {
     removeListener?: NodeJS.Process['removeListener'];
 };
-export type EmbedLockRunResult = 'ran' | 'busy' | 'unavailable';
+export type EmbedLockRunResult = 'ran' | 'skipped' | 'busy' | 'unavailable';
 /**
  * Serializes embeddings started through hq-cli only. A bare `qmd embed` (or
  * another tool that does not call this module) cannot participate, because qmd
@@ -34,5 +34,5 @@ export declare function installEmbedLockCleanup(cleanup: () => void, processEven
  * termination. An interrupted owner is safely reclaimed through the lock's
  * existing staleness and owner-grace protocol.
  */
-export declare function runWithEmbedLock(home: string, dependencies: EmbedLockDependencies, run: () => void): EmbedLockRunResult;
+export declare function runWithEmbedLock(home: string, dependencies: EmbedLockDependencies, run: () => 'skipped' | void): EmbedLockRunResult;
 //# sourceMappingURL=embed-lock.d.ts.map

package/dist/lib/search-index/embed-lock.js

@@ -276,8 +276,7 @@ export function runWithEmbedLock(home, dependencies, run) {
     if (acquired === 'busy')
         return 'busy';
     try {
-        run();
-        return 'ran';
+        return run() === 'skipped' ? 'skipped' : 'ran';
     }
     finally {
         releaseEmbedLock(home, dependencies);

package/dist/lib/search-index/load-gate.d.ts

@@ -0,0 +1,65 @@
+import * as os from 'node:os';
+export declare const DEFAULT_MAX_LOAD_PERCENT = 50;
+/**
+ * Twelve requests is enough to avoid quietly starving a frequently requested
+ * index, while still leaving several opportunities for a busy machine to cool
+ * down before we spend CPU on an embed. The thirteenth request is forced.
+ */
+export declare const MAX_CONSECUTIVE_DEFERRED_EMBEDS = 12;
+/** Six hours bounds deferral even when indexing requests are infrequent. */
+export declare const MAX_EMBED_DEFERRAL_SECONDS: number;
+export type LoadGateDependencies = {
+    env: NodeJS.ProcessEnv;
+    now: () => number;
+    readFile: (file: string) => string;
+    writeFile: (file: string, contents: string) => void;
+    rename: (source: string, destination: string) => void;
+    mkdir: (directory: string) => void;
+    /** A synchronous seam so the existing synchronous qmd entry points stay synchronous. */
+    sleep: (milliseconds: number) => void;
+    cpus: () => os.CpuInfo[];
+    /** Only used outside Linux, where /proc/meminfo is unavailable. */
+    freemem: () => number;
+    totalmem: () => number;
+};
+type CpuCounters = {
+    total: number;
+    idle: number;
+};
+export type EmbedLoadDecision = {
+    action: 'embed';
+    forced: false;
+} | {
+    action: 'embed';
+    forced: true;
+    notice: string;
+} | {
+    action: 'skip';
+    signal: 'cpu' | 'memory';
+    percent: number;
+    limit: number;
+    notice: string;
+};
+export declare class LoadGateConfigurationError extends Error {
+    constructor(value: string);
+}
+export declare function defaultLoadGateDependencies(env?: NodeJS.ProcessEnv): LoadGateDependencies;
+export declare function parseProcStatAggregate(contents: string): CpuCounters | undefined;
+export declare function cpuBusyPercent(before: CpuCounters, after: CpuCounters): number | undefined;
+/** Sample aggregate CPU busy time over 200 ms, falling back only without /proc/stat. */
+export declare function measureCpuPercent(dependencies: LoadGateDependencies): number;
+export declare function memAvailableFraction(contents: string): number | undefined;
+/** Prefer Linux MemAvailable, because MemFree alone treats reclaimable cache as used memory. */
+export declare function measureMemoryPercent(dependencies: LoadGateDependencies): number;
+export declare function parseLoadThreshold(env: NodeJS.ProcessEnv): number | undefined;
+export declare function loadGateStatePath(home: string): string;
+/**
+ * Decide immediately before qmd embed whether this host can absorb it. The
+ * caller must already own the shared embed lock, so state updates are atomic
+ * with respect to hq-cli's other embed entry points.
+ */
+export declare function checkEmbedLoad(home: string, dependencies: LoadGateDependencies): EmbedLoadDecision;
+/** Reset the starvation counter only after qmd embed has actually returned successfully. */
+export declare function recordSuccessfulEmbed(home: string, dependencies: LoadGateDependencies): void;
+export {};
+//# sourceMappingURL=load-gate.d.ts.map

package/dist/lib/search-index/load-gate.js

@@ -0,0 +1,270 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { lockRoot } from './embed-lock.js';
+export const DEFAULT_MAX_LOAD_PERCENT = 50;
+/**
+ * Twelve requests is enough to avoid quietly starving a frequently requested
+ * index, while still leaving several opportunities for a busy machine to cool
+ * down before we spend CPU on an embed. The thirteenth request is forced.
+ */
+export const MAX_CONSECUTIVE_DEFERRED_EMBEDS = 12;
+/** Six hours bounds deferral even when indexing requests are infrequent. */
+export const MAX_EMBED_DEFERRAL_SECONDS = 6 * 60 * 60;
+const LOAD_GATE_STATE_NAME = 'qmd-embed-load-state';
+const PROC_STAT = '/proc/stat';
+const PROC_MEMINFO = '/proc/meminfo';
+export class LoadGateConfigurationError extends Error {
+    constructor(value) {
+        super(`HQ_INDEX_MAX_LOAD_PERCENT must be an integer from 1 to 100, 0, or off; received ${JSON.stringify(value)}.`);
+        this.name = 'LoadGateConfigurationError';
+    }
+}
+function synchronousSleep(milliseconds) {
+    const slot = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(slot, 0, 0, milliseconds);
+}
+export function defaultLoadGateDependencies(env = process.env) {
+    return {
+        env,
+        now: () => Math.floor(Date.now() / 1_000),
+        readFile: (file) => fs.readFileSync(file, 'utf8'),
+        writeFile: (file, contents) => fs.writeFileSync(file, contents),
+        rename: (source, destination) => fs.renameSync(source, destination),
+        mkdir: (directory) => fs.mkdirSync(directory, { recursive: true }),
+        sleep: synchronousSleep,
+        cpus: () => os.cpus(),
+        // os.freemem() reports MemFree on Linux, which excludes reclaimable cache.
+        // Use it only where /proc/meminfo does not exist.
+        freemem: () => os.freemem(),
+        totalmem: () => os.totalmem(),
+    };
+}
+function errorCode(error) {
+    return error?.code;
+}
+function missing(error) {
+    return errorCode(error) === 'ENOENT';
+}
+export function parseProcStatAggregate(contents) {
+    const line = contents.split('\n').find((candidate) => /^cpu\s+/.test(candidate));
+    if (!line)
+        return undefined;
+    const values = line.trim().split(/\s+/).slice(1).map(Number);
+    if (values.length < 5 || values.some((value) => !Number.isFinite(value) || value < 0))
+        return undefined;
+    // Linux reports guest and guest_nice inside user and nice respectively.
+    const total = values.slice(0, 8).reduce((sum, value) => sum + value, 0);
+    const idle = values[3] + values[4];
+    return total > 0 && Number.isFinite(idle) ? { total, idle } : undefined;
+}
+export function cpuBusyPercent(before, after) {
+    const totalDelta = after.total - before.total;
+    const idleDelta = after.idle - before.idle;
+    if (totalDelta <= 0 || idleDelta < 0)
+        return undefined;
+    return Math.max(0, Math.min(100, (1 - idleDelta / totalDelta) * 100));
+}
+function cpuCountersFromCpus(cpus) {
+    let total = 0;
+    let idle = 0;
+    if (cpus.length === 0)
+        return undefined;
+    for (const cpu of cpus) {
+        const { user, nice, sys, idle: cpuIdle, irq } = cpu.times;
+        const values = [user, nice, sys, cpuIdle, irq];
+        if (values.some((value) => !Number.isFinite(value) || value < 0))
+            return undefined;
+        total += values.reduce((sum, value) => sum + value, 0);
+        idle += cpuIdle;
+    }
+    return total > 0 ? { total, idle } : undefined;
+}
+function fallbackCpuPercent(dependencies) {
+    const before = cpuCountersFromCpus(dependencies.cpus());
+    dependencies.sleep(200);
+    const after = cpuCountersFromCpus(dependencies.cpus());
+    const busy = before && after ? cpuBusyPercent(before, after) : undefined;
+    if (busy === undefined)
+        throw new Error('Cannot determine CPU busy time from os.cpus().');
+    return busy;
+}
+/** Sample aggregate CPU busy time over 200 ms, falling back only without /proc/stat. */
+export function measureCpuPercent(dependencies) {
+    let first;
+    try {
+        first = dependencies.readFile(PROC_STAT);
+    }
+    catch (error) {
+        if (missing(error))
+            return fallbackCpuPercent(dependencies);
+        throw error;
+    }
+    dependencies.sleep(200);
+    let second;
+    try {
+        second = dependencies.readFile(PROC_STAT);
+    }
+    catch (error) {
+        if (missing(error))
+            return fallbackCpuPercent(dependencies);
+        throw error;
+    }
+    const before = parseProcStatAggregate(first);
+    const after = parseProcStatAggregate(second);
+    const busy = before && after ? cpuBusyPercent(before, after) : undefined;
+    if (busy === undefined)
+        throw new Error('Cannot determine CPU busy time from /proc/stat.');
+    return busy;
+}
+export function memAvailableFraction(contents) {
+    const fields = new Map();
+    for (const line of contents.split('\n')) {
+        const match = /^(MemTotal|MemAvailable):\s+(\d+)\s+kB$/.exec(line.trim());
+        if (match)
+            fields.set(match[1], Number(match[2]));
+    }
+    const total = fields.get('MemTotal');
+    const available = fields.get('MemAvailable');
+    if (total === undefined || available === undefined || total <= 0 || available < 0 || available > total)
+        return undefined;
+    return 1 - available / total;
+}
+/** Prefer Linux MemAvailable, because MemFree alone treats reclaimable cache as used memory. */
+export function measureMemoryPercent(dependencies) {
+    try {
+        const fraction = memAvailableFraction(dependencies.readFile(PROC_MEMINFO));
+        if (fraction === undefined)
+            throw new Error('Cannot determine memory use from /proc/meminfo.');
+        return fraction * 100;
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+    }
+    const total = dependencies.totalmem();
+    const free = dependencies.freemem();
+    if (total <= 0 || free < 0 || free > total)
+        throw new Error('Cannot determine memory use.');
+    return (1 - free / total) * 100;
+}
+export function parseLoadThreshold(env) {
+    const value = env.HQ_INDEX_MAX_LOAD_PERCENT?.trim() || String(DEFAULT_MAX_LOAD_PERCENT);
+    if (value === '0' || value.toLowerCase() === 'off')
+        return undefined;
+    if (!/^[1-9]\d{0,2}$/.test(value) || Number(value) > 100)
+        throw new LoadGateConfigurationError(value);
+    return Number(value);
+}
+export function loadGateStatePath(home) {
+    return path.join(lockRoot(home), LOAD_GATE_STATE_NAME);
+}
+function readFields(file, dependencies) {
+    try {
+        const fields = {};
+        for (const line of dependencies.readFile(file).split('\n')) {
+            if (line === '')
+                continue;
+            const index = line.indexOf('=');
+            const key = line.slice(0, index);
+            if (index < 1 || !['skips', 'firstDeferredAt', 'lastSuccessfulEmbedAt'].includes(key) || fields[key] !== undefined)
+                return undefined;
+            fields[key] = line.slice(index + 1);
+        }
+        return fields;
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw error;
+    }
+}
+function nonnegativeInteger(value) {
+    return value !== undefined && /^\d+$/.test(value) ? Number(value) : undefined;
+}
+function readState(home, dependencies) {
+    const fields = readFields(loadGateStatePath(home), dependencies);
+    if (!fields)
+        return { skips: 0 };
+    const skips = nonnegativeInteger(fields.skips);
+    const firstDeferredAt = nonnegativeInteger(fields.firstDeferredAt);
+    const lastSuccessfulEmbedAt = nonnegativeInteger(fields.lastSuccessfulEmbedAt);
+    if (skips === undefined
+        || (fields.firstDeferredAt !== undefined && firstDeferredAt === undefined)
+        || (fields.lastSuccessfulEmbedAt !== undefined && lastSuccessfulEmbedAt === undefined)
+        || (skips > 0 && firstDeferredAt === undefined)
+        || (skips === 0 && firstDeferredAt !== undefined))
+        return { skips: 0 };
+    return {
+        skips,
+        ...(firstDeferredAt === undefined ? {} : { firstDeferredAt }),
+        ...(lastSuccessfulEmbedAt === undefined ? {} : { lastSuccessfulEmbedAt }),
+    };
+}
+function writeState(home, state, dependencies) {
+    dependencies.mkdir(lockRoot(home));
+    const statePath = loadGateStatePath(home);
+    const temporaryPath = `${statePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    dependencies.writeFile(temporaryPath, [
+        `skips=${state.skips}`,
+        ...(state.firstDeferredAt === undefined ? [] : [`firstDeferredAt=${state.firstDeferredAt}`]),
+        ...(state.lastSuccessfulEmbedAt === undefined ? [] : [`lastSuccessfulEmbedAt=${state.lastSuccessfulEmbedAt}`]),
+        '',
+    ].join('\n'));
+    dependencies.rename(temporaryPath, statePath);
+}
+function rounded(percent) {
+    return Math.round(percent);
+}
+function trippedSignal(cpuPercent, memoryPercent, limit) {
+    if (cpuPercent >= limit)
+        return { signal: 'cpu', percent: rounded(cpuPercent) };
+    if (memoryPercent >= limit)
+        return { signal: 'memory', percent: rounded(memoryPercent) };
+    return undefined;
+}
+/**
+ * Decide immediately before qmd embed whether this host can absorb it. The
+ * caller must already own the shared embed lock, so state updates are atomic
+ * with respect to hq-cli's other embed entry points.
+ */
+export function checkEmbedLoad(home, dependencies) {
+    const limit = parseLoadThreshold(dependencies.env);
+    if (limit === undefined)
+        return { action: 'embed', forced: false };
+    const cpuPercent = measureCpuPercent(dependencies);
+    const memoryPercent = measureMemoryPercent(dependencies);
+    const tripped = trippedSignal(cpuPercent, memoryPercent, limit);
+    if (!tripped)
+        return { action: 'embed', forced: false };
+    const now = dependencies.now();
+    const state = readState(home, dependencies);
+    const skips = state.skips + 1;
+    const deferredSince = state.firstDeferredAt ?? now;
+    const exceededSkipBound = skips > MAX_CONSECUTIVE_DEFERRED_EMBEDS;
+    const exceededTimeBound = now - deferredSince >= MAX_EMBED_DEFERRAL_SECONDS;
+    if (exceededSkipBound || exceededTimeBound) {
+        return {
+            action: 'embed',
+            forced: true,
+            notice: `hq: proceeding with qmd embed despite ${tripped.signal} ${tripped.percent}% (limit ${limit}%) because embeddings have been deferred too long.\n`,
+        };
+    }
+    writeState(home, {
+        skips,
+        firstDeferredAt: state.firstDeferredAt ?? now,
+        ...(state.lastSuccessfulEmbedAt === undefined ? {} : { lastSuccessfulEmbedAt: state.lastSuccessfulEmbedAt }),
+    }, dependencies);
+    return {
+        action: 'skip',
+        signal: tripped.signal,
+        percent: tripped.percent,
+        limit,
+        notice: `hq: skipping qmd embed — ${tripped.signal} ${tripped.percent}% (limit ${limit}%).\n`,
+    };
+}
+/** Reset the starvation counter only after qmd embed has actually returned successfully. */
+export function recordSuccessfulEmbed(home, dependencies) {
+    writeState(home, { skips: 0, lastSuccessfulEmbedAt: dependencies.now() }, dependencies);
+}
+//# sourceMappingURL=load-gate.js.map

package/dist/lib/workers-registry/index.js

@@ -18,10 +18,26 @@ function isFile(target) {
         return false;
     }
 }
-/** A sorted `find -L … -name worker.yaml -type f` equivalent, including symlinked pack workers. */
+/**
+ * A sorted `find -L … -name worker.yaml -type f` equivalent, including
+ * symlinked pack workers.
+ *
+ * Excluded subtrees are pruned at the descent, not filtered from the result.
+ * That distinction is the whole cost of this scan: a tenant's `repos/` holds
+ * source checkouts, so filtering afterwards means reading every `node_modules`
+ * and `.git` directory inside them — tens of thousands of directories on a real
+ * root — to produce matches that are discarded a moment later.
+ *
+ * Directory entries carry their own type, so the common case costs one
+ * `readdir` per directory instead of an extra `stat` per entry. Symlinks are
+ * the exception: their dirent type describes the link, so resolving one still
+ * needs a `stat`, which is what keeps this faithful to `find -L`.
+ */
 function workerYamlFiles(root, relativeRoot) {
     const output = [];
     const walk = (relative, ancestors) => {
+        if (isExcludedWorkerDirectory(relative))
+            return;
         const absolute = path.join(root, relative);
         if (!isDirectory(absolute))
             return;
@@ -35,20 +51,23 @@ function workerYamlFiles(root, relativeRoot) {
         if (ancestors.has(physical))
             return; // `find -L` reports loops; a bounded walk is safer here.
         const nextAncestors = new Set(ancestors).add(physical);
-        let names;
+        let entries;
         try {
-            names = fs.readdirSync(absolute).sort();
+            entries = fs.readdirSync(absolute, { withFileTypes: true });
         }
         catch {
             return;
         }
-        for (const name of names) {
-            const childRelative = path.join(relative, name);
+        entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+        for (const entry of entries) {
+            const childRelative = path.join(relative, entry.name);
             const child = path.join(root, childRelative);
-            if (name === 'worker.yaml' && isFile(child))
+            if (entry.name === 'worker.yaml' && (entry.isFile() || isFile(child))) {
                 output.push(childRelative);
-            else if (isDirectory(child))
+            }
+            else if (entry.isDirectory() || (entry.isSymbolicLink() && isDirectory(child))) {
                 walk(childRelative, nextAncestors);
+            }
         }
     };
     walk(relativeRoot, new Set());
@@ -139,8 +158,8 @@ function withoutTimestamp(content) {
  * both `core` and `personal` — the checkout wins. The operator's actual worker
  * then silently vanishes from the registry every skill reads.
  */
-function isExcludedWorkerPath(relativeFile) {
-    const normalized = relativeFile.replaceAll('\\', '/');
+function isExcludedWorkerDirectory(relativeDirectory) {
+    const normalized = relativeDirectory.replaceAll('\\', '/');
     const [root, tenant, nested] = normalized.split('/');
     if (root !== 'companies')
         return /(?:^|\/)_overrides(?:\/|$)/.test(normalized);
@@ -150,6 +169,15 @@ function isExcludedWorkerPath(relativeFile) {
         return true;
     return /(?:^|\/)_overrides(?:\/|$)/.test(normalized);
 }
+/**
+ * Every exclusion is a property of the directory holding the `worker.yaml`, so
+ * the file rule is the directory rule applied to its parent. Deriving it keeps
+ * the pruned descent and this final filter from ever disagreeing — a drift that
+ * would either resurrect a shadowing copy or silently drop a real worker.
+ */
+function isExcludedWorkerPath(relativeFile) {
+    return isExcludedWorkerDirectory(path.dirname(relativeFile));
+}
 /**
  * Generate core/workers/registry.yaml from worker.yaml files. Invalid workers
  * are quarantined but do not prevent all valid workers from being registered.

package/package.json

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