@indigoai-us/hq-cli 5.97.3-rc.1 → 5.97.3

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.97.3] — 2026-08-10
+
 ## [5.97.3-rc.1] — 2026-08-10
 
 ## [5.97.2]

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

@@ -1,3 +1,4 @@
+import { type StdioOptions } from 'node:child_process';
 import { type QmdProcessResult, type RunQmdOptions } from './index.js';
 export type BackgroundResult = {
     state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed' | 'terminated';
@@ -17,6 +18,7 @@ export type BackgroundDependencies = {
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
     spawnWorker: (options: {
         logPath: string;
+        fallbackLogPath?: string;
     }) => number;
     /** Test seam for simulating a competing owner replacing the atomic record. */
     afterOwnerPublish?: (ownerFile: string) => void;
@@ -28,6 +30,60 @@ export type BackgroundStatus = {
     lock: 'held' | 'stale' | 'free';
     completedAt?: 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
+ * touching real files or the invoking uid.
+ */
+export type SpawnWorkerIo = {
+    mkdirSync: (directory: string) => void;
+    openSync: (file: string) => number;
+    closeSync: (fd: number) => void;
+    spawn: (command: string, args: string[], options: {
+        detached: boolean;
+        stdio: StdioOptions;
+    }) => {
+        pid?: number;
+        unref: () => void;
+    };
+    /** Report a degraded open without swallowing it (stderr notice + breadcrumb). */
+    report: (info: WorkerLogDegradation) => void;
+};
+export type WorkerLogDegradation = {
+    requested: string;
+    used: string | null;
+    usedFallback: boolean;
+    code?: string;
+    syscall?: string;
+};
+type WorkerLogOpen = {
+    fd: number | null;
+    logPath: string | null;
+    usedFallback: boolean;
+    error?: {
+        code?: string;
+        syscall?: string;
+    };
+};
+/**
+ * Open the detached worker's log, degrading instead of crashing. Try the
+ * requested path; on ANY open failure retry once against a per-user fallback
+ * under the caller's own $HOME; if that also fails, return a no-log result so
+ * the launcher still spawns the worker.
+ *
+ * This is the fix for Sentry indigo-d0/hq-cli 7663380187: HQ's /handoff always
+ * points --log at the fixed, shared, world-writable /tmp/qmd-handoff.log, and an
+ * unguarded fs.openSync(logPath, 'a') here threw EACCES whenever that file
+ * already existed owned by another uid, so the reindex worker never spawned and
+ * the raw errno reached Sentry. A diagnostic side-channel must not take down the
+ * feature it exists to observe — every other worker-log writer in this module
+ * (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;
 /** Defaults used by the CLI; tests supply every nondeterministic dependency. */
 export declare function defaultBackgroundDependencies(hqRoot: string): BackgroundDependencies;
 /** Match the shell forwarder's hosted-agent markers before looking up qmd. */
@@ -39,4 +95,5 @@ export declare function runBackgroundLauncher(dependencies: BackgroundDependenci
 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;
+export {};
 //# sourceMappingURL=background.d.ts.map

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

@@ -1,20 +1,99 @@
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { Sentry } from '../../sentry.js';
 import { reconcileCollections as defaultReconcileCollections, resolveQmdBin as defaultResolveQmdBin, runQmd as defaultRunQmd, } from './index.js';
 const LOCK_NAME = 'qmd-reindex-bg.lock';
 const COMPLETE_NAME = 'qmd-reindex-bg.completed';
-function defaultSpawnWorker({ logPath }) {
-    fs.mkdirSync(path.dirname(logPath), { recursive: true });
-    const log = fs.openSync(logPath, 'a');
+function errnoInfo(error) {
+    const e = error;
+    return { code: e?.code, syscall: e?.syscall };
+}
+/**
+ * Open the detached worker's log, degrading instead of crashing. Try the
+ * requested path; on ANY open failure retry once against a per-user fallback
+ * under the caller's own $HOME; if that also fails, return a no-log result so
+ * the launcher still spawns the worker.
+ *
+ * This is the fix for Sentry indigo-d0/hq-cli 7663380187: HQ's /handoff always
+ * points --log at the fixed, shared, world-writable /tmp/qmd-handoff.log, and an
+ * unguarded fs.openSync(logPath, 'a') here threw EACCES whenever that file
+ * already existed owned by another uid, so the reindex worker never spawned and
+ * the raw errno reached Sentry. A diagnostic side-channel must not take down the
+ * feature it exists to observe — every other worker-log writer in this module
+ * (appendWorkerLog, capWorkerLog) already swallows I/O failures the same way.
+ */
+export function openWorkerLog(logPath, fallbackLogPath, io) {
+    try {
+        io.mkdirSync(path.dirname(logPath));
+        return { fd: io.openSync(logPath), logPath, usedFallback: false };
+    }
+    catch (primaryError) {
+        const error = errnoInfo(primaryError);
+        if (fallbackLogPath && fallbackLogPath !== logPath) {
+            try {
+                io.mkdirSync(path.dirname(fallbackLogPath));
+                return { fd: io.openSync(fallbackLogPath), logPath: fallbackLogPath, usedFallback: true, error };
+            }
+            catch { /* fall through to the no-log result below */ }
+        }
+        return { fd: null, logPath: null, usedFallback: false, error };
+    }
+}
+/**
+ * Surface a degraded worker-log open without swallowing it: one best-effort
+ * stderr line naming the rejected path and where output went, plus a Sentry
+ * breadcrumb carrying only the errno — never the fallback path, which lives
+ * under $HOME. The condition is now handled and degraded, so it is deliberately
+ * NOT captured as an exception; the breadcrumb just gives the next genuine
+ * failure at this site the errno evidence this event lacked.
+ */
+function reportWorkerLogDegradation(info) {
+    const reason = info.code ? ` (${info.code}${info.syscall ? ` on ${info.syscall}` : ''})` : '';
+    const destination = info.used ? `writing worker output to ${info.used} instead` : 'disabling worker output';
+    try {
+        process.stderr.write(`hq: cannot open background reindex log ${info.requested}${reason}; ${destination}.\n`);
+    }
+    catch { /* the notice itself is best-effort and must never crash the launcher */ }
+    try {
+        Sentry.addBreadcrumb({
+            category: 'qmd.background',
+            level: 'warning',
+            message: 'worker log open degraded',
+            data: { code: info.code, syscall: info.syscall, usedFallback: info.usedFallback },
+        });
+    }
+    catch { /* breadcrumb is best-effort; no Sentry client is active in tests */ }
+}
+const defaultSpawnWorkerIo = {
+    mkdirSync: (directory) => { fs.mkdirSync(directory, { recursive: true }); },
+    openSync: (file) => fs.openSync(file, 'a'),
+    closeSync: (fd) => { fs.closeSync(fd); },
+    spawn: (command, args, options) => spawn(command, args, options),
+    report: reportWorkerLogDegradation,
+};
+export function defaultSpawnWorker({ logPath, fallbackLogPath }, io = defaultSpawnWorkerIo) {
+    const opened = openWorkerLog(logPath, fallbackLogPath, io);
+    if (opened.error) {
+        io.report({ requested: logPath, used: opened.logPath, usedFallback: opened.usedFallback, ...opened.error });
+    }
     const entry = process.argv[1];
     if (!entry)
         throw new Error('Cannot determine hq CLI entrypoint for background worker');
-    const child = spawn(process.execPath, [entry, 'index', 'background', '--worker', '--log', logPath], {
+    // Hand the child the log path we actually opened so its own appendWorkerLog /
+    // capWorkerLog write to the same file. When nothing could be opened, omit
+    // --log entirely so the child resolves its own default rather than re-failing
+    // on the path we already rejected — the reindex itself must still run.
+    const logArgs = opened.logPath ? ['--log', opened.logPath] : [];
+    const stdio = opened.fd === null
+        ? ['ignore', 'ignore', 'ignore']
+        : ['ignore', opened.fd, opened.fd];
+    const child = io.spawn(process.execPath, [entry, 'index', 'background', '--worker', ...logArgs], {
         detached: true,
-        stdio: ['ignore', log, log],
+        stdio,
     });
-    fs.closeSync(log);
+    if (opened.fd !== null)
+        io.closeSync(opened.fd);
     child.unref();
     if (!child.pid)
         throw new Error('Unable to start qmd background worker');
@@ -358,7 +437,15 @@ export function runBackgroundLauncher(dependencies) {
     catch {
         return { state: 'skipped' };
     }
-    return { state: 'launched', pid: dependencies.spawnWorker({ logPath: workerLogPath(dependencies.env) }) };
+    // Fall back to a per-user log under the caller's own $HOME when the requested
+    // (often the shared, world-writable /tmp) log cannot be opened — see
+    // 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');
+    return {
+        state: 'launched',
+        pid: dependencies.spawnWorker({ logPath: workerLogPath(dependencies.env), fallbackLogPath }),
+    };
 }
 /** Run the single-flight cleanup → update → embed pipeline in a worker only. */
 export async function runBackgroundWorker(dependencies) {

package/package.json

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