@indigoai-us/hq-cli 5.115.3 → 5.115.5

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