@indigoai-us/hq-cli 5.106.0 → 5.106.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [5.106.2] — 2026-09-02
+
+### Fixed
+
+- An `hq` installed as a local project dependency no longer updates itself in an
+  endless loop. The updater used to treat a pnpm virtual store
+  (`node_modules/.pnpm/...`) as an npm install prefix and install there — a
+  directory nothing on PATH ever reads — then report success, so the next
+  command found the same old build and updated again. On one outpost this ran
+  `npm install -g` up to 31 times an hour for days. Such copies are now
+  identified as local, reported with the path to fix, and left for their owning
+  project to update.
+- The updater refuses an "update" to a version that is not newer than the one
+  already installed, instead of reinstalling it on every invocation.
+- Success is now reported only after verifying the new version is the one PATH
+  actually resolves. An install that lands somewhere the running `hq` never
+  reads is reported as a failed update rather than as a success.
+
+## [5.106.1] — 2026-09-02
+
 ## [5.106.0] — 2026-09-02
 
 ### Fixed

package/dist/commands/core-checkpoint.d.ts

@@ -6,6 +6,7 @@
  * reads/writes. It never waits for the sibling, and it never performs network
  * I/O itself.
  */
+import * as fs from "node:fs";
 import { Command } from "commander";
 type Backend = "claude" | "codex" | "grok" | "none";
 type SpawnableBackend = Exclude<Backend, "none">;
@@ -41,6 +42,15 @@ export declare const CHECKPOINT_IDLE_REPLY_REMINDER: string;
  */
 export declare const SIBLING_PROMPT_TEMPLATE = "You are the HQ checkpoint sibling \u2014 a background maintenance agent for this\nHQ install. Your parent session's state is in <payloadPath>. Work\nquietly and do not ask questions; if something is ambiguous, record it in the\nreport instead of guessing.\n\n1. Read the payload. If it lists a transcript path that exists, read its tail (~400 lines)\n   both for session context and to extract additional reusable learnings/insights\n   the parent did not pass explicitly. Never quote secrets\n   or tokens from the transcript. If .claude/skills/checkpoint/SKILL.md exists\n   under this HQ root, read it and follow it wherever it goes beyond these instructions;\n   the write bounds below always win over the skill text.\n2. Upgrade the thread file named in the payload IN PLACE: verify/repair its\n   JSON; fill git.remote_url, git.initial_commit, git.commits_made, and\n   git.knowledge_repos by scanning core/knowledge/public/*,\n   core/knowledge/private/*, personal/knowledge/*, and companies/*/knowledge\n   for symlinks or directories containing .git, recording dirty repositories\n   as {\"<name>\": {\"commit\": \"<short>\", \"dirty\": true}}. Fill worker,\n   next_steps, and insights; set type to \"checkpoint\"; then rename the file to\n   drop -auto- from its filename. Use the renamed path in every reference you\n   write afterwards.\n3. For every explicit or transcript-derived learning that is a reusable rule,\n   FIRST search the existing policies for one the learning refines, contradicts\n   or duplicates. Then take exactly one of these actions and name it in the\n   report \u2014 the policy set is curated, not append-only:\n   - AMEND an existing policy in place when the learning sharpens it, narrows\n     its scope, or adds a case, and the rule as written is still correct.\n   - SUPERSEDE it when the learning contradicts it: rewrite the rule to what is\n     now true and record inside the file what changed and why.\n   - MERGE near-duplicates into the single best-named file, then delete the\n     files you merged away.\n   - CREATE a new policy only when no existing policy covers the rule.\n   Follow core/knowledge/public/hq-core/policies-spec.md. Write under\n   personal/policies/ or, only when the payload names a company and the rule is\n   company-specific, companies/<company>/policies/.\n   DELETION BOUNDS: delete a policy only as the MERGE or SUPERSEDE step above,\n   only inside those two directories, and never one whose body marks it HARD \u2014\n   if a hard policy now looks wrong, leave it untouched and flag it in the\n   report for a human to decide. Never delete a file you have not read.\n   Apply the same curation to durable facts (not rules) under\n   personal/knowledge/ or companies/<company>/knowledge/: correct a stale fact\n   in place rather than appending a second, contradictory copy of it.\n   Store up to two explicit or transcript-derived insights per\n   core/knowledge/public/hq-core/insights-spec.md when present, otherwise\n   workspace/insights/.\n4. Close an active session journal fail-soft with\n   bash .claude/skills/_shared/journal.sh close \"<project_dir>\" \"<one-line synthesis>\".\n   Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with\n   id, created_at, summary, files, and next_steps for backward compatibility.\n5. Update workspace/threads/recent.md and regenerate\n   workspace/threads/INDEX.md. For each company whose knowledge path appears\n   in files_touched, regenerate companies/<company>/knowledge/INDEX.md under\n   core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation\n   is allowed for those companies, but knowledge/policy content writes remain\n   restricted to the payload's named company.\n6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;\n   skip silently on any failure. Hook or automation improvements go ONLY under\n   personal/hooks/ as proposals.\n7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.\n8. Write <runDir>/report.md \u2014 full prose: what you read, what you changed\n   (paths), and what you skipped and why. List every policy or knowledge file\n   you amended, superseded, merged or deleted with the reason, so a human can\n   audit and reverse it; a deletion you do not name in the report is a defect.\n   Then drain the queue: while\n   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim\n   it atomically by renaming it aside \u2014\n   mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl\n   (N counting up from 2) \u2014 and process the claimed payloads with this same\n   flow. Repeat until a claim finds nothing left, then update the report.\n   NEVER read the queue and truncate it in place: a payload appended between\n   your read and the truncate is lost, and its checkpoint is never enriched.\n";
 export declare function renderSiblingPrompt(runDir: string, payloadPath: string): string;
