@indigoai-us/hq-cli 5.345.90 → 5.345.92

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.345.92] — 2026-10-12
+- The background search-index worker no longer spins at full CPU when its working directory is deleted: it only writes to absolute log paths, rejects a `C:/...` log path on macOS and Linux, receives the launcher's HQ root, and kills any qmd cleanup, update, or embed step that runs past 2 hours (`QMD_REINDEX_STEP_TIMEOUT_SEC` overrides). The bundled `qmd-reindex-bg.sh` converts paths with `cygpath` only on Git Bash, MSYS2, or Cygwin.
+
+## [5.345.91] — 2026-10-12
+- Add published E2E checks comparing native commands with bundled shell scripts for qmd background reindex, hq-session, checkpoint stop gate, and worker skill commands.
+
+- `hq integrations connect <app> --auth key` (and `--token-stdin`) now
+  sends the access key to the app's MCP endpoint. Catalog Slack used to
+  ignore the key and only `--mcp-url` connected. If the server says the
+  app needs a key and cannot sign HQ in automatically, the command
+  collects the key instead of stopping.
+
 ## [5.345.90] — 2026-10-12
 - The setup bot that ships with hq-cli (used before an HQ has synced its core workers) now reads the HQ desktop app's first-run handoff, the same as hq-core's copy. It treats the one note the app sends when its visual setup closes as its kickoff, never offers or repeats an import the app already did, and never runs a second scan. It also no longer asks what the person already said: told "I run an independent software engineering company", it sets up for a software services firm instead of asking "for clients, or your own product?".
 

package/assets/scaffold/core/scripts/qmd-reindex-bg.sh

@@ -37,15 +37,28 @@ if ! command -v hq >/dev/null 2>&1; then
   exit 127
 fi
 
-if command -v cygpath >/dev/null 2>&1; then
-  HQ_ROOT="$(cygpath -m "$HQ_ROOT")"
+# Convert paths to Windows-native form ONLY on a Windows Bash (Git Bash, MSYS2,
+# Cygwin). A `cygpath` merely being on PATH is not evidence of Windows: a test
+# that stubs it on macOS turned `--log /tmp/qmd-handoff.log` into the RELATIVE
+# POSIX path `C:/tmp/qmd-handoff.log`, and the detached worker that inherited
+# it spun at 100% CPU for days once its temp cwd was deleted.
+convert_windows_paths=0
+case "${OSTYPE:-}" in
+  msys* | cygwin*) convert_windows_paths=1 ;;
+esac
+case "$(uname -s 2>/dev/null || true)" in
+  MINGW* | MSYS* | CYGWIN*) convert_windows_paths=1 ;;
+esac
+if [ "$convert_windows_paths" -eq 1 ] && ! command -v cygpath >/dev/null 2>&1; then
+  convert_windows_paths=0
 fi
-if command -v cygpath >/dev/null 2>&1; then
+
+if [ "$convert_windows_paths" -eq 1 ]; then
   HQ_ROOT="$(cygpath -m "$HQ_ROOT")"
 fi
 forwarded_args=("$@")
 forwarded_arg_count=$#
-if command -v cygpath >/dev/null 2>&1; then
+if [ "$convert_windows_paths" -eq 1 ]; then
   for ((index = 0; index < forwarded_arg_count; index++)); do
     case "${forwarded_args[index]}" in
       --log) index=$((index + 1)); if ((index < forwarded_arg_count)); then forwarded_args[index]="$(cygpath -m "${forwarded_args[index]}")"; fi ;;

package/dist/commands/integrations-connect.d.ts

@@ -15,6 +15,12 @@
  * install and treats hq-pro's `INTEGRATION_FACTORY_OAUTH_REQUIRED` as the
  * signal to switch into the browser flow. That way a catalog row that says
  * "key" but is really OAuth-protected still connects on the first try.
+ *
+ * A pasted key is different. Catalog/domain installs can drop `--auth key` /
+ * `--token-stdin` (hq-pro only forwards a bearer token on the direct MCP URL
+ * path, and an OAuth catalog row short-circuits to sign-in). When the caller
+ * supplied a key, or the server says the endpoint needs one and cannot
+ * register HQ, retry against the inspected MCP URL with the key.
  */
 import { Command } from "commander";
 import { type ResidentCommandLeaseOptions } from "../utils/resident-package-preload.js";

package/dist/commands/integrations-connect.js

@@ -15,6 +15,12 @@
  * install and treats hq-pro's `INTEGRATION_FACTORY_OAUTH_REQUIRED` as the
  * signal to switch into the browser flow. That way a catalog row that says
  * "key" but is really OAuth-protected still connects on the first try.
+ *
+ * A pasted key is different. Catalog/domain installs can drop `--auth key` /
+ * `--token-stdin` (hq-pro only forwards a bearer token on the direct MCP URL
+ * path, and an OAuth catalog row short-circuits to sign-in). When the caller
+ * supplied a key, or the server says the endpoint needs one and cannot
+ * register HQ, retry against the inspected MCP URL with the key.
  */
 import chalk from "chalk";
 import open from "open";
@@ -30,6 +36,8 @@ import { completeOAuth, discoverDocs, installIntegration, listCatalog, pullBluep
 import { OAUTH_LOOPBACK_TIMEOUT_CODE, startLoopbackListener, } from "./integrations-oauth.js";
 /** hq-pro's machine code for "this endpoint needs a browser sign-in". */
 const OAUTH_REQUIRED_CODE = "INTEGRATION_FACTORY_OAUTH_REQUIRED";
+/** hq-pro's machine code for "this MCP endpoint refused the auth we sent". */
+const DIRECT_MCP_AUTH_REJECTED_CODE = "DIRECT_MCP_AUTH_REJECTED";
 function warnBrowserOpenFailure(error) {
     console.warn("[hq-cli:integrations-connect] browser open failed", safeCaughtError(error));
 }
@@ -51,6 +59,17 @@ function isOAuthRequiredError(err) {
     return (err instanceof IntegrationsCliError &&
         (err.code === OAUTH_REQUIRED_CODE || err.oauthProtected === true));
 }
+/**
+ * The server probed the MCP endpoint, got an OAuth challenge, and determined
+ * it cannot self-register HQ (no DCR). The recovery is a pasted access key,
+ * not a browser sign-in. `oauthProtected: true` is the opposite signal and
+ * must keep taking the sign-in branch.
+ */
+function isAccessKeyRequiredError(err) {
+    return (err instanceof IntegrationsCliError &&
+        err.code === DIRECT_MCP_AUTH_REJECTED_CODE &&
+        err.oauthProtected !== true);
+}
 /**
  * hq-pro will not take our loopback callback, for either of the two reasons it
  * can refuse one:
@@ -894,6 +913,59 @@ async function completeCredentialIfNeeded(token, companyUid, target, opts, resul
         bearerToken,
     });
 }
+function mcpUrlFromBlueprint(blueprint) {
+    const surfaces = [
+        ...(blueprint.recommendedSurface ? [blueprint.recommendedSurface] : []),
+        ...blueprint.surfaces,
+    ];
+    for (const surface of surfaces) {
+        const url = surface.url?.trim();
+        if (url && /^https:\/\//i.test(url))
+            return url;
+    }
+    return undefined;
+}
+/**
+ * Catalog/domain/query installs are the path that drops a pasted key. The
+ * working connect is the same one `--mcp-url` already uses: a direct MCP
+ * endpoint plus `authMode: bearer`.
+ */
+async function targetForAccessKeyConnect(token, companyUid, target, opts) {
+    if (target.ref.mcpUrl)
+        return { ...target, authClass: "key" };
+    const blueprint = await pullBlueprint(token, companyUid, {
+        ...(target.ref.domain ? { domain: target.ref.domain } : {}),
+        ...(target.ref.query ? { query: target.ref.query } : {}),
+        ...(target.ref.catalogEntryId ? { catalogEntryId: target.ref.catalogEntryId } : {}),
+    });
+    const mcpUrl = mcpUrlFromBlueprint(blueprint);
+    if (!mcpUrl) {
+        throw new IntegrationsCliError(`${target.label} needs an access key. Re-run with --mcp-url <endpoint> --auth key --token-stdin.`, { expected: true });
+    }
+    return {
+        ref: {
+            mcpUrl,
+            ...(opts.provider ? { provider: opts.provider } : blueprint.provider ? { provider: blueprint.provider } : {}),
+            ...(opts.displayName
+                ? { displayName: opts.displayName }
+                : blueprint.displayName
+                    ? { displayName: blueprint.displayName }
+                    : {}),
+        },
+        authClass: "key",
+        label: target.label,
+    };
+}
+function bearerInstallInput(target, opts, bearerToken) {
+    return {
+        ...target.ref,
+        authMode: "bearer",
+        bearerToken,
+        ...(opts.authHeader
+            ? { authScheme: { placement: "header", header: opts.authHeader } }
+            : {}),
+    };
+}
 /** Print the outcome of a successful connect. */
 function reportInstall(result, opts, expectedRevivedConnectionId) {
     if (opts.json) {
@@ -923,17 +995,34 @@ async function connectApp(token, companyUid, app, opts, expectedRevivedConnectio
         : opts.auth ?? target.authClass;
     assertUserClientApplicable(opts, target, authMode);
     assertScopesApplicable(opts, target, authMode);
-    if (authMode === "oauth") {
-        const result = await connectViaOAuth(token, companyUid, target, opts);
-        if (result)
-            reportInstall(result, opts, expectedRevivedConnectionId);
-        return;
-    }
     // A key is only collected when something already says one is needed, or
     // the caller supplied one — otherwise a no-auth app would pointlessly
-    // prompt.
+    // prompt. Compute this BEFORE the OAuth branch: a catalog row marked
+    // oauth plus `--token-stdin` used to skip the key entirely.
     const wantsKey = authMode === "key" || Boolean(opts.token || opts.tokenStdin);
+    const finishWithAccessKey = async (existingKey) => {
+        const keyTarget = await targetForAccessKeyConnect(token, companyUid, target, opts);
+        const bearerToken = existingKey ?? (await resolveKey(opts, keyTarget.label));
+        const result = await installIntegration(token, companyUid, bearerInstallInput(keyTarget, opts, bearerToken));
+        reportInstall(await completeCredentialIfNeeded(token, companyUid, keyTarget, opts, result), opts, expectedRevivedConnectionId);
+    };
+    if (authMode === "oauth" && !wantsKey) {
+        try {
+            const result = await connectViaOAuth(token, companyUid, target, opts);
+            if (result)
+                reportInstall(result, opts, expectedRevivedConnectionId);
+        }
+        catch (err) {
+            if (isAccessKeyRequiredError(err)) {
+                await finishWithAccessKey();
+                return;
+            }
+            throw err;
+        }
+        return;
+    }
     const bearerToken = wantsKey ? await resolveKey(opts, target.label) : undefined;
+    const alreadyDirectKeyInstall = Boolean(target.ref.mcpUrl && bearerToken);
     try {
         const result = await installIntegration(token, companyUid, {
             ...target.ref,
@@ -952,13 +1041,28 @@ async function connectApp(token, companyUid, app, opts, expectedRevivedConnectio
         reportInstall(await completeCredentialIfNeeded(token, companyUid, target, opts, result), opts, expectedRevivedConnectionId);
     }
     catch (err) {
+        const retryAsKey = !alreadyDirectKeyInstall &&
+            (isAccessKeyRequiredError(err) || (isOAuthRequiredError(err) && wantsKey));
+        if (retryAsKey) {
+            await finishWithAccessKey(bearerToken);
+            return;
+        }
         // Server-authoritative detection: the endpoint turned out to be
         // OAuth-protected, so run the browser flow instead of making the
         // caller re-issue the command with --auth oauth.
         if (isOAuthRequiredError(err)) {
-            const result = await connectViaOAuth(token, companyUid, target, opts);
-            if (result)
-                reportInstall(result, opts, expectedRevivedConnectionId);
+            try {
+                const result = await connectViaOAuth(token, companyUid, target, opts);
+                if (result)
+                    reportInstall(result, opts, expectedRevivedConnectionId);
+            }
+            catch (oauthErr) {
+                if (isAccessKeyRequiredError(oauthErr)) {
+                    await finishWithAccessKey(bearerToken);
+                    return;
+                }
+                throw oauthErr;
+            }
             return;
         }
         throw err;

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

@@ -19,10 +19,10 @@ export type BackgroundDependencies = {
     /** Apply the per-document size cap to qmd's config before the update reads anything. */
     applyIndexSizeLimit: (hqRoot: string) => unknown;
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
-    spawnWorker: (options: {
-        logPath: string;
-        fallbackLogPath?: string;
-    }) => number;
+    spawnWorker: (options: SpawnWorkerOptions) => number;
+    /** Test seams for log-path resolution; production uses the real process. */
+    platform?: NodeJS.Platform;
+    cwd?: () => string;
     /** Test seam for simulating a competing owner replacing the atomic record. */
     afterOwnerPublish?: (ownerFile: string) => void;
     /** Test seams for signal delivery; production uses the real process. */
@@ -36,6 +36,32 @@ export type BackgroundStatus = {
     lock: 'held' | 'stale' | 'free';
     completedAt?: number;
 };
+export type SpawnWorkerOptions = {
+    logPath: string;
+    fallbackLogPath?: string;
+    /** Absolute HQ root the worker must index; forwarded as --hq-root. */
+    hqRoot?: string;
+};
+/**
+ * Turn a requested worker log path (or HQ root) into an absolute native path,
+ * or undefined when it cannot be used safely.
+ *
+ * - On a non-Windows host a drive-letter path (`C:/tmp/qmd-handoff.log`) is the
+ *   residue of a Windows-only `cygpath -m` conversion applied where it does not
+ *   belong. POSIX treats it as RELATIVE, so honouring it would create a `C:`
+ *   directory inside whatever the current directory happens to be. Reject it.
+ * - A relative path is resolved against `cwd` only when a cwd is supplied (the
+ *   launcher, whose cwd is the caller's). The detached worker never resolves
+ *   against its inherited cwd: that directory can be deleted under it (a test
+ *   sandbox's temp dir), and Node's `fs.mkdirSync(relative, { recursive: true })`
+ *   then loops forever at 100% CPU instead of failing.
+ */
+export declare function resolveNativeAbsolutePath(logPath: string, options?: {
+    platform?: NodeJS.Platform;
+    cwd?: () => string;
+}): string | undefined;
+/** Per-step qmd timeout for the detached worker (QMD_REINDEX_STEP_TIMEOUT_SEC). */
+export declare function workerStepTimeoutMs(env: NodeJS.ProcessEnv): number;
 /**
  * Injectable seams for the launcher's worker-log open and detached spawn. Split
  * out purely as a test seam so a synthetic open failure can be forced without
@@ -87,10 +113,7 @@ type WorkerLogOpen = {
  * (appendWorkerLog, capWorkerLog) already swallows I/O failures the same way.
  */
 export declare function openWorkerLog(logPath: string, fallbackLogPath: string | undefined, io: Pick<SpawnWorkerIo, 'mkdirSync' | 'openSync'>): WorkerLogOpen;
-export declare function defaultSpawnWorker({ logPath, fallbackLogPath }: {
-    logPath: string;
-    fallbackLogPath?: string;
-}, io?: SpawnWorkerIo): number;
+export declare function defaultSpawnWorker({ logPath, fallbackLogPath, hqRoot }: SpawnWorkerOptions, io?: SpawnWorkerIo): number;
 /** Defaults used by the CLI; tests supply every nondeterministic dependency. */
 export declare function defaultBackgroundDependencies(hqRoot: string): BackgroundDependencies;
 export declare function installWorkerCleanup(cleanup: () => void, processEvents?: Pick<NodeJS.Process, 'once'>, exit?: (code: number) => void): void;

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

@@ -8,6 +8,54 @@ import { applyIndexSizeLimit as defaultApplyIndexSizeLimit } from './max-doc-byt
 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';
+/**
+ * Default hard wall-clock limit for EACH qmd step (cleanup, update, embed) the
+ * detached worker runs. The worker has no terminal and nobody waiting on it, so
+ * an unbounded step could hold the single-flight lock and a CPU for days. Two
+ * hours leaves a first full CPU-only embed of a large HQ room to finish.
+ * Override with QMD_REINDEX_STEP_TIMEOUT_SEC (a positive integer).
+ */
+const DEFAULT_STEP_TIMEOUT_MS = 2 * 60 * 60 * 1_000;
+const WINDOWS_DRIVE_PATH = /^[A-Za-z]:[\\/]/;
+/**
+ * Turn a requested worker log path (or HQ root) into an absolute native path,
+ * or undefined when it cannot be used safely.
+ *
+ * - On a non-Windows host a drive-letter path (`C:/tmp/qmd-handoff.log`) is the
+ *   residue of a Windows-only `cygpath -m` conversion applied where it does not
+ *   belong. POSIX treats it as RELATIVE, so honouring it would create a `C:`
+ *   directory inside whatever the current directory happens to be. Reject it.
+ * - A relative path is resolved against `cwd` only when a cwd is supplied (the
+ *   launcher, whose cwd is the caller's). The detached worker never resolves
+ *   against its inherited cwd: that directory can be deleted under it (a test
+ *   sandbox's temp dir), and Node's `fs.mkdirSync(relative, { recursive: true })`
+ *   then loops forever at 100% CPU instead of failing.
+ */
+export function resolveNativeAbsolutePath(logPath, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const pathApi = platform === 'win32' ? path.win32 : path.posix;
+    if (!logPath)
+        return undefined;
+    if (platform !== 'win32' && WINDOWS_DRIVE_PATH.test(logPath))
+        return undefined;
+    if (pathApi.isAbsolute(logPath))
+        return logPath;
+    if (!options.cwd)
+        return undefined;
+    try {
+        return pathApi.resolve(options.cwd(), logPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Per-step qmd timeout for the detached worker (QMD_REINDEX_STEP_TIMEOUT_SEC). */
+export function workerStepTimeoutMs(env) {
+    const raw = env.QMD_REINDEX_STEP_TIMEOUT_SEC;
+    if (raw && /^\d+$/.test(raw) && Number(raw) > 0)
+        return Number(raw) * 1_000;
+    return DEFAULT_STEP_TIMEOUT_MS;
+}
 function errnoInfo(error) {
     const e = error;
     return { code: e?.code, syscall: e?.syscall };
@@ -75,7 +123,7 @@ const defaultSpawnWorkerIo = {
     spawn: (command, args, options) => spawn(command, args, options),
     report: reportWorkerLogDegradation,
 };
-export function defaultSpawnWorker({ logPath, fallbackLogPath }, io = defaultSpawnWorkerIo) {
+export function defaultSpawnWorker({ logPath, fallbackLogPath, hqRoot }, io = defaultSpawnWorkerIo) {
     const opened = openWorkerLog(logPath, fallbackLogPath, io);
     if (opened.error) {
         io.report({ requested: logPath, used: opened.logPath, usedFallback: opened.usedFallback, ...opened.error });
@@ -91,7 +139,10 @@ export function defaultSpawnWorker({ logPath, fallbackLogPath }, io = defaultSpa
     const stdio = opened.fd === null
         ? ['ignore', 'ignore', 'ignore']
         : ['ignore', opened.fd, opened.fd];
-    const child = io.spawn(process.execPath, [entry, 'index', 'background', '--worker', ...logArgs], {
+    // Forward the launcher's root so the worker indexes what the caller asked for
+    // instead of re-deriving a root from its inherited (possibly temporary) cwd.
+    const rootArgs = hqRoot ? ['--hq-root', hqRoot] : [];
+    const child = io.spawn(process.execPath, [entry, 'index', 'background', '--worker', ...rootArgs, ...logArgs], {
         detached: true,
         windowsHide: true,
         stdio,
@@ -203,6 +254,10 @@ function workerLogPath(env) {
 function appendWorkerLog(logPath, text) {
     if (!text)
         return;
+    // Never mkdir a relative path: in a deleted cwd Node's recursive mkdirSync
+    // spins forever (see resolveNativeAbsolutePath). Callers pass an absolute path.
+    if (!path.isAbsolute(logPath))
+        return;
     try {
         fs.mkdirSync(path.dirname(logPath), { recursive: true });
         fs.appendFileSync(logPath, text.endsWith('\n') ? text : `${text}\n`);
@@ -217,6 +272,8 @@ function capWorkerLog(logPath, env) {
     const max = Number(raw);
     if (max === 0)
         return;
+    if (!path.isAbsolute(logPath))
+        return;
     try {
         if (!fs.existsSync(logPath) || fs.statSync(logPath).size <= max)
             return;
@@ -265,9 +322,26 @@ export function runBackgroundLauncher(dependencies) {
     // openWorkerLog. `home` is validated non-empty above, so the fallback is
     // always inside a directory this user owns.
     const fallbackLogPath = path.join(home, '.hq', 'logs', 'qmd-handoff.log');
+    const platform = dependencies.platform ?? process.platform;
+    const cwd = dependencies.cwd ?? (() => process.cwd());
+    const requestedLogPath = workerLogPath(dependencies.env);
+    const logPath = resolveNativeAbsolutePath(requestedLogPath, { platform, cwd });
+    if (!logPath) {
+        try {
+            (dependencies.writeStderr ?? ((text) => process.stderr.write(text)))(`hq: background reindex log ${requestedLogPath} is not a usable absolute path on this platform; writing worker output to ${fallbackLogPath} instead.\n`);
+        }
+        catch { /* the notice is best-effort and must never crash the launcher */ }
+    }
+    // Hand the worker an absolute root resolved against the caller's cwd, which
+    // still exists now; a drive-letter root on POSIX is dropped like the log path.
+    const hqRoot = resolveNativeAbsolutePath(dependencies.hqRoot, { platform, cwd });
     return {
         state: 'launched',
-        pid: dependencies.spawnWorker({ logPath: workerLogPath(dependencies.env), fallbackLogPath }),
+        pid: dependencies.spawnWorker({
+            logPath: logPath ?? fallbackLogPath,
+            fallbackLogPath,
+            ...(hqRoot ? { hqRoot } : {}),
+        }),
     };
 }
 /** Run the single-flight cleanup → update → embed pipeline in a worker only. */
@@ -290,7 +364,12 @@ export async function runBackgroundWorker(dependencies) {
     // The cap lives inside the exit cleanup because a signal-path process.exit
     // never unwinds to a `finally` — the shell capped in its EXIT trap for the
     // same reason.
-    const logPath = workerLogPath(dependencies.env);
+    // The launcher always forwards an absolute --log. Anything else (a relative or
+    // drive-letter path from a direct invocation) goes to the per-user log rather
+    // than being resolved against this detached process's inherited cwd.
+    const logPath = resolveNativeAbsolutePath(workerLogPath(dependencies.env), { platform: dependencies.platform })
+        ?? path.join(home, '.hq', 'logs', 'qmd-handoff.log');
+    const timeoutMs = workerStepTimeoutMs(dependencies.env);
     let released = false;
     const cleanup = () => {
         if (released)
@@ -337,7 +416,7 @@ export async function runBackgroundWorker(dependencies) {
         if (await signalWindow())
             return { state: 'terminated' };
         try {
-            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot })));
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot, timeoutMs })));
         }
         catch (error) {
             appendWorkerLog(logPath, errorOutput(error)); // cleanup is intentionally best-effort
@@ -345,7 +424,7 @@ export async function runBackgroundWorker(dependencies) {
         if (await signalWindow())
             return { state: 'terminated' };
         try {
-            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['update'], { cwd: dependencies.hqRoot })));
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['update'], { cwd: dependencies.hqRoot, timeoutMs })));
         }
         catch (error) {
             appendWorkerLog(logPath, errorOutput(error));
@@ -376,7 +455,7 @@ export async function runBackgroundWorker(dependencies) {
         if (loadDecision.forced)
             (dependencies.writeStderr ?? ((text) => process.stderr.write(text)))(loadDecision.notice);
         try {
-            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot })));
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot, timeoutMs })));
             recordSuccessfulEmbed(home, loadGateDependencies);
         }
         catch (error) {

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

@@ -64,6 +64,8 @@ export type QmdSpawn = (cmd: string, args: string[], options: {
     env?: NodeJS.ProcessEnv;
     encoding: 'utf8';
     timeout?: number;
+    /** Signal sent when `timeout` elapses (spawnSync default: SIGTERM). */
+    killSignal?: NodeJS.Signals;
     shell?: boolean;
 }) => {
     status: number | null;
@@ -160,6 +162,20 @@ export declare class QmdTerminatedError extends QmdExitError {
     name: string;
     constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string, signal: string);
 }
+/**
+ * qmd ran past the hard wall-clock limit its caller set (`RunQmdOptions.timeoutMs`)
+ * and was KILLED by hq-cli. Unlike the parent {@link QmdTerminatedError}, the
+ * signal here originates INSIDE hq-cli: spawnSync reports `error.code ===
+ * 'ETIMEDOUT'` after delivering `killSignal`. Raised only when the caller opted
+ * into a timeout, so every untimed qmd call keeps its existing classification.
+ * The background reindex worker uses this to bound each step instead of
+ * holding the single-flight lock indefinitely.
+ */
+export declare class QmdTimedOutError extends QmdTerminatedError {
+    readonly timeoutMs: number;
+    name: string;
+    constructor(message: string, args: string[], stdout: string, stderr: string, signal: string, timeoutMs: number);
+}
 /**
  * qmd refused an LLM-backed operation because its local LLM is DISABLED IN CI:
  * qmd hard-disables every LLM operation whenever `CI` is truthy in the
@@ -511,6 +527,14 @@ export type RunQmdOptions = {
      * cwd / interpreter branches are provable without touching the real disk.
      */
     exists?: (candidate: string) => boolean;
+    /**
+     * Hard wall-clock limit for the qmd child, in milliseconds. When it elapses
+     * the child is sent SIGKILL and {@link QmdTimedOutError} is thrown. Omitted
+     * (the default) means no limit, preserving every interactive caller's
+     * behaviour. Applies to the real spawn path only; the legacy `runner` seam
+     * has no process to kill.
+     */
+    timeoutMs?: number;
 };
 /** Run qmd with captured output and typed failures. */
 export declare function runQmd(args: string[], options?: RunQmdOptions): QmdProcessResult;

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

@@ -133,6 +133,23 @@ export class QmdTerminatedError extends QmdExitError {
         this.signal = signal;
     }
 }
+/**
+ * qmd ran past the hard wall-clock limit its caller set (`RunQmdOptions.timeoutMs`)
+ * and was KILLED by hq-cli. Unlike the parent {@link QmdTerminatedError}, the
+ * signal here originates INSIDE hq-cli: spawnSync reports `error.code ===
+ * 'ETIMEDOUT'` after delivering `killSignal`. Raised only when the caller opted
+ * into a timeout, so every untimed qmd call keeps its existing classification.
+ * The background reindex worker uses this to bound each step instead of
+ * holding the single-flight lock indefinitely.
+ */
+export class QmdTimedOutError extends QmdTerminatedError {
+    timeoutMs;
+    name = 'QmdTimedOutError';
+    constructor(message, args, stdout, stderr, signal, timeoutMs) {
+        super(message, args, null, stdout, stderr, signal);
+        this.timeoutMs = timeoutMs;
+    }
+}
 /**
  * qmd refused an LLM-backed operation because its local LLM is DISABLED IN CI:
  * qmd hard-disables every LLM operation whenever `CI` is truthy in the
@@ -557,6 +574,7 @@ const defaultSpawn = (cmd, args, options) => {
         env: options.env,
         encoding: 'utf8',
         timeout: options.timeout,
+        killSignal: options.killSignal,
         shell: options.shell,
     });
     return {
@@ -588,6 +606,7 @@ function spawnQmd(invocation, args, options = {}) {
         env,
         encoding: 'utf8',
         timeout: options.timeout,
+        ...(options.killSignal ? { killSignal: options.killSignal } : {}),
         shell: plan.shell,
     });
 }
@@ -1286,12 +1305,18 @@ export function runQmd(args, options = {}) {
     // above never opens a store).
     ensureQmdStoreDir(options.env ?? process.env, { cwd: options.cwd });
     const launcher = invocationBin(invocation);
+    const timeoutMs = options.timeoutMs !== undefined && options.timeoutMs > 0 ? options.timeoutMs : undefined;
     const result = spawnQmd(invocation, args, {
         cwd: options.cwd,
         env: options.env ?? process.env,
         platform: options.platform,
         spawn: options.spawn,
+        ...(timeoutMs !== undefined ? { timeout: timeoutMs, killSignal: 'SIGKILL' } : {}),
     });
+    if (timeoutMs !== undefined && result.error?.code === 'ETIMEDOUT') {
+        const subcommand = typeof args[0] === 'string' && args[0].length > 0 ? redactErrorText(args[0]) || 'qmd' : 'qmd';
+        throw new QmdTimedOutError(`qmd ${subcommand} exceeded its ${timeoutMs}ms limit and was killed`, args, result.stdout ?? '', result.stderr ?? '', String(result.signal ?? 'SIGKILL'), timeoutMs);
+    }
     // Thread attribution so finishRunQmd can attribute a spawn-level ENOENT to the
     // right component — the working directory, the Node interpreter, or a
     // genuinely missing qmd — instead of blaming the launcher for all three

package/package.json

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