@indigoai-us/hq-cli 5.336.0 → 5.337.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.337.0] — 2026-10-03
+- QMD index updates now share the cross-process writer lock and skip bounded SQLite contention so a later sync can catch up.
+- Self-update now checks the Windows npm prefix that stores command shims, so an unwritable prefix is detected before npm runs.
+
 ## [5.336.0] — 2026-10-03
 - Client-health refresh failures now retain the bounded Cognito OAuth error class for accurate auth diagnostics.
 - Fix macOS Bash 3.2 service PATH generation when nounset is enabled.

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

@@ -21,6 +21,9 @@ export type SearchIndexDependencies = {
     singleFlightEnabled?: () => boolean;
     /** Test seams for the host load gate consulted while the embed lock is held. */
     loadGateDependencies?: LoadGateDependencies;
+    /** Test seams for the bounded wait before an index-sync write. */
+    nowMs?: () => number;
+    sleepSync?: (milliseconds: number) => void;
     writeStderr?: (text: string) => void;
 };
 export type SyncSearchIndexResult = {

package/dist/commands/index-cmd.js

@@ -1,5 +1,5 @@
 import { Option } from 'commander';
-import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcileCollections, resolveQmdBin, resolveQmdHome, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
+import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcileCollections, resolveQmdBin, resolveQmdHome, resolveQmdVersion, runQmd, QmdExitError, } 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';
@@ -22,6 +22,40 @@ const defaults = {
     runBackgroundWorker,
     backgroundStatus,
 };