+export type WriteStampsOptions = {
+    /**
+     * Filesystem seam (default the real `node:fs`); injected in tests to force a
+     * permission errno so the HqStateWriteError conversion can be proven without a
+     * real unwritable path.
+     */
+    fs?: Pick<typeof fs, "mkdirSync" | "writeFileSync">;
+};
+export declare function writeStamps(liveRoot: string, sessionId: string | undefined, options?: WriteStampsOptions): string[];
 /**
  * Preference order for `--backend auto`: the caller's own backend first, so a
  * claude session keeps using claude and a codex session keeps using codex

package/dist/commands/core-checkpoint.js

@@ -12,6 +12,7 @@ import { execFileSync, spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { peekIdToken } from "../utils/id-token.js";
+import { toHqStateWriteError } from "../utils/hq-state-write-error.js";
 const DEFAULT_TRIGGER = "stop-gate";
 const BACKENDS = new Set(["auto", "claude", "codex", "grok", "none"]);
 // Pinned by operator directive 2026-07-31; change defaults here deliberately.
@@ -368,9 +369,30 @@ function gitStateFor(cwd, liveRoot, initialCommit, explicitCommits) {
                 : [],
     };
 }
-function writeStamps(liveRoot, sessionId) {
+/**
+ * Perform a write into HQ's OWN state tree, converting a filesystem errno into a
+ * typed, path-naming {@link HqStateWriteError} (the boundary prints that and does
+ * NOT capture it — the fault is the user's machine, not an hq bug) while leaving
+ * any NON-errno failure — a genuine defect — to propagate unchanged and stay
+ * reportable. Scoped by the caller to the checkpoint state paths this command
+ * derives. The checkpoint still FAILS (exits non-zero) on such an error; only
+ * the classification and the message change (HQ-CLI-19, Sentry 7702730566).
+ */
+function writeHqState(targetPath, operation, perform) {
+    try {
+        perform();
+    }
+    catch (error) {
+        const typed = toHqStateWriteError(error, targetPath, operation);
+        if (typed)
+            throw typed;
+        throw error;
+    }
+}
+export function writeStamps(liveRoot, sessionId, options = {}) {
+    const fsImpl = options.fs ?? fs;
     const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
-    fs.mkdirSync(stateDir, { recursive: true });
+    writeHqState(stateDir, "create the checkpoint state directory", () => fsImpl.mkdirSync(stateDir, { recursive: true }));
     const sessionKey = sessionId
         ? sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "unknown"
         : "unknown";
@@ -379,8 +401,9 @@ function writeStamps(liveRoot, sessionId) {
         path.join(stateDir, "checkpoint-cli-last"),
         path.join(stateDir, `checkpoint-cli-last-${sessionKey}`),
     ];
-    for (const stampPath of stampPaths)
-        fs.writeFileSync(stampPath, timestamp);
+    for (const stampPath of stampPaths) {
+        writeHqState(stampPath, "write its checkpoint state file", () => fsImpl.writeFileSync(stampPath, timestamp));
+    }
     return stampPaths;
 }
 /**
@@ -894,8 +917,8 @@ function runCheckpoint(options, command, group) {
             trigger: input.trigger,
         },
     };
-    fs.mkdirSync(path.dirname(threadPath), { recursive: true });
-    fs.writeFileSync(threadPath, `${JSON.stringify(thread, null, 2)}\n`);
+    writeHqState(path.dirname(threadPath), "create the checkpoint thread directory", () => fs.mkdirSync(path.dirname(threadPath), { recursive: true }));
+    writeHqState(threadPath, "write the checkpoint thread file", () => fs.writeFileSync(threadPath, `${JSON.stringify(thread, null, 2)}\n`));
     writeStamps(liveRoot, input.sessionId);
     printResult(`checkpoint: ${relativeThreadPath}`);
     // finally: the thread is already written at this point, so the agent must

package/dist/commands/index-cmd.js

@@ -4,6 +4,7 @@ import { backgroundStatus, defaultBackgroundDependencies, runBackgroundLauncher,
 import { findHqRoot } from '../utils/manifest.js';
 import { QMD_NATIVE_BINDING_REMEDY, isQmdNativeBindingError, } from '../utils/qmd-native-binding-error.js';
 import { isQmdStoreMissingError, qmdStoreMissingMessage, } from '../utils/qmd-store-missing-error.js';
+import { isQmdStoreUnopenableError, qmdStoreUnopenableMessage, } from '../utils/qmd-store-unopenable-error.js';
 const defaults = {
     reconcileCollections,
     deriveCollections,
@@ -134,6 +135,18 @@ export function registerIndexCommand(program, dependencies = defaults) {
                 process.stderr.write(`qmd: unusable — ${remedy}\n`);
                 process.exitCode = 1;
             }
+            else if (isQmdStoreUnopenableError(error)) {
+                // The local qmd store directory exists but cannot be opened —
+                // typically not writable, so better-sqlite3 throws SQLITE_CANTOPEN
+                // (HQ-CLI-18). Like the store-missing case, this diagnostic command
+                // should DESCRIBE the broken local store, not crash on it (and never
+                // forward qmd's macOS-only Homebrew advisory): print the classified
+                // reason + remedy and exit 1 without rethrowing. Every OTHER qmd
+                // failure keeps propagating.
+                const remedy = qmdStoreUnopenableMessage(error) ?? 'its local search store could not be opened';
+                process.stderr.write(`qmd: unusable — ${remedy}\n`);
+                process.exitCode = 1;
+            }
             else {
                 throw error;
             }

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

@@ -175,6 +175,31 @@ export declare class QmdStoreMissingError extends QmdExitError {
     name: string;
     constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string, storeDir?: string | undefined, ensureReason?: string | undefined);
 }
+/**
+ * qmd could not OPEN its SQLite store even though the store's directory EXISTS.
+ * better-sqlite3 throws `SqliteError: unable to open database file`
+ * (SQLITE_CANTOPEN) — most often because the store directory is not writable, so
+ * WAL mode (`PRAGMA journal_mode = WAL`) cannot create its -wal/-shm sidecars.
+ * The DISJOINT other half of "hq's store could not be opened": {@link
+ * QmdStoreMissingError} is a directory that does not EXIST; this is a directory
+ * that exists but is not USABLE. Either way it is the caller's ENVIRONMENT —
+ * permissions on the cache/index directory or its files — never a bug HQ can fix
+ * in code.
+ *
+ * `storeDir` carries the directory hq resolved qmd would open its store in, and
+ * `probeReason` the bounded errno phrase from hq's own best-effort WRITABILITY
+ * probe of that directory (undefined when the probe passed or did not run — e.g.
+ * a read-only DB file inside a writable directory). Both are hq-DERIVED — the
+ * resolved path plus a finite errno reason — so the boundary can name them in an
+ * input-free remedy and NEVER re-emit qmd's macOS-only Homebrew/BREW_PREFIX
+ * advisory to a Linux terminal. HQ-CLI-18 (Sentry 7702459375).
+ */
+export declare class QmdStoreUnopenableError extends QmdExitError {
+    readonly storeDir?: string | undefined;
+    readonly probeReason?: string | undefined;
+    name: string;
+    constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string, storeDir?: string | undefined, probeReason?: string | undefined);
+}
 export type ResolveQmdBinOptions = {
     env?: Record<string, string | undefined>;
     isExecutable?: (candidate: string) => boolean;
@@ -231,12 +256,15 @@ export declare function resolveQmdVersion(): string | undefined;
  * directory so the mkdir happens at most once per distinct directory per process
  * (idempotent, bounded — a process opens a tiny, fixed set of store dirs). Read
  * by finishRunQmd to stamp the directory and the errno reason onto a
- * QmdStoreMissingError, turning the condition that carried no cause in the
- * reported event into a self-describing one.
+ * QmdStoreMissingError (mkdir failed) or a QmdStoreUnopenableError (mkdir
+ * succeeded but the writability probe failed), turning a condition that carried
+ * no cause in the reported event into a self-describing one. `writable` records
+ * the create+unlink probe result; `created` records whether the mkdir ran.
  */
 type QmdStoreEnsureOutcome = {
     dir: string;
     created: boolean;
+    writable: boolean;
     reason?: string;
 };
 /** Test-only: read the most recent store-directory ensure outcome. */
@@ -246,16 +274,32 @@ export declare function lastQmdStoreEnsureOutcome(): QmdStoreEnsureOutcome | und
  * pinned @tobilu/qmd@2.5.3 rule (dist/store.js getDefaultDbPath + dist/paths.js
  * qmdHomedir) against the SAME env the qmd child receives:
  *   - $INDEX_PATH set  -> dirname($INDEX_PATH) (qmd returns INDEX_PATH verbatim,
- *     so the store file's directory is the one that must exist);
+ *     so the store file's directory is the one that must exist). A RELATIVE
+ *     INDEX_PATH is resolved against `cwd` — the working directory the qmd child
+ *     will run in (index sync/status/background pass one) — because qmd opens
+ *     `new Database(INDEX_PATH)` relative to its own cwd, not the CLI process's;
  *   - else             -> ${XDG_CACHE_HOME || <home>/.cache}/qmd, where <home> is
  *     $HOME || $USERPROFILE || os.homedir() || '/tmp' (qmdHomedir's exact order).
  * An upstream-contract test pins this rule to the INSTALLED qmd so a bump that
  * changes it turns CI red instead of silently restoring the noise.
  */
-export declare function resolveQmdStoreDir(env?: NodeJS.ProcessEnv): string;
+export declare function resolveQmdStoreDir(env?: NodeJS.ProcessEnv, cwd?: string): string;
 export type EnsureQmdStoreDirOptions = {
+    /**
+     * The working directory the qmd child will run in, used to resolve a RELATIVE
+     * INDEX_PATH the same way qmd does. Defaults to `process.cwd()` (spawnSync's
+     * default when no cwd is given), so it only matters when a caller passes a cwd.
+     */
+    cwd?: string;
     /** mkdir seam (default `fs.mkdirSync(dir, { recursive: true })`); injected in tests. */
     mkdir?: (dir: string) => void;
+    /**
+     * Writability probe seam (default: create+unlink a uniquely-named temp file
+     * inside `dir`); injected in tests. MUST throw on failure. A create+unlink
+     * probe is used rather than `fs.accessSync(W_OK)` because access() reports
+     * writable for root and can disagree with open() under macOS TCC.
+     */
+    probeWritable?: (dir: string) => void;
 };
 /**
  * Best-effort, once-per-directory self-provisioning of qmd's store directory

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

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { isQmdModuleMissingError } from '../../utils/qmd-module-missing-error.js';
 import { isQmdNativeBindingError } from '../../utils/qmd-native-binding-error.js';
 import { isQmdStoreMissingError } from '../../utils/qmd-store-missing-error.js';
+import { isQmdStoreUnopenableError } from '../../utils/qmd-store-unopenable-error.js';
 import { redactErrorText } from '../../utils/redact-error-text.js';
 import { planCommandSpawn } from '../../utils/windows-spawn.js';
 const require = createRequire(import.meta.url);
@@ -159,6 +160,35 @@ export class QmdStoreMissingError extends QmdExitError {
         this.ensureReason = ensureReason;
     }
 }
+/**
+ * qmd could not OPEN its SQLite store even though the store's directory EXISTS.
+ * better-sqlite3 throws `SqliteError: unable to open database file`
+ * (SQLITE_CANTOPEN) — most often because the store directory is not writable, so
+ * WAL mode (`PRAGMA journal_mode = WAL`) cannot create its -wal/-shm sidecars.
+ * The DISJOINT other half of "hq's store could not be opened": {@link
+ * QmdStoreMissingError} is a directory that does not EXIST; this is a directory
+ * that exists but is not USABLE. Either way it is the caller's ENVIRONMENT —
+ * permissions on the cache/index directory or its files — never a bug HQ can fix
+ * in code.
+ *
+ * `storeDir` carries the directory hq resolved qmd would open its store in, and
+ * `probeReason` the bounded errno phrase from hq's own best-effort WRITABILITY
+ * probe of that directory (undefined when the probe passed or did not run — e.g.
+ * a read-only DB file inside a writable directory). Both are hq-DERIVED — the
+ * resolved path plus a finite errno reason — so the boundary can name them in an
+ * input-free remedy and NEVER re-emit qmd's macOS-only Homebrew/BREW_PREFIX
+ * advisory to a Linux terminal. HQ-CLI-18 (Sentry 7702459375).
+ */
+export class QmdStoreUnopenableError extends QmdExitError {
+    storeDir;
+    probeReason;
+    name = 'QmdStoreUnopenableError';
+    constructor(message, args, status, stdout, stderr, storeDir, probeReason) {
+        super(message, args, status, stdout, stderr);
+        this.storeDir = storeDir;
+        this.probeReason = probeReason;
+    }
+}
 function isExecutable(candidate) {
     try {
         fs.accessSync(candidate, fs.constants.X_OK);
@@ -305,16 +335,21 @@ export function lastQmdStoreEnsureOutcome() {
  * pinned @tobilu/qmd@2.5.3 rule (dist/store.js getDefaultDbPath + dist/paths.js
  * qmdHomedir) against the SAME env the qmd child receives:
  *   - $INDEX_PATH set  -> dirname($INDEX_PATH) (qmd returns INDEX_PATH verbatim,
- *     so the store file's directory is the one that must exist);
+ *     so the store file's directory is the one that must exist). A RELATIVE
+ *     INDEX_PATH is resolved against `cwd` — the working directory the qmd child
+ *     will run in (index sync/status/background pass one) — because qmd opens
+ *     `new Database(INDEX_PATH)` relative to its own cwd, not the CLI process's;
  *   - else             -> ${XDG_CACHE_HOME || <home>/.cache}/qmd, where <home> is
  *     $HOME || $USERPROFILE || os.homedir() || '/tmp' (qmdHomedir's exact order).
  * An upstream-contract test pins this rule to the INSTALLED qmd so a bump that
  * changes it turns CI red instead of silently restoring the noise.
  */
-export function resolveQmdStoreDir(env = process.env) {
+export function resolveQmdStoreDir(env = process.env, cwd = process.cwd()) {
     const indexPath = env.INDEX_PATH;
+    // path.resolve leaves an absolute INDEX_PATH untouched and anchors a relative
+    // one to the child cwd, so the probed/stamped directory is the one qmd uses.
     if (indexPath)
-        return path.dirname(indexPath);
+        return path.dirname(path.resolve(cwd, indexPath));
     const home = env.HOME || env.USERPROFILE || os.homedir() || '/tmp';
     const cacheDir = env.XDG_CACHE_HOME || path.join(home, '.cache');
     return path.join(cacheDir, 'qmd');
@@ -338,6 +373,23 @@ function ensureFailureReason(error) {
             return typeof code === 'string' && code.length > 0 ? code : 'an unknown error';
     }
 }
+/**
+ * Create AND unlink a uniquely-named temp file inside `dir` to prove qmd will be
+ * able to open (and, under WAL, create/delete the -wal/-shm sidecars in) its
+ * store. A recursive mkdir is a NO-OP on an existing directory, so a successful
+ * mkdir does NOT prove writability — this is what makes the store-unopenable
+ * remedy self-describing instead of evidence-free (HQ-CLI-18). BOTH the create
+ * and the unlink must succeed: a directory that allows creation but denies
+ * deletion cannot support WAL sidecar churn, so a failed unlink is a real
+ * writability failure (and swallowing it would also litter a probe file every
+ * process). Either failure throws so the caller records the bounded errno
+ * reason; on the happy path the probe file is always removed.
+ */
+function probeDirWritable(dir) {
+    const probe = path.join(dir, `.hq-write-probe-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fs.writeFileSync(probe, '');
+    fs.unlinkSync(probe);
+}
 /**
  * Best-effort, once-per-directory self-provisioning of qmd's store directory
  * BEFORE qmd is spawned, so the benign majority case — a pruned cache or a fresh
@@ -351,7 +403,7 @@ function ensureFailureReason(error) {
 export function ensureQmdStoreDir(env = process.env, options = {}) {
     let dir;
     try {
-        dir = resolveQmdStoreDir(env);
+        dir = resolveQmdStoreDir(env, options.cwd);
     }
     catch {
         // Resolution itself must never break a qmd run.
@@ -360,12 +412,23 @@ export function ensureQmdStoreDir(env = process.env, options = {}) {
     let outcome = storeEnsureByDir.get(dir);
     if (!outcome) {
         const mkdir = options.mkdir ?? ((target) => { fs.mkdirSync(target, { recursive: true }); });
+        const probeWritable = options.probeWritable ?? probeDirWritable;
         try {
             mkdir(dir);
-            outcome = { dir, created: true };
+            // mkdir(recursive) is a no-op on an EXISTING directory, so success does not
+            // prove qmd can open its store there. Probe real writability so an
+            // existing-but-unwritable store dir — the reported HQ-CLI-18 shape — is
+            // recorded with its errno reason rather than looking successful.
+            try {
+                probeWritable(dir);
+                outcome = { dir, created: true, writable: true };
+            }
+            catch (probeError) {
+                outcome = { dir, created: true, writable: false, reason: ensureFailureReason(probeError) };
+            }
         }
         catch (error) {
-            outcome = { dir, created: false, reason: ensureFailureReason(error) };
+            outcome = { dir, created: false, writable: false, reason: ensureFailureReason(error) };
         }
         storeEnsureByDir.set(dir, outcome);
     }
@@ -951,6 +1014,28 @@ function finishRunQmd(result, bin, args) {
         const ensure = lastQmdStoreEnsure;
         throw new QmdStoreMissingError(`qmd ${subcommand} could not run: its local search store could not be opened (its directory does not exist)`, args, normalized.status, normalized.stdout, normalized.stderr, ensure?.dir, ensure && !ensure.created ? ensure.reason : undefined);
     }
+    // qmd could not OPEN its SQLite store even though the directory EXISTS
+    // (better-sqlite3: `SqliteError: unable to open database file` /
+    // SQLITE_CANTOPEN — typically the store directory is not writable, so WAL mode
+    // cannot create its -wal/-shm sidecars). That is the caller's environment —
+    // permissions on the cache/index directory or its files — not an hq-cli
+    // defect. Type it so the boundary prints hq's OWN platform-correct remedy
+    // (naming the resolved store dir and the recorded writability-probe reason)
+    // and skips capture, INSTEAD of forwarding qmd's macOS-only Homebrew/BREW_PREFIX
+    // advisory verbatim to a Linux terminal (HQ-CLI-18, Sentry 7702459375). Read
+    // qmd's OWN captured streams only, never the synthesized message, so a user
+    // query containing that phrase can never trip it. Placed AFTER the
+    // store-MISSING check (its sentence is the DISJOINT `Cannot open database
+    // because the directory does not exist`, so it keeps priority for its own
+    // shape) and BEFORE the collection-missing regex (that regex needs
+    // `collection`/`qmd://` adjacent to a not-found token, which this stderr
+    // lacks), so no existing branch changes behaviour. The stamped
+    // storeDir/probeReason come from the pre-spawn ensure that ran for this exact
+    // store directory.
+    if (isQmdStoreUnopenableError({ stderr: normalized.stderr, stdout: normalized.stdout })) {
+        const ensure = lastQmdStoreEnsure;
+        throw new QmdStoreUnopenableError(`qmd ${subcommand} could not run: its local search store could not be opened`, args, normalized.status, normalized.stdout, normalized.stderr, ensure?.dir, ensure && !ensure.writable ? ensure.reason : undefined);
+    }
     if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(classifyText)) {
         throw new QmdCollectionMissingError(message, args, normalized.status, normalized.stdout, normalized.stderr);
     }
@@ -995,7 +1080,7 @@ export function runQmd(args, options = {}) {
     // classified with its cause instead of captured (HQ-CLI-16). Best-effort and
     // idempotent; only the real spawn path needs it (the injected-runner path
     // above never opens a store).
-    ensureQmdStoreDir(options.env ?? process.env);
+    ensureQmdStoreDir(options.env ?? process.env, { cwd: options.cwd });
     const result = spawnQmd(invocation, args, {
         cwd: options.cwd,
         env: options.env ?? process.env,

package/dist/main.js

@@ -72,6 +72,8 @@ import { qmdTerminatedMessage } from "./utils/qmd-terminated-error.js";
 import { qmdLlmDisabledMessage } from "./utils/qmd-llm-disabled-error.js";
 import { qmdModuleMissingMessage } from "./utils/qmd-module-missing-error.js";
 import { qmdStoreMissingMessage } from "./utils/qmd-store-missing-error.js";
+import { qmdStoreUnopenableMessage } from "./utils/qmd-store-unopenable-error.js";
+import { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
@@ -556,7 +558,33 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         const storeMissingMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg
             ? null
             : qmdStoreMissingMessage(err);
-        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg
+        // A qmd store-UNOPENABLE failure (better-sqlite3 `SqliteError: unable to
+        // open database file` / SQLITE_CANTOPEN: the store directory EXISTS but is
+        // not writable, so WAL sidecars cannot be created) is the caller's local
+        // filesystem/permissions, not an hq-cli defect. finishRunQmd types it
+        // QmdStoreUnopenableError, carrying the resolved store directory and the
+        // writability-probe errno reason; print that self-describing, PLATFORM-
+        // CORRECT remedy and skip capture, so qmd's macOS-only Homebrew/BREW_PREFIX
+        // advisory can NEVER reach a Linux terminal (HQ-CLI-18, Sentry 7702459375).
+        // Evaluated immediately AFTER the store-MISSING check (disjoint sentence, so
+        // it keeps priority for its own shape) and BEFORE the environmental /
+        // transport / generic branches.
+        const storeUnopenableMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg
+            ? null
+            : qmdStoreUnopenableMessage(err);
+        // An hq STATE-TREE write that failed for an environmental errno
+        // (permission/quota/read-only/parent-gone) is typed at the write site as an
+        // HqStateWriteError carrying the exact hq-DERIVED path it tried to write.
+        // The reported EPERM on the checkpoint stamp file (Node 26 dropped the path)
+        // otherwise reached the capture below and gave the user nothing to act on
+        // (HQ-CLI-19, Sentry 7702730566). Print the path-naming, platform-aware
+        // remedy and skip capture. Placed with the environmental-fs family — BEFORE
+        // the generic envMsg computation — so this typed carrier wins even though
+        // it also carries an errno `code` environmentalFsErrorMessage could read.
+        const stateWriteMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg
+            ? null
+            : hqStateWriteErrorMessage(err);
+        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || stateWriteMsg
             ? null
             : environmentalFsErrorMessage(err);
         // A LOCAL sync-state lock failure (@indigoai-us/hq-cloud's
@@ -573,7 +601,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // environmental-fs check, before network-transport — is pinned by tests.
         // The `in-process-async-holder` reason is deliberately NOT suppressed here
         // (see sync-state-lock-error.ts); it stays captured.
-        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || envMsg
+        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || stateWriteMsg || envMsg
             ? null
             : syncStateLockMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
@@ -592,6 +620,8 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             llmDisabledMsg ||
             moduleMissingMsg ||
             storeMissingMsg ||
+            storeUnopenableMsg ||
+            stateWriteMsg ||
             envMsg ||
             lockMsg
             ? null
@@ -614,6 +644,12 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (storeMissingMsg) {
             deps.stderr.write(`hq: ${storeMissingMsg}\n`);
         }
+        else if (storeUnopenableMsg) {
+            deps.stderr.write(`hq: ${storeUnopenableMsg}\n`);
+        }
+        else if (stateWriteMsg) {
+            deps.stderr.write(`hq: ${stateWriteMsg}\n`);
+        }
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }

package/dist/utils/cli-telemetry.js

@@ -33,6 +33,7 @@ async function emitCachedCliSessionStarted() {
                             app: "hq-cli",
                             source: "cli",
                             occurredAt: new Date().toISOString(),
+                            consentBasis: "no-consent",
                             schemaVersion: 1,
                             properties: { version: CLI_VERSION },
                         },

package/dist/utils/hq-state-write-error.d.ts

@@ -0,0 +1,41 @@
+/** Map an errno code to a bounded reason; anything outside the closed set to a fixed fallback. */
+export declare function stateWriteReason(code: unknown): string;
+/**
+ * A permission/filesystem write into HQ's OWN state tree that hq cannot fix in
+ * code. Carries the hq-DERIVED absolute `path` hq tried to write, the
+ * `operation` (a fixed label, never free text), the bounded errno `reason`, and
+ * the raw errno `code` — all of finite cardinality, so the printed line and any
+ * grouping stay bounded.
+ */
+export declare class HqStateWriteError extends Error {
+    readonly path: string;
+    readonly operation: string;
+    readonly reason: string;
+    readonly code: string;
+    name: string;
+    constructor(path: string, operation: string, reason: string, code: string);
+}
+/**
+ * If `error` is an ENVIRONMENTAL filesystem failure — its `.code` is one of the
+ * CLOSED set of permission/quota/read-only/parent-shape errnos above — convert
+ * it into an {@link HqStateWriteError} that NAMES `targetPath` (the hq-derived
+ * path the caller was writing) and the `operation` label; otherwise return
+ * `null` so the caller rethrows the original error UNCHANGED. Keeping the set
+ * closed is what makes "genuine faults stay reportable" hold: a NON-errno error
+ * (a code defect) and an UNUSUAL errno (e.g. `EISDIR`/`EEXIST`, which mean hq
+ * wrote to the wrong shape) both stay captured. Scoped by the CALLER to hq's own
+ * state paths, never applied as a blanket boundary rule.
+ */
+export declare function toHqStateWriteError(error: unknown, targetPath: string, operation: string): HqStateWriteError | null;
+/** True when `err` is an {@link HqStateWriteError} (structural, so a rehydrated shape matches). */
+export declare function isHqStateWriteError(err: unknown): err is HqStateWriteError;
+/**
+ * If `err` is an {@link HqStateWriteError}, return the actionable, path-naming
+ * remedy; otherwise return `null`. A non-null result means the caller should
+ * print the message and SKIP Sentry capture — the condition is the user's
+ * machine, not a bug HQ can fix. The wording is platform-aware from `platform`
+ * (injected in tests), never from any upstream text, and always names the exact
+ * hq-derived path because the runtime does not (Node 26 drops it).
+ */
+export declare function hqStateWriteErrorMessage(err: unknown, platform?: NodeJS.Platform): string | null;
+//# sourceMappingURL=hq-state-write-error.d.ts.map

package/dist/utils/hq-state-write-error.js

@@ -0,0 +1,113 @@
+// src/utils/hq-state-write-error.ts
+//
+// Type a filesystem write into HQ's OWN state tree that failed for an
+// ENVIRONMENTAL reason (a permission/quota/read-only/parent-gone errno) rather
+// than an hq-cli code defect. These are unactionable from our side — the file
+// or its directory is owned by another user, the terminal lacks Full Disk
+// Access on macOS, the mount is read-only — so the CLI surfaces an actionable
+// message and does NOT report them to Sentry.
+//
+// HQ-CLI-19 (Sentry indigo-d0/hq-cli 7702730566): `hq core checkpoint` wrote its
+// thread file fine, then `fs.writeFileSync` on the EXISTING checkpoint stamp
+// file threw `EPERM: operation not permitted, open` on macOS 26 / Node 26. The
+// raw error reached the boundary; environmentalFsErrorMessage maps only
+// ENOSPC/EDQUOT/EROFS (never EPERM/EACCES — see below), so it was captured. And
+// because Node 26's writeFileSync fast path carried NO `path` on the thrown
+// error, both the user and the issue got `EPERM: operation not permitted, open`
+// with nothing to act on.
+//
+// Why type this at the WRITE SITE instead of widening the boundary's errno
+// allowlist: EPERM/EACCES are AMBIGUOUS — "the user's machine" vs "hq wrote to
+// the wrong place". A blanket errno rule at the boundary would silently suppress
+// EVERY permission error CLI-wide, including a genuine hq path defect that must
+// stay reportable. Typing only the specific hq-DERIVED state paths this command
+// computes keeps the blast radius bounded, and because the remedy NAMES the
+// exact path hq tried to write (the runtime supplies none on Node 26), a
+// wrong-path defect is immediately visible to the user and to support even
+// though it is not captured.
+/** The bounded, human errno reason for a state-write failure (never free text). */
+const STATE_WRITE_REASONS = {
+    EACCES: "permission denied",
+    EPERM: "operation not permitted (permission denied)",
+    EROFS: "the filesystem is read-only",
+    ENOSPC: "no space left on device",
+    EDQUOT: "the disk quota is exhausted",
+    ENOTDIR: "a path component is not a directory",
+    ENOENT: "a parent path does not exist",
+};
+/** Map an errno code to a bounded reason; anything outside the closed set to a fixed fallback. */
+export function stateWriteReason(code) {
+    if (typeof code === "string" && code in STATE_WRITE_REASONS) {
+        return STATE_WRITE_REASONS[code];
+    }
+    return typeof code === "string" && code.length > 0 ? code : "a filesystem error";
+}
+/**
+ * A permission/filesystem write into HQ's OWN state tree that hq cannot fix in
+ * code. Carries the hq-DERIVED absolute `path` hq tried to write, the
+ * `operation` (a fixed label, never free text), the bounded errno `reason`, and
+ * the raw errno `code` — all of finite cardinality, so the printed line and any
+ * grouping stay bounded.
+ */
+export class HqStateWriteError extends Error {
+    path;
+    operation;
+    reason;
+    code;
+    name = "HqStateWriteError";
+    constructor(path, operation, reason, code) {
+        super(`hq could not ${operation} ${path}: ${reason}`);
+        this.path = path;
+        this.operation = operation;
+        this.reason = reason;
+        this.code = code;
+    }
+}
+/**
+ * If `error` is an ENVIRONMENTAL filesystem failure — its `.code` is one of the
+ * CLOSED set of permission/quota/read-only/parent-shape errnos above — convert
+ * it into an {@link HqStateWriteError} that NAMES `targetPath` (the hq-derived
+ * path the caller was writing) and the `operation` label; otherwise return
+ * `null` so the caller rethrows the original error UNCHANGED. Keeping the set
+ * closed is what makes "genuine faults stay reportable" hold: a NON-errno error
+ * (a code defect) and an UNUSUAL errno (e.g. `EISDIR`/`EEXIST`, which mean hq
+ * wrote to the wrong shape) both stay captured. Scoped by the CALLER to hq's own
+ * state paths, never applied as a blanket boundary rule.
+ */
+export function toHqStateWriteError(error, targetPath, operation) {
+    const code = error?.code;
+    if (typeof code !== "string" || !(code in STATE_WRITE_REASONS))
+        return null;
+    return new HqStateWriteError(targetPath, operation, STATE_WRITE_REASONS[code], code);
+}
+/** True when `err` is an {@link HqStateWriteError} (structural, so a rehydrated shape matches). */
+export function isHqStateWriteError(err) {
+    if (err instanceof HqStateWriteError)
+        return true;
+    return (err !== null &&
+        typeof err === "object" &&
+        err.name === "HqStateWriteError" &&
+        typeof err.path === "string");
+}
+/**
+ * If `err` is an {@link HqStateWriteError}, return the actionable, path-naming
+ * remedy; otherwise return `null`. A non-null result means the caller should
+ * print the message and SKIP Sentry capture — the condition is the user's
+ * machine, not a bug HQ can fix. The wording is platform-aware from `platform`
+ * (injected in tests), never from any upstream text, and always names the exact
+ * hq-derived path because the runtime does not (Node 26 drops it).
+ */
+export function hqStateWriteErrorMessage(err, platform = process.platform) {
+    if (!isHqStateWriteError(err))
+        return null;
+    const base = `hq could not ${err.operation} ${err.path}: ${err.reason}. ` +
+        "This is your machine's filesystem, not an hq bug: check that this file and its " +
+        "directory exist and are owned by you and writable";
+    const platformTail = platform === "darwin"
+        ? ", and on macOS grant your terminal Full Disk Access (System Settings → " +
+            "Privacy & Security → Full Disk Access) or move your HQ root out of a protected " +
+            "location, then run your command again."
+        : ", then run your command again.";
+    return `${base}${platformTail}`;
+}
+//# sourceMappingURL=hq-state-write-error.js.map

package/dist/utils/qmd-store-unopenable-error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * True when `err` is a qmd store-unopenable failure: better-sqlite3's fixed
+ * sentence (or the SQLITE_CANTOPEN errno token) appears in qmd's captured
+ * STDERR. Accepts either the thrown error (reads its `stderr`) or a bare
+ * `{ stderr }` probe object. A true result means the caller should print the
+ * classified remedy, exit non-zero, and SKIP Sentry capture.
+ */
+export declare function isQmdStoreUnopenableError(err: unknown): boolean;
+/**
+ * If `err` is a qmd store-unopenable failure, return the actionable remedy;
+ * otherwise return `null`. Mirrors qmdStoreMissingMessage so the top-level
+ * handler can branch on it the same way: a non-null result means
+ * print-and-skip-Sentry, null means "handle as usual (capture to Sentry)". The
+ * store directory and errno reason are read STRUCTURALLY from the error's own
+ * hq-populated `storeDir`/`probeReason` fields (absent on a bare probe object —
+ * then the message names neither), NEVER from qmd's output.
+ */
+export declare function qmdStoreUnopenableMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-store-unopenable-error.d.ts.map

package/dist/utils/qmd-store-unopenable-error.js

@@ -0,0 +1,99 @@
+// src/utils/qmd-store-unopenable-error.ts
+//
+// Classify a qmd failure caused by an UNOPENABLE STORE — the SQLite store's
+// directory EXISTS but qmd cannot open the database (better-sqlite3 throws
+// `SqliteError: unable to open database file` / SQLITE_CANTOPEN, most often
+// because the store directory is not writable, so WAL mode cannot create its
+// -wal/-shm sidecars). This is the caller's LOCAL filesystem/permissions, not
+// an hq-cli code defect, so the CLI surfaces an actionable remedy and SKIPS
+// Sentry capture. Sibling of qmd-store-missing-error.ts (HQ-CLI-16, a store
+// directory that does not exist) — the DISJOINT other half of "hq's store
+// could not be opened".
+//
+// HQ-CLI-18 (Sentry indigo-d0/hq-cli 7702459375): `hq search …` spawned qmd,
+// whose better-sqlite3 could not open the store (SQLITE_CANTOPEN). @tobilu/qmd
+// FIRST console.warn's a macOS-only remedy built by createSqliteVecUnavailableError
+// ("… Install Homebrew SQLite … set BREW_PREFIX …") for ANY probe failure, then
+// throws the uncaught SqliteError from `PRAGMA journal_mode = WAL`. hq-cli's
+// classifier chain missed this shape (store-missing keys on the DISJOINT
+// sentence `Cannot open database because the directory does not exist`), so it
+// stayed a plain QmdExitError, reached the boundary's final else, was captured,
+// and — the visible harm — forwarded qmd's Homebrew/BREW_PREFIX advisory
+// VERBATIM to a Linux terminal. Typing the condition lets the boundary print
+// hq's OWN platform-correct, input-free remedy and never echo upstream text,
+// exactly as qmdTerminatedMessage already does for qmd's raw advisory stderr.
+//
+// Matching is deliberately narrow so it can neither be tripped by user input nor
+// silence a real bug: better-sqlite3's FIXED sentence / SQLite's fixed errno
+// token is required in qmd's captured STDERR ONLY — never the synthesized
+// `message` (which echoes the caller's argv) and never STDOUT. better-sqlite3's
+// uncaught SqliteError and qmd's advisory both land on stderr; STDOUT for a
+// `search`/`get` carries indexed DOCUMENT content, so keying on it would let a
+// result body that merely contains the phrase suppress an UNRELATED nonzero
+// exit. Every other qmd store failure (a locked db, a corrupt store, an unknown
+// exit) matches none of this and stays a reportable QmdExitError.
+/**
+ * better-sqlite3's fixed "cannot open" sentence and SQLite's fixed errno token.
+ * Either, on its own, is sufficient. Both were present in the reported event and
+ * in the local SQLITE_CANTOPEN reproduction.
+ */
+const STORE_UNOPENABLE = /SqliteError:\s*unable to open database file|\bSQLITE_CANTOPEN\b/i;
+/**
+ * qmd's captured STDERR only. STDOUT is deliberately NOT consulted: for a
+ * `search`/`get` it is untrusted document content, so a result body containing
+ * this signature must never classify. The synthesized `message` is likewise not
+ * consulted — it embeds the caller's qmd arguments.
+ */
+function capturedStderr(err) {
+    if (err === null || typeof err !== "object")
+        return "";
+    const record = err;
+    return typeof record.stderr === "string" ? record.stderr : "";
+}
+/**
+ * True when `err` is a qmd store-unopenable failure: better-sqlite3's fixed
+ * sentence (or the SQLITE_CANTOPEN errno token) appears in qmd's captured
+ * STDERR. Accepts either the thrown error (reads its `stderr`) or a bare
+ * `{ stderr }` probe object. A true result means the caller should print the
+ * classified remedy, exit non-zero, and SKIP Sentry capture.
+ */
+export function isQmdStoreUnopenableError(err) {
+    return STORE_UNOPENABLE.test(capturedStderr(err));
+}
+/**
+ * The actionable, PLATFORM-NEUTRAL remedy, naming the store directory qmd could
+ * not open and (when the store-directory ensure recorded one) the errno reason
+ * its writability probe failed with. Both are hq-DERIVED values — the resolved
+ * store path and a bounded errno phrase — never caller argv/query or upstream
+ * text, so the line stays input-free and can NEVER re-emit qmd's macOS-only
+ * Homebrew/BREW_PREFIX advisory to a Linux terminal.
+ */
+function remedyMessage(storeDir, probeReason) {
+    const where = storeDir
+        ? `hq's local search store (${storeDir}) could not be opened`
+        : "hq's local search store could not be opened";
+    const because = probeReason ? ` — ${probeReason}.` : ".";
+    return (`${where}${because} This is your machine's filesystem, not an hq bug: check that ` +
+        "the store directory and its database files are owned by you and writable (or " +
+        "point INDEX_PATH at a writable location), then run your command again.");
+}
+/**
+ * If `err` is a qmd store-unopenable failure, return the actionable remedy;
+ * otherwise return `null`. Mirrors qmdStoreMissingMessage so the top-level
+ * handler can branch on it the same way: a non-null result means
+ * print-and-skip-Sentry, null means "handle as usual (capture to Sentry)". The
+ * store directory and errno reason are read STRUCTURALLY from the error's own
+ * hq-populated `storeDir`/`probeReason` fields (absent on a bare probe object —
+ * then the message names neither), NEVER from qmd's output.
+ */
+export function qmdStoreUnopenableMessage(err) {
+    if (!isQmdStoreUnopenableError(err))
+        return null;
+    const record = err;
+    const storeDir = typeof record.storeDir === "string" && record.storeDir.length > 0 ? record.storeDir : null;
+    const probeReason = typeof record.probeReason === "string" && record.probeReason.length > 0
+        ? record.probeReason
+        : null;
+    return remedyMessage(storeDir, probeReason);
+}
+//# sourceMappingURL=qmd-store-unopenable-error.js.map

package/dist/utils/self-update.js

@@ -60,7 +60,7 @@ import { spawnSync } from "node:child_process";
 import semver from "semver";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, inOwnProcessGroup, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, inOwnProcessGroup, isLocalDependencyInstall, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
@@ -222,11 +222,20 @@ async function updateAndReexec(argv, flavor, known, deps) {
     if (!interactive && flavor.onlyWhenAttended) {
         return { action: "deferred", latest };
     }
+    // A local copy (a project dependency, a `pnpm dlx` cache) has no self-update
+    // path: every install argv here targets a GLOBAL install, so the copy that is
+    // actually running would stay exactly as stale as it started while the CLI
+    // reported success and re-exec'd into the same build. That is the shape of
+    // the 2026-09-02 gate loop — see isLocalDependencyInstall in version-gate.ts.
+    const install = (deps.resolveInstall ?? resolveRunningInstall)();
+    if (isLocalDependencyInstall(install)) {
+        console.error(chalk.dim(`hq-cli ${latest} is available, but this copy is a local dependency (${install.packageRoot}) — update the project that owns it.`));
+        return { action: "skipped", latest };
+    }
     const releaseLock = flavor.lock ? (deps.acquireLock ?? acquireUpdateLock)() : () => { };
     if (!releaseLock)
         return { action: "skipped", latest };
     let result;
-    const install = (deps.resolveInstall ?? resolveRunningInstall)();
     const plan = buildSelfUpdatePlan(install);
     // A pnpm global install needs PNPM_HOME to find its global bin dir. A
     // minimal-environment parent (systemd, cron, non-login shell) lacks it and

package/dist/utils/sentry-fingerprint.js

@@ -83,6 +83,7 @@ const KNOWN_ERROR_NAMES = new Set([
     "QmdLlmDisabledError",
     "QmdModuleMissingError",
     "QmdStoreMissingError",
+    "QmdStoreUnopenableError",
 ]);
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";

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

@@ -70,6 +70,59 @@ export declare function npmPrefixFromPackageDir(pkgDir: string): string | null;
 export declare function isPnpmManagedPackageDir(pkgDir: string): boolean;
 /** Whether the running package lives inside Bun's global install tree. */
 export declare function isBunManagedPackageDir(pkgDir: string): boolean;
+/**
+ * Whether the package dir sits inside a pnpm **virtual store** — the adjacent
+ * `node_modules/.pnpm` segment pair pnpm creates for every install, global or
+ * not:
+ *
+ *   <proj>/node_modules/.pnpm/@indigoai-us+hq-cli@5.69.0/node_modules/@indigoai-us/hq-cli
+ *
+ * A virtual store is a content-addressed cache keyed by the EXACT version in
+ * the directory name. Nothing on PATH ever resolves through
+ * `<store>/lib/node_modules`, and the store dir is not an npm prefix — so the
+ * one thing that must never happen is treating it as one.
+ *
+ * Note this is deliberately broader than {@link isPnpmManagedPackageDir}, which
+ * answers a different question ("is this the copy `pnpm add -g` updates?") and
+ * is checked FIRST by {@link resolveRunningInstall}. By the time this predicate
+ * decides anything, a pnpm *global* store has already been classified.
+ */
+export declare function isPnpmVirtualStorePackageDir(pkgDir: string): boolean;
+/**
+ * Whether the running CLI is a **local** copy — a project dependency or a
+ * `pnpm dlx` cache — rather than a global install this process may replace.
+ *
+ * This is the guard for HQ-CLI update-loop incident 2026-09-02. A stale
+ * `@indigoai-us/hq-cli@5.69.0` sat in an HQ tree's pnpm virtual store, and the
+ * sync runner (npx, which puts `<cwd>/node_modules/.bin` on PATH) kept invoking
+ * it. The gate saw a build below `minVersion`, derived an npm prefix from the
+ * store path, ran
+ *
+ *   npm install -g --prefix <store> @indigoai-us/hq-cli@latest
+ *
+ * which unpacked a pristine copy into `<store>/lib/node_modules` — a directory
+ * pnpm's shim never reads — then reported success. The next invocation resolved
+ * the same 5.69.0 shim and did it all again, ~25 times an hour forever.
+ *
+ * A local copy has no self-update path at all: replacing it is its owning
+ * project's job, and installing globally would leave the copy that is actually
+ * running untouched. So the gate must say so and stop, not install.
+ */
+export declare function isLocalDependencyPackageDir(pkgDir: string, platform?: NodeJS.Platform): boolean;
+export declare function isLocalDependencyInstall(install: RunningInstall, platform?: NodeJS.Platform): boolean;
+/**
+ * Whether an update to `target` would actually move the install forward.
+ *
+ * Loop protection, independent of the layout bug above: an "update" to a
+ * version that is not strictly newer than what is running can never converge,
+ * so however the target was resolved — a stale dist-tag, a bad cache, a
+ * misconfigured hq-pro pin — the gate must refuse it rather than reinstall on
+ * every invocation and announce success each time.
+ *
+ * Unparseable versions return true: this guard exists to stop a provable
+ * no-op, not to become a new way for the gate to refuse to work.
+ */
+export declare function isNewerVersion(target: string, current: string): boolean;
 /**
  * Where the running CLI is installed and who owns it. Resolved in ONE pass so
  * the package-root walk (which reads and parses a `package.json` per directory
@@ -278,7 +331,7 @@ export declare function probeCliVersion(bin: string): string | null;
 export declare function checkUpdateConvergence(targetVersion: string, deps?: {
     resolveBin?: () => string | null;
     probeVersion?: (bin: string) => string | null;
-}): void;
+}): boolean;
 /** Injectable surface for {@link enforceUpdateRequired} (unit tests). */
 interface EnforceUpdateDeps {
     performUpdateString?: (command: string) => UpdateResult;
@@ -286,7 +339,12 @@ interface EnforceUpdateDeps {
     runner?: UpdateRunner;
     cleanStale?: (prefix: string) => string[];
     acquireLock?: () => UpdateLockHandle | null;
-    checkConvergence?: (targetVersion: string) => void;
+    /**
+     * `false` means the probe *disproved* convergence. `void`/`undefined` keeps
+     * the historical "unverified is fine" behaviour, so an injected stub that
+     * returns nothing still exercises the success path.
+     */
+    checkConvergence?: (targetVersion: string) => boolean | void;
 }
 /**
  * Hard enforcement when the server says we're below `minVersion`. Print a
@@ -346,7 +404,11 @@ export declare const __test__: {
     enforceUpdateRequired: typeof enforceUpdateRequired;
     isBunManagedPackageDir: typeof isBunManagedPackageDir;
     pnpmUpdateEnv: typeof pnpmUpdateEnv;
+    isLocalDependencyInstall: typeof isLocalDependencyInstall;
+    isLocalDependencyPackageDir: typeof isLocalDependencyPackageDir;
+    isNewerVersion: typeof isNewerVersion;
     isPnpmManagedPackageDir: typeof isPnpmManagedPackageDir;
+    isPnpmVirtualStorePackageDir: typeof isPnpmVirtualStorePackageDir;
     npmPrefixFromPackageDir: typeof npmPrefixFromPackageDir;
     nudgeUpdateRecommended: typeof nudgeUpdateRecommended;
     performUpdate: typeof performUpdate;

package/dist/utils/version-gate.js

@@ -34,6 +34,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
+import semver from "semver";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
 import { acquireUpdateLock, } from "./update-lock.js";
@@ -140,6 +141,106 @@ export function isBunManagedPackageDir(pkgDir) {
     }
     return false;
 }
+/**
+ * Whether the package dir sits inside a pnpm **virtual store** — the adjacent
+ * `node_modules/.pnpm` segment pair pnpm creates for every install, global or
+ * not:
+ *
+ *   <proj>/node_modules/.pnpm/@indigoai-us+hq-cli@5.69.0/node_modules/@indigoai-us/hq-cli
+ *
+ * A virtual store is a content-addressed cache keyed by the EXACT version in
+ * the directory name. Nothing on PATH ever resolves through
+ * `<store>/lib/node_modules`, and the store dir is not an npm prefix — so the
+ * one thing that must never happen is treating it as one.
+ *
+ * Note this is deliberately broader than {@link isPnpmManagedPackageDir}, which
+ * answers a different question ("is this the copy `pnpm add -g` updates?") and
+ * is checked FIRST by {@link resolveRunningInstall}. By the time this predicate
+ * decides anything, a pnpm *global* store has already been classified.
+ */
+export function isPnpmVirtualStorePackageDir(pkgDir) {
+    const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    const segments = normalized.split("/").filter(Boolean);
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        if (segments[i] === "node_modules" && segments[i + 1] === ".pnpm")
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether the running CLI is a **local** copy — a project dependency or a
+ * `pnpm dlx` cache — rather than a global install this process may replace.
+ *
+ * This is the guard for HQ-CLI update-loop incident 2026-09-02. A stale
+ * `@indigoai-us/hq-cli@5.69.0` sat in an HQ tree's pnpm virtual store, and the
+ * sync runner (npx, which puts `<cwd>/node_modules/.bin` on PATH) kept invoking
+ * it. The gate saw a build below `minVersion`, derived an npm prefix from the
+ * store path, ran
+ *
+ *   npm install -g --prefix <store> @indigoai-us/hq-cli@latest
+ *
+ * which unpacked a pristine copy into `<store>/lib/node_modules` — a directory
+ * pnpm's shim never reads — then reported success. The next invocation resolved
+ * the same 5.69.0 shim and did it all again, ~25 times an hour forever.
+ *
+ * A local copy has no self-update path at all: replacing it is its owning
+ * project's job, and installing globally would leave the copy that is actually
+ * running untouched. So the gate must say so and stop, not install.
+ */
+export function isLocalDependencyPackageDir(pkgDir, platform = process.platform) {
+    // A pnpm virtual store is local by construction on every platform. (A pnpm
+    // *global* store is classified earlier, by isPnpmManagedPackageDir.)
+    if (isPnpmVirtualStorePackageDir(pkgDir))
+        return true;
+    // On every non-Windows platform npm's global root is ALWAYS
+    // `<prefix>/lib/node_modules` — that is what `npm root -g` reports for
+    // /usr/local, Homebrew, nvm and a user-level `--prefix` alike. So a package
+    // under a `node_modules` with no `lib` parent is not a global install: it is
+    // a project dependency (`<proj>/node_modules/@scope/pkg`) or an npx cache
+    // (`~/.npm/_npx/<hash>/node_modules/@scope/pkg`). Both reproduce the same
+    // loop as the pnpm store — `npm install -g --prefix <dir>` writes
+    // `<dir>/lib/node_modules` while the `.bin` shim keeps resolving
+    // `<dir>/node_modules`.
+    //
+    // Windows is the exception and must keep the old behaviour: its global
+    // layout is `<prefix>\node_modules` with no `lib` segment, so the same test
+    // would misread a genuine global install as local.
+    if (platform === "win32")
+        return false;
+    const segments = pkgDir
+        .replace(/\\/g, "/")
+        .replace(/\/+$/, "")
+        .split("/")
+        .filter(Boolean);
+    const nodeModulesIndex = segments.lastIndexOf("node_modules");
+    if (nodeModulesIndex <= 0)
+        return false;
+    return segments[nodeModulesIndex - 1] !== "lib";
+}
+export function isLocalDependencyInstall(install, platform = process.platform) {
+    return (install.manager === "npm" &&
+        install.packageRoot !== null &&
+        isLocalDependencyPackageDir(install.packageRoot, platform));
+}
+/**
+ * Whether an update to `target` would actually move the install forward.
+ *
+ * Loop protection, independent of the layout bug above: an "update" to a
+ * version that is not strictly newer than what is running can never converge,
+ * so however the target was resolved — a stale dist-tag, a bad cache, a
+ * misconfigured hq-pro pin — the gate must refuse it rather than reinstall on
+ * every invocation and announce success each time.
+ *
+ * Unparseable versions return true: this guard exists to stop a provable
+ * no-op, not to become a new way for the gate to refuse to work.
+ */
+export function isNewerVersion(target, current) {
+    const t = semver.valid(target);
+    const c = semver.valid(current);
+    if (!t || !c)
+        return true;
+    return semver.gt(t, c);
+}
 export function resolveRunningInstall() {
     try {
         const packageRoot = findRunningPackageRoot();
@@ -151,6 +252,13 @@ export function resolveRunningInstall() {
         if (isBunManagedPackageDir(packageRoot)) {
             return { manager: "bun", prefix: null, packageRoot };
         }
+        // A local copy — project dependency, pnpm virtual store, or npx cache.
+        // `npmPrefixFromPackageDir` would hand back the project/cache directory and
+        // `npm install -g --prefix <dir>` then writes where nothing loads from —
+        // see isLocalDependencyPackageDir. There is no npm prefix to report here.
+        if (isLocalDependencyPackageDir(packageRoot)) {
+            return { manager: "npm", prefix: null, packageRoot };
+        }
         return {
             manager: "npm",
             prefix: npmPrefixFromPackageDir(packageRoot),
@@ -506,6 +614,14 @@ function manualUpdateCommand(install, decision) {
 function nudgeUpdateRecommended(decision, install = resolveRunningInstall()) {
     const msg = chalk.yellow(`⚠ A new version of hq-cli is available: ${decision.latestVersion} (current: ${decision.currentVersion}).`);
     console.error(msg);
+    // A local copy is not updated by any global command. Printing the server's
+    // npm-shaped one would send the user to install a second copy that this
+    // invocation still would not use — the same wrong advice the pnpm-global
+    // carve-out exists to avoid.
+    if (isLocalDependencyInstall(install)) {
+        console.error(chalk.dim(`  This copy is a local dependency (${install.packageRoot}); update the project that owns it, or invoke the global \`hq\`.`));
+        return;
+    }
     const command = install.manager === "pnpm"
         ? `pnpm ${buildPnpmInstallArgv().join(" ")}`
         : install.manager === "bun"
@@ -584,21 +700,41 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
         const bin = (deps.resolveBin ?? resolveHqOnPath)();
         if (!bin) {
             console.error(chalk.yellow("⚠ Updated, but couldn't resolve `hq` on PATH to verify the new version took effect."));
-            return;
+            // Unverifiable, not disproven — the caller keeps its success report.
+            return true;
         }
         const reported = (deps.probeVersion ?? probeCliVersion)(bin);
         if (!reported) {
             console.error(chalk.yellow(`⚠ Updated, but \`${bin} --version\` did not respond — couldn't verify the new version took effect.`));
-            return;
+            return true; // unverifiable, see above
         }
         if (reported === targetVersion)
-            return; // converged — the normal case
+            return true; // converged — the normal case
         console.error(chalk.yellow(`⚠ hq updated to ${targetVersion} but PATH still resolves ${bin} at version ${reported} — ` +
             `a second install is shadowing the managed one. Remove it (e.g. \`pnpm remove -g ${CLI_NAME}\`) ` +
             "or the updater will loop forever."));
+        // The warning above fires for ANY mismatch — something other than the copy
+        // we just wrote is winning PATH resolution, which is worth saying either
+        // way. But only a STALE result disproves convergence.
+        //
+        // The install runs `@latest`, not `@<targetVersion>`, so it can legitimately
+        // land a version NEWER than the `latestVersion` the gate was handed: the npm
+        // dist-tag moves between the version-check response and the install, or the
+        // service's value was briefly behind. That is a successful upgrade. Failing
+        // it would exit 75 and reinstall on the next invocation — the very loop this
+        // guard exists to stop.
+        const reportedSemver = semver.valid(reported);
+        const targetSemver = semver.valid(targetVersion);
+        if (reportedSemver &&
+            targetSemver &&
+            semver.gte(reportedSemver, targetSemver)) {
+            return true;
+        }
+        return false;
     }
     catch {
         // Verification is best-effort; never break the CLI over a probe.
+        return true;
     }
 }
 /**
@@ -629,6 +765,26 @@ function enforceUpdateRequired(decision, deps = {}) {
     // `resolveRunningInstall`
     // already reports `prefix: null` there and neither is consulted below.
     const install = (deps.resolveInstall ?? resolveRunningInstall)();
+    // Loop protection #1 — nothing here can update a copy this process does not
+    // own. Installing globally would leave the local copy that is actually
+    // running stale, so the gate would fire again on the very next invocation.
+    // Say what to fix and stop; do NOT spend an install.
+    if (isLocalDependencyInstall(install)) {
+        console.error(chalk.red(`  This copy is a local dependency, not a global install: ${install.packageRoot}`));
+        console.error(chalk.dim("  Self-update cannot replace it — an install would land where this copy is never loaded from, and the gate would fire again on the next run."));
+        console.error(chalk.dim(`  Update the project that owns it (e.g. \`pnpm update ${CLI_NAME}\` in its root, or remove the stale dependency), or invoke the global \`hq\` instead.`));
+        process.exit(75);
+    }
+    // Loop protection #2 — an "update" to a version that is not strictly newer
+    // than what is running can never converge. Whatever produced the target (a
+    // stale dist-tag, a bad cache, a misconfigured pin), reinstalling it on every
+    // invocation and announcing success each time is strictly worse than saying
+    // so once.
+    if (!isNewerVersion(decision.latestVersion, decision.currentVersion)) {
+        console.error(chalk.red(`  Refusing to update: the offered version ${decision.latestVersion} is not newer than the installed ${decision.currentVersion}.`));
+        console.error(chalk.dim("  This is a server-side or registry problem, not a local one — reinstalling would loop without ever converging."));
+        process.exit(75);
+    }
     const isManagedOutsideNpm = install.manager !== "npm";
     const prefix = install.prefix;
     if (!isManagedOutsideNpm && !command && !prefix) {
@@ -768,11 +924,17 @@ function attemptRequiredUpdate(decision, deps, install) {
         }
         return 75;
     }
-    console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
     // Read-your-writes: a "successful" install into the npm prefix does not
-    // prove the user's PATH resolves it. Warn (once, no retry) when a ghost
-    // install is shadowing the copy we just wrote — see checkUpdateConvergence.
-    (deps.checkConvergence ?? checkUpdateConvergence)(decision.latestVersion);
+    // prove the user's PATH resolves it. Verify BEFORE announcing, so a ghost
+    // install shadowing the copy we just wrote is reported as the failed update
+    // it is rather than as a success the caller will keep retrying — see
+    // checkUpdateConvergence.
+    const converged = (deps.checkConvergence ?? checkUpdateConvergence)(decision.latestVersion);
+    if (converged === false) {
+        console.error(chalk.red(`✗ Update did not take effect: \`hq\` on PATH still resolves a different build than ${decision.latestVersion}.`));
+        return 75;
+    }
+    console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
     return 0;
 }
 export async function enforceVersionGate(onUpdateRecommended) {
@@ -829,7 +991,11 @@ export const __test__ = {
     enforceUpdateRequired,
     isBunManagedPackageDir,
     pnpmUpdateEnv,
+    isLocalDependencyInstall,
+    isLocalDependencyPackageDir,
+    isNewerVersion,
     isPnpmManagedPackageDir,
+    isPnpmVirtualStorePackageDir,
     npmPrefixFromPackageDir,
     nudgeUpdateRecommended,
     performUpdate,

package/package.json

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