@indigoai-us/hq-cli 5.94.3 → 5.95.0

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

@@ -9,7 +9,7 @@ export type SearchIndexDependencies = {
     resolveQmdVersion: () => string | undefined;
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
     runBackgroundLauncher?: (dependencies: BackgroundDependencies) => BackgroundResult;
-    runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult;
+    runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult | Promise<BackgroundResult>;
     backgroundStatus?: (dependencies: BackgroundDependencies) => BackgroundStatus;
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */

package/dist/commands/index-cmd.js

@@ -73,13 +73,13 @@ export function registerIndexCommand(program, dependencies = defaults) {
         .option('--log <path>', 'Write worker output to this log file')
         .addOption(new Option('--worker').hideHelp())
         .option('--hq-root <path>', 'HQ root to index (defaults to auto-detected root)')
-        .action((options) => {
+        .action(async (options) => {
         const hqRoot = resolveRoot(options.hqRoot);
         const background = makeBackgroundDependencies(hqRoot, dependencies);
         if (options.log)
             background.env = { ...background.env, QMD_REINDEX_LOG: options.log };
         const result = options.worker
-            ? (dependencies.runBackgroundWorker ?? runBackgroundWorker)(background)
+            ? await (dependencies.runBackgroundWorker ?? runBackgroundWorker)(background)
             : (dependencies.runBackgroundLauncher ?? runBackgroundLauncher)(background);
         if (!options.worker && result.state === 'launched')
             console.log(result.pid);

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

@@ -1,6 +1,6 @@
 import { type QmdProcessResult, type RunQmdOptions } from './index.js';
 export type BackgroundResult = {
-    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed';
+    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed' | 'terminated';
 } | {
     state: 'launched';
     pid: number;
@@ -20,6 +20,9 @@ export type BackgroundDependencies = {
     }) => number;
     /** 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. */
+    processEvents?: Pick<NodeJS.Process, 'once'>;
+    exit?: (code: number) => void;
 };
 export type BackgroundStatus = {
     lock: 'held' | 'stale' | 'free';
@@ -33,7 +36,7 @@ export declare function installWorkerCleanup(cleanup: () => void, processEvents?
 /** Start a detached worker; this public entry never owns the qmd pipeline. */
 export declare function runBackgroundLauncher(dependencies: BackgroundDependencies): BackgroundResult;
 /** Run the single-flight cleanup → update → embed pipeline in a worker only. */
-export declare function runBackgroundWorker(dependencies: BackgroundDependencies): BackgroundResult;
+export declare function runBackgroundWorker(dependencies: BackgroundDependencies): Promise<BackgroundResult>;
 /** Report the background lock and latest successful completion for `hq index status`. */
 export declare function backgroundStatus(dependencies: BackgroundDependencies): BackgroundStatus;
 //# sourceMappingURL=background.d.ts.map

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

@@ -170,6 +170,10 @@ function acquireClaim(home, observedGeneration, dependencies) {
         const claimant = path.join(claim, `c.${dependencies.pid}.${dependencies.random()}`);
         try {
             fs.mkdirSync(claimant);
+            // Test-only deterministic failure inject (unset in production) — shell
+            // parity with the script's claimant write_owner_record injection.
+            if (dependencies.env.QMD_FORCE_CLAIMANT_WRITE_FAIL)
+                throw new Error('forced claimant write failure');
             fs.writeFileSync(path.join(claimant, 'owner'), `pid=${dependencies.pid}\nts=${dependencies.now()}\n`);
             return { claim, claimant };
         }
@@ -236,6 +240,10 @@ function createAndPublishLock(home, dependencies) {
     const ownerFile = path.join(directory, 'owner');
     const temporary = path.join(directory, `.owner.tmp.${dependencies.pid}.${dependencies.random()}`);
     try {
+        // Test-only deterministic failure inject (unset in production) — shell
+        // parity: the script's write_owner_record honored the same variable.
+        if (dependencies.env.QMD_FORCE_OWNER_WRITE_FAIL)
+            throw new Error('forced owner write failure');
         fs.writeFileSync(temporary, `pid=${dependencies.pid}\nts=${dependencies.now()}\nnonce=${nonce}\n`);
         fs.renameSync(temporary, ownerFile);
         dependencies.afterOwnerPublish?.(ownerFile);
@@ -290,11 +298,52 @@ function releaseLock(home, dependencies) {
 export function installWorkerCleanup(cleanup, processEvents = process, exit = () => undefined) {
     processEvents.once('exit', cleanup);
     // Unlike Bash, Node cannot turn a SIGKILL or an already-defaulted signal into
-    // catchable cleanup. SIGINT/SIGTERM are registered here and the CLI's normal
-    // process exit then runs the same idempotent owner release. Exiting prevents
-    // a synchronous pipeline from continuing after it has released ownership.
+    // catchable cleanup. SIGINT/SIGTERM/SIGHUP are registered here (the shell
+    // worker trapped `INT TERM HUP`; a detached worker's controlling terminal
+    // going away delivers HUP, and the default disposition would kill the
+    // process without releasing the lock) and the CLI's normal process exit then
+    // runs the same idempotent owner release. Exiting prevents a synchronous
+    // pipeline from continuing after it has released ownership.
     processEvents.once('SIGINT', () => { cleanup(); exit(0); });
     processEvents.once('SIGTERM', () => { cleanup(); exit(0); });
+    processEvents.once('SIGHUP', () => { cleanup(); exit(0); });
+}
+function workerLogPath(env) {
+    return env.QMD_REINDEX_LOG
+        ?? env.QMD_HANDOFF_LOG
+        ?? path.join(env.HANDOFF_LOG_DIR ?? '/tmp', 'qmd-handoff.log');
+}
+function appendWorkerLog(logPath, text) {
+    if (!text)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        fs.appendFileSync(logPath, text.endsWith('\n') ? text : `${text}\n`);
+    }
+    catch { /* logging is best-effort, exactly like the shell worker's >>"$LOG" */ }
+}
+/** Keep only the trailing QMD_HANDOFF_LOG_MAX_BYTES of the worker log (shell cap_log parity). */
+function capWorkerLog(logPath, env) {
+    const raw = env.QMD_HANDOFF_LOG_MAX_BYTES ?? '65536';
+    if (!/^\d+$/.test(raw))
+        return;
+    const max = Number(raw);
+    if (max === 0)
+        return;
+    try {
+        if (!fs.existsSync(logPath) || fs.statSync(logPath).size <= max)
+            return;
+        const content = fs.readFileSync(logPath);
+        fs.writeFileSync(logPath, content.subarray(content.length - max));
+    }
+    catch { /* best-effort, matching the shell's cap_log */ }
+}
+function stepOutput(result) {
+    return `${result.stdout ?? ''}${result.stderr ?? ''}`;
+}
+function errorOutput(error) {
+    const e = error;
+    return `${e.stdout ?? ''}${e.stderr ?? ''}` || (e.message ?? '');
 }
 /** Start a detached worker; this public entry never owns the qmd pipeline. */
 export function runBackgroundLauncher(dependencies) {
@@ -309,13 +358,10 @@ export function runBackgroundLauncher(dependencies) {
     catch {
         return { state: 'skipped' };
     }
-    const logPath = dependencies.env.QMD_REINDEX_LOG
-        ?? dependencies.env.QMD_HANDOFF_LOG
-        ?? path.join(dependencies.env.HANDOFF_LOG_DIR ?? '/tmp', 'qmd-handoff.log');
-    return { state: 'launched', pid: dependencies.spawnWorker({ logPath }) };
+    return { state: 'launched', pid: dependencies.spawnWorker({ logPath: workerLogPath(dependencies.env) }) };
 }
 /** Run the single-flight cleanup → update → embed pipeline in a worker only. */
-export function runBackgroundWorker(dependencies) {
+export async function runBackgroundWorker(dependencies) {
     if (isHostedAgent(dependencies.env))
         return { state: 'skipped-agent' };
     const home = dependencies.env.HOME;
@@ -329,14 +375,32 @@ export function runBackgroundWorker(dependencies) {
     }
     if (isRecentCompletion(home, dependencies) || !acquireLock(home, dependencies))
         return { state: 'busy' };
+    // Shell-worker log parity: each step's captured output appends to the
+    // handoff log and the log keeps only its trailing QMD_HANDOFF_LOG_MAX_BYTES.
+    // 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);
     let released = false;
     const cleanup = () => {
         if (released)
             return;
         released = true;
         releaseLock(home, dependencies);
+        capWorkerLog(logPath, dependencies.env);
+    };
+    installWorkerCleanup(cleanup, dependencies.processEvents ?? process, dependencies.exit ?? ((code) => process.exit(code)));
+    // A signal that lands during a synchronous qmd step cannot interrupt it, and
+    // Node defers the handler until the event loop next turns — which a fully
+    // synchronous pipeline never lets happen, so SIGTERM used to be processed
+    // only AFTER update/embed had already run. Bash traps fire between commands;
+    // yielding one event-loop turn between steps restores that contract. If the
+    // handler ran (production exits; tests inject `exit`), `released` is set and
+    // the pipeline stops before its next step.
+    const signalWindow = async () => {
+        await new Promise((resolve) => setImmediate(resolve));
+        return released;
     };
-    installWorkerCleanup(cleanup, process, (code) => process.exit(code));
     try {
         if (isRecentCompletion(home, dependencies))
             return { state: 'busy' };
@@ -349,21 +413,36 @@ export function runBackgroundWorker(dependencies) {
             // The shell worker has no collection-registration step. Keep this #306
             // integration best-effort so it cannot suppress a later index update.
         }
+        if (await signalWindow())
+            return { state: 'terminated' };
         try {
-            dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot });
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot })));
         }
-        catch { /* cleanup is intentionally best-effort */ }
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error)); // cleanup is intentionally best-effort
+        }
+        if (await signalWindow())
+            return { state: 'terminated' };
         try {
-            dependencies.runQmd(['update'], { cwd: dependencies.hqRoot });
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['update'], { cwd: dependencies.hqRoot })));
         }
-        catch {
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error));
+            appendWorkerLog(logPath, `[qmd-reindex-bg] update-failed ts=${dependencies.now()}`);
             return { state: 'update-failed' };
         }
+        if (await signalWindow())
+            return { state: 'terminated' };
         try {
-            dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot });
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot })));
+        }
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error)); // a completed embed attempt still permits the stamp
         }
-        catch { /* a completed embed attempt still permits the completion stamp */ }
+        if (await signalWindow())
+            return { state: 'terminated' };
         writeCompletion(home, dependencies);
+        appendWorkerLog(logPath, `[qmd-reindex-bg] done ts=${dependencies.now()}`);
         return { state: 'completed' };
     }
     finally {

package/package.json

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