@indigoai-us/hq-cli 5.345.91 → 5.345.92

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [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.
 

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