+const INDEX_SYNC_LOCK_WAIT_MS = 5_000;
+const INDEX_SYNC_LOCK_POLL_MS = 100;
+const syncSleepBuffer = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+function sleepSync(milliseconds) {
+    Atomics.wait(syncSleepBuffer, 0, 0, milliseconds);
+}
+function isSqliteBusy(error) {
+    return error instanceof QmdExitError &&
+        /\bSQLITE_BUSY\b|SqliteError:\s*database is locked\b/i.test(`${error.message}\n${error.stderr}`);
+}
+/** Wait for the shared writer or SQLite transaction to clear, then skip safely. */
+function runWithIndexSyncLock(home, lockDependencies, dependencies, run) {
+    const now = dependencies.nowMs ?? Date.now;
+    const sleep = dependencies.sleepSync ?? sleepSync;
+    const deadline = now() + INDEX_SYNC_LOCK_WAIT_MS;
+    const maxAttempts = Math.ceil(INDEX_SYNC_LOCK_WAIT_MS / INDEX_SYNC_LOCK_POLL_MS) + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        try {
+            const outcome = runWithEmbedLock(home, lockDependencies, run);
+            if (outcome !== 'busy')
+                return outcome;
+        }
+        catch (error) {
+            if (isSqliteBusy(error))
+                return 'busy';
+            throw error;
+        }
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            return 'busy';
+        sleep(Math.min(INDEX_SYNC_LOCK_POLL_MS, remaining));
+    }
+    return 'busy';
+}
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */
 export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
     const updateIndex = () => {
@@ -60,12 +94,12 @@ export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
         return undefined;
     };
     if (singleFlightEnabled) {
-        const outcome = runWithEmbedLock(home, lockDependencies, () => {
+        const outcome = runWithIndexSyncLock(home, lockDependencies, dependencies, () => {
             updateIndex();
             return embed ? runEmbed() : undefined;
         });
         if (outcome === 'busy') {
-            writeStderr('hq: qmd reindex is already running; skipping this pass.\n');
+            writeStderr('hq: qmd index update is busy; skipping this pass.\n');
             return { status: 'skipped', reason: 'busy' };
         }
         if (outcome === 'unavailable') {
@@ -74,7 +108,17 @@ export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
         }
         return { status: 'updated', embedded };
     }
-    updateIndex();
+    const updateOutcome = runWithIndexSyncLock(home, lockDependencies, dependencies, () => {
+        updateIndex();
+    });
+    if (updateOutcome === 'busy') {
+        writeStderr('hq: qmd index update is busy; skipping this pass.\n');
+        return { status: 'skipped', reason: 'busy' };
+    }
+    if (updateOutcome === 'unavailable') {
+        writeStderr('hq: cannot access the qmd reindex lock; skipping this pass.\n');
+        return { status: 'skipped', reason: 'unavailable' };
+    }
     if (!embed)
         return { status: 'updated', embedded: false };
     const outcome = runWithEmbedLock(home, lockDependencies, runEmbed);

package/dist/lib/core-utils/qmd-reindex-after-sync.js

@@ -122,11 +122,28 @@ export function qmdReindexAfterSync(args = [], options = {}) {
         }
         return 0;
     }
-    updateIndex();
-    if (!embed)
-        return 0;
     const lockDependencies = options.embedLockDependencies ?? defaultEmbedLockDependencies();
     const home = resolveQmdHome(lockDependencies.env);
+    try {
+        const outcome = runWithEmbedLock(home, lockDependencies, () => { updateIndex(); });
+        if (outcome === "busy") {
+            line(stderr, "hq: qmd reindex is already running; skipping this post-sync pass.");
+            return 0;
+        }
+        if (outcome === "unavailable") {
+            line(stderr, "hq: cannot access the qmd reindex lock; skipping this post-sync pass.");
+            return 0;
+        }
+    }
+    catch (error) {
+        if (error instanceof LoadGateConfigurationError)
+            line(stderr, `hq: ${error.message}`);
+        warnOnNativeStartupFailure(error);
+        /* embeddings are deferred-cost and sync must not wait on search freshness */
+        return 0;
+    }
+    if (!embed)
+        return 0;
     try {
         const outcome = runWithEmbedLock(home, lockDependencies, () => runEmbed(home, lockDependencies));
         if (outcome === "busy") {

package/dist/lib/search-index/reindex-single-flight-flag.d.ts

@@ -1,5 +1,5 @@
 export declare const QMD_REINDEX_SINGLE_FLIGHT_FLAG = "qmd.reindex-single-flight";
 export declare const QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK = false;
-/** Keep all HQ-managed QMD writers coordinated only for explicitly enabled canaries. */
+/** Keep whole update-to-embed passes single-flight only for explicitly enabled canaries. */
 export declare function qmdReindexSingleFlightEnabled(): boolean;
 //# sourceMappingURL=reindex-single-flight-flag.d.ts.map

package/dist/lib/search-index/reindex-single-flight-flag.js

@@ -1,7 +1,7 @@
 import { resolveProcessFlagGate } from "../flag-registry.js";
 export const QMD_REINDEX_SINGLE_FLIGHT_FLAG = "qmd.reindex-single-flight";
 export const QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK = false;
-/** Keep all HQ-managed QMD writers coordinated only for explicitly enabled canaries. */
+/** Keep whole update-to-embed passes single-flight only for explicitly enabled canaries. */
 export function qmdReindexSingleFlightEnabled() {
     return resolveProcessFlagGate(QMD_REINDEX_SINGLE_FLIGHT_FLAG, { fallback: QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK }, () => QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK);
 }

package/dist/utils/version-gate.d.ts

@@ -178,7 +178,7 @@ export declare function isPrefixWritable(prefix: string, access?: (target: strin
  * When one of those directories has not been created yet, check its nearest
  * existing ancestor: npm can create a child only if that ancestor is writable.
  */
-export declare function canWriteNpmInstall(prefix: string, packageRoot: string, access?: (target: string, mode: number) => void): boolean;
+export declare function canWriteNpmInstall(prefix: string, packageRoot: string, access?: (target: string, mode: number) => void, platform?: NodeJS.Platform): boolean;
 /** Claim the one local warning/report for this installed version and prefix. */
 export declare function claimNonWritableNpmPrefixNotice(install: Pick<RunningInstall, "manager" | "prefix" | "packageRoot">, fromVersion: string, homeDir?: string, kind?: "user" | "report"): boolean;
 /** Emit one path-free warning event for a handled non-writable npm prefix. */

package/dist/utils/version-gate.js

@@ -432,8 +432,8 @@ export function isPrefixWritable(prefix, access = (target, mode) => accessSync(t
  * When one of those directories has not been created yet, check its nearest
  * existing ancestor: npm can create a child only if that ancestor is writable.
  */
-export function canWriteNpmInstall(prefix, packageRoot, access = (target, mode) => accessSync(target, mode)) {
-    let nodeModulesRoot = path.join(prefix, process.platform === "win32" ? "node_modules" : "lib/node_modules");
+export function canWriteNpmInstall(prefix, packageRoot, access = (target, mode) => accessSync(target, mode), platform = process.platform) {
+    let nodeModulesRoot = path.join(prefix, platform === "win32" ? "node_modules" : "lib/node_modules");
     let cursor = path.resolve(packageRoot);
     while (true) {
         if (path.basename(cursor).toLowerCase() === "node_modules") {
@@ -446,11 +446,11 @@ export function canWriteNpmInstall(prefix, packageRoot, access = (target, mode)
         cursor = parent;
     }
     const mode = fsConstants.W_OK | fsConstants.X_OK;
-    // npm needs write access to the directories it replaces or links into. The
-    // prefix root itself need not be writable when those directories already
-    // exist; when one is missing, the nearest-existing-ancestor check below
-    // still verifies permission to create it.
-    const targets = [path.join(prefix, "bin"), nodeModulesRoot, path.dirname(packageRoot)];
+    // POSIX npm writes command shims under <prefix>/bin; Windows writes them
+    // directly under <prefix>. Check the actual shim directory alongside the
+    // package directories npm replaces or links into.
+    const shimDirectory = platform === "win32" ? prefix : path.join(prefix, "bin");
+    const targets = [shimDirectory, nodeModulesRoot, path.dirname(packageRoot)];
     return targets.every((target) => {
         let candidate = path.resolve(target);
         while (true) {

package/package.json

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