@indigoai-us/hq-cli 5.103.32 → 5.103.34

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.103.34] — 2026-08-30
+
+## [5.103.33] — 2026-08-30
+
 ## [5.103.32] — 2026-08-29
 
 ## [5.103.31] — 2026-08-29

package/dist/commands/auth.js

@@ -17,6 +17,7 @@ import chalk from "chalk";
 import { browserLogin, clearCachedTokens, loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_COGNITO, refreshCachedSession, } from "../utils/cognito-session.js";
 import { cognitoConfigForLoginProvider } from "../utils/login-provider.js";
+import { callbackPortBusyGuidance, DEFAULT_CALLBACK_PORT, isCallbackPortBusy, } from "../utils/callback-port-busy.js";
 /**
  * Decode the (unverified) ID token payload for display purposes only.
  * The token was just returned by Cognito's token endpoint, so its contents
@@ -46,17 +47,6 @@ function machineIdentityLabel() {
     const creds = loadMachineCreds();
     return creds ? `machine identity ${creds.username}` : "machine identity";
 }
-function isCallbackPortCollision(error) {
-    if (!error || typeof error !== "object")
-        return false;
-    const { code, message } = error;
-    return code === "EADDRINUSE" || message?.includes("EADDRINUSE") === true;
-}
-function callbackPortCollisionGuidance(port) {
-    return (`  The browser-login callback port (127.0.0.1:${port}) is already in use. ` +
-        "Another `hq auth login` may still be waiting for browser sign-in. Finish that login, " +
-        "or stop its terminal/process, then retry.");
-}
 export function registerAuthCommands(program) {
     const authCmd = program
         .command("auth")
@@ -83,7 +73,7 @@ export function registerAuthCommands(program) {
             console.log(chalk.dim(`  Token cached at ~/.hq/cognito-tokens.json (expires ${tokens.expiresAt})`));
         }
         catch (err) {
-            const callbackPortCollision = isCallbackPortCollision(err);
+            const callbackPortCollision = isCallbackPortBusy(err);
             const msg = callbackPortCollision
                 ? "Browser-login callback port is already in use."
                 : err instanceof CognitoAuthError
@@ -93,7 +83,7 @@ export function registerAuthCommands(program) {
                         : String(err);
             console.error(chalk.red(`Login failed: ${msg}`));
             if (callbackPortCollision) {
-                console.error(chalk.dim(callbackPortCollisionGuidance(DEFAULT_COGNITO.port ?? 8765)));
+                console.error(chalk.dim(`  ${callbackPortBusyGuidance(DEFAULT_COGNITO.port ?? DEFAULT_CALLBACK_PORT)}`));
             }
             else {
                 console.error(chalk.dim("  If you do not have an account, sign up at https://onboarding.hq.computer"));

package/dist/commands/index-cmd.js

@@ -3,6 +3,7 @@ import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcil
 import { backgroundStatus, defaultBackgroundDependencies, runBackgroundLauncher, runBackgroundWorker, } from '../lib/search-index/background.js';
 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';
 const defaults = {
     reconcileCollections,
     deriveCollections,
@@ -119,10 +120,23 @@ export function registerIndexCommand(program, dependencies = defaults) {
             qmdStatus = dependencies.runQmd(['status'], { cwd: hqRoot });
         }
         catch (error) {
-            if (!isQmdNativeBindingError(error))
+            if (isQmdNativeBindingError(error)) {
+                process.stderr.write(`qmd: unusable — native bindings unbuilt. ${QMD_NATIVE_BINDING_REMEDY}\n`);
+                process.exitCode = 1;
+            }
+            else if (isQmdStoreMissingError(error)) {
+                // The local qmd store directory does not exist (HQ-CLI-16). Like the
+                // native-binding case, this diagnostic command should DESCRIBE the
+                // broken local store, not crash on it: print the classified reason +
+                // remedy and exit 1 without rethrowing, so the boundary never files it
+                // as a Sentry crash. Every OTHER qmd failure keeps propagating.
+                const remedy = qmdStoreMissingMessage(error) ?? 'its local search store directory does not exist';
+                process.stderr.write(`qmd: unusable — ${remedy}\n`);
+                process.exitCode = 1;
+            }
+            else {
                 throw error;
-            process.stderr.write(`qmd: unusable — native bindings unbuilt. ${QMD_NATIVE_BINDING_REMEDY}\n`);
-            process.exitCode = 1;
+            }
         }
         if (registered) {
             console.log(collectionSummary(expected, registered));

package/dist/commands/skill.js

@@ -136,11 +136,17 @@ export function resolveSkillUid(target, cwd) {
     return uid;
 }
 export function canonicalCompanySkillPath(hqRoot, companySlug, skillSlug) {
+    // HQ-CLI-17 (Sentry 7699881899): both validators reject CALLER-supplied input
+    // — the `--company` slug and the `create <slug>` argument. A malformed value is
+    // the caller's request, not an hq-cli defect, so throw `localSkillError`
+    // (expected: true) and let the top-level boundary print the remedy and skip
+    // Sentry, exactly as the sibling caller-input throws in this module already do.
+    // The message text is unchanged; only its CLASS changes.
     if (!COMPANY_SLUG_PATTERN.test(companySlug)) {
-        throw new Error("Company slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
+        throw localSkillError("Company slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
     }
     if (!SKILL_SLUG_PATTERN.test(skillSlug)) {
-        throw new Error("Skill slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
+        throw localSkillError("Skill slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
     }
     return path.join(hqRoot, "companies", companySlug, "skills", skillSlug, "SKILL.md");
 }
@@ -277,7 +283,10 @@ export function registerSkillCommand(program, deps = {}) {
         .option("--surface-only", "Refresh local skill discovery without registration or sync")
         .action(async (slug, opts) => {
         if (!SKILL_SLUG_PATTERN.test(slug)) {
-            throw new Error("Skill slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
+            // HQ-CLI-17: the `create <slug>` argument is caller input; a malformed
+            // slug is a correctly-enforced refusal, not a crash. Mark it expected
+            // (via localSkillError) so it is printed and skipped for Sentry.
+            throw localSkillError("Skill slug must start with a lowercase letter or number and contain only lowercase letters, numbers, and hyphens.");
         }
         const parentOpts = skill.opts();
         const resolvedRoot = path.resolve(parentOpts.hqRoot ?? hqRoot);
@@ -285,7 +294,13 @@ export function registerSkillCommand(program, deps = {}) {
         const filePath = canonicalCompanySkillPath(resolvedRoot, companySlug, slug);
         const legacyPrefix = readCompanyPrefix(resolvedRoot, companySlug);
         if (fs.existsSync(filePath) && !fs.statSync(filePath).isFile()) {
-            throw new Error(`Expected a SKILL.md file at '${filePath}'.`);
+            // HQ-CLI-17: the target path is derived from caller input and its
+            // on-disk shape is the caller's own filesystem, not an hq-cli defect.
+            // The bare Error also embedded this absolute (home-relative) path, so it
+            // minted a NEW Sentry fingerprint per machine. Mark it expected so it is
+            // printed (with the path the caller needs) and never captured. Redaction
+            // in localSkillError scrubs credentials but leaves plain paths intact.
+            throw localSkillError(`Expected a SKILL.md file at '${filePath}'.`);
         }
         if (opts.surfaceOnly === true) {
             // Discovery wrappers are execution surfaces. Never create one for an
@@ -396,8 +411,10 @@ export function registerSkillCommand(program, deps = {}) {
         .requiredOption("-m, --message <text>", "The improvement to discuss")
         .action(async (target, opts) => {
         const message = opts.message.trim();
+        // HQ-CLI-17: a blank `-m/--message` is caller input, not an hq-cli defect.
+        // Mark it expected so it is printed and skipped for Sentry.
         if (!message)
-            throw new Error("An improvement message is required.");
+            throw localSkillError("An improvement message is required.");
         const parentOpts = skill.opts();
         const resolvedRoot = path.resolve(parentOpts.hqRoot ?? hqRoot);
         const companySlug = resolveCompanySlug(parentOpts.company, resolvedRoot);

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

@@ -152,6 +152,29 @@ export declare class QmdLlmDisabledError extends QmdExitError {
 export declare class QmdModuleMissingError extends QmdExitError {
     name: string;
 }
+/**
+ * qmd could not open its SQLite store because the store's DIRECTORY does not
+ * exist. @tobilu/qmd resolves the store as $INDEX_PATH (returned verbatim,
+ * before any mkdir) else ${XDG_CACHE_HOME||~/.cache}/qmd (behind a mkdir whose
+ * failure it swallows), then `new Database(path)` throws better-sqlite3's
+ * `TypeError: Cannot open database because the directory does not exist`. That
+ * missing directory is the caller's ENVIRONMENT — a pruned cache, a fresh
+ * machine, an INDEX_PATH into a deleted tree, or a directory hq could not create
+ * (permissions / a read-only mount) — never a bug HQ can fix in code.
+ *
+ * `storeDir` carries the directory hq resolved qmd would open its store in, and
+ * `ensureReason` the bounded errno phrase for why hq's own best-effort
+ * pre-create of that directory failed (undefined when the ensure succeeded or
+ * did not run). Both are hq-DERIVED — the resolved path plus a finite errno
+ * reason — so the boundary can name them in an input-free remedy without ever
+ * echoing caller argv or upstream text. HQ-CLI-16 (Sentry 7698235964).
+ */
+export declare class QmdStoreMissingError extends QmdExitError {
+    readonly storeDir?: string | undefined;
+    readonly ensureReason?: string | undefined;
+    name: string;
+    constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string, storeDir?: string | undefined, ensureReason?: string | undefined);
+}
 export type ResolveQmdBinOptions = {
     env?: Record<string, string | undefined>;
     isExecutable?: (candidate: string) => boolean;
@@ -203,6 +226,48 @@ export declare function packageLocalNodeEntry(): string | undefined;
  * disappeared from `hq index status`. Same root cause as packageLocalBin.
  */
 export declare function resolveQmdVersion(): string | undefined;
+/**
+ * The outcome of the best-effort store-directory ensure, keyed by resolved
+ * 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.
+ */
+type QmdStoreEnsureOutcome = {
+    dir: string;
+    created: boolean;
+    reason?: string;
+};
+/** Test-only: read the most recent store-directory ensure outcome. */
+export declare function lastQmdStoreEnsureOutcome(): QmdStoreEnsureOutcome | undefined;
+/**
+ * Resolve the DIRECTORY @tobilu/qmd will open its SQLite store in, mirroring the
+ * 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);
+ *   - 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 type EnsureQmdStoreDirOptions = {
+    /** mkdir seam (default `fs.mkdirSync(dir, { recursive: true })`); injected in tests. */
+    mkdir?: (dir: string) => void;
+};
+/**
+ * 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
+ * machine — simply works instead of erroring. It creates ONLY that one directory
+ * (recursive), records the outcome (including a bounded errno reason on
+ * failure), and NEVER throws, retries, waits, or spawns. When the mkdir fails
+ * (permissions / read-only), qmd then still can't open its store, and the
+ * recorded reason is what makes the classified remedy self-describing. Modelled
+ * on the repairQmdNativeBindings best-effort contract in this file.
+ */
+export declare function ensureQmdStoreDir(env?: NodeJS.ProcessEnv, options?: EnsureQmdStoreDirOptions): void;
 /** Reset per-process probe/repair memoisation. Test-only. */
 export declare function __resetQmdProbeStateForTests(): void;
 /** Probe a resolved invocation, memoised per invocation; records the failure

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

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 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 { redactErrorText } from '../../utils/redact-error-text.js';
 import { planCommandSpawn } from '../../utils/windows-spawn.js';
 const require = createRequire(import.meta.url);
@@ -131,6 +132,33 @@ export class QmdLlmDisabledError extends QmdExitError {
 export class QmdModuleMissingError extends QmdExitError {
     name = 'QmdModuleMissingError';
 }
+/**
+ * qmd could not open its SQLite store because the store's DIRECTORY does not
+ * exist. @tobilu/qmd resolves the store as $INDEX_PATH (returned verbatim,
+ * before any mkdir) else ${XDG_CACHE_HOME||~/.cache}/qmd (behind a mkdir whose
+ * failure it swallows), then `new Database(path)` throws better-sqlite3's
+ * `TypeError: Cannot open database because the directory does not exist`. That
+ * missing directory is the caller's ENVIRONMENT — a pruned cache, a fresh
+ * machine, an INDEX_PATH into a deleted tree, or a directory hq could not create
+ * (permissions / a read-only mount) — never a bug HQ can fix in code.
+ *
+ * `storeDir` carries the directory hq resolved qmd would open its store in, and
+ * `ensureReason` the bounded errno phrase for why hq's own best-effort
+ * pre-create of that directory failed (undefined when the ensure succeeded or
+ * did not run). Both are hq-DERIVED — the resolved path plus a finite errno
+ * reason — so the boundary can name them in an input-free remedy without ever
+ * echoing caller argv or upstream text. HQ-CLI-16 (Sentry 7698235964).
+ */
+export class QmdStoreMissingError extends QmdExitError {
+    storeDir;
+    ensureReason;
+    name = 'QmdStoreMissingError';
+    constructor(message, args, status, stdout, stderr, storeDir, ensureReason) {
+        super(message, args, status, stdout, stderr);
+        this.storeDir = storeDir;
+        this.ensureReason = ensureReason;
+    }
+}
 function isExecutable(candidate) {
     try {
         fs.accessSync(candidate, fs.constants.X_OK);
@@ -265,6 +293,84 @@ const usableQmdCache = new Map();
 const lastProbeFailure = new Map();
 /** At most one native-binding repair attempt per process (bounded, no retries). */
 let nativeBindingRepairAttempted = false;
+const storeEnsureByDir = new Map();
+/** The most recent ensure outcome (the directory the next qmd spawn will use). */
+let lastQmdStoreEnsure;
+/** Test-only: read the most recent store-directory ensure outcome. */
+export function lastQmdStoreEnsureOutcome() {
+    return lastQmdStoreEnsure;
+}
+/**
+ * Resolve the DIRECTORY @tobilu/qmd will open its SQLite store in, mirroring the
+ * 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);
+ *   - 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) {
+    const indexPath = env.INDEX_PATH;
+    if (indexPath)
+        return path.dirname(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');
+}
+/** Map a mkdir ErrnoException to a bounded, human errno reason (never free text). */
+function ensureFailureReason(error) {
+    const code = error?.code;
+    switch (code) {
+        case 'EACCES':
+        case 'EPERM':
+            return 'permission denied';
+        case 'EROFS':
+            return 'the filesystem is read-only';
+        case 'ENOTDIR':
+            return 'a path component is not a directory';
+        case 'ENOENT':
+            return 'a parent path does not exist';
+        case 'ENOSPC':
+            return 'no space left on device';
+        default:
+            return typeof code === 'string' && code.length > 0 ? code : 'an unknown error';
+    }
+}
+/**
+ * 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
+ * machine — simply works instead of erroring. It creates ONLY that one directory
+ * (recursive), records the outcome (including a bounded errno reason on
+ * failure), and NEVER throws, retries, waits, or spawns. When the mkdir fails
+ * (permissions / read-only), qmd then still can't open its store, and the
+ * recorded reason is what makes the classified remedy self-describing. Modelled
+ * on the repairQmdNativeBindings best-effort contract in this file.
+ */
+export function ensureQmdStoreDir(env = process.env, options = {}) {
+    let dir;
+    try {
+        dir = resolveQmdStoreDir(env);
+    }
+    catch {
+        // Resolution itself must never break a qmd run.
+        return;
+    }
+    let outcome = storeEnsureByDir.get(dir);
+    if (!outcome) {
+        const mkdir = options.mkdir ?? ((target) => { fs.mkdirSync(target, { recursive: true }); });
+        try {
+            mkdir(dir);
+            outcome = { dir, created: true };
+        }
+        catch (error) {
+            outcome = { dir, created: false, reason: ensureFailureReason(error) };
+        }
+        storeEnsureByDir.set(dir, outcome);
+    }
+    lastQmdStoreEnsure = outcome;
+}
 /** How long a single usability probe or repair sub-step may run. */
 const PROBE_TIMEOUT_MS = 10_000;
 const REPAIR_STEP_TIMEOUT_MS = 180_000;
@@ -275,6 +381,8 @@ export function __resetQmdProbeStateForTests() {
     usableQmdCache.clear();
     lastProbeFailure.clear();
     nativeBindingRepairAttempted = false;
+    storeEnsureByDir.clear();
+    lastQmdStoreEnsure = undefined;
 }
 /** The qmd file identity of an invocation: the launcher for a node entry, else
  * the command. Used to key probe failures and confine native-binding repair. */
@@ -823,6 +931,26 @@ function finishRunQmd(result, bin, args) {
     if (isQmdModuleMissingError({ stderr: normalized.stderr, stdout: normalized.stdout })) {
         throw new QmdModuleMissingError(`qmd ${subcommand} could not run: a module it needs was not found (the hq install tree looks incomplete)`, args, normalized.status, normalized.stdout, normalized.stderr);
     }
+    // qmd could not open its SQLite store because the store DIRECTORY does not
+    // exist (better-sqlite3: `TypeError: Cannot open database because the
+    // directory does not exist`). That missing directory is the caller's
+    // environment — a pruned cache, a fresh machine, an INDEX_PATH into a deleted
+    // tree, or a directory hq could not create (permissions / a read-only mount) —
+    // not an hq-cli defect. Type it so the boundary prints a self-describing
+    // remedy (naming the resolved store dir and the recorded errno reason) and
+    // skips capture, and so index-cmd's diagnostic command degrades rather than
+    // crashing. 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 LLM-disabled and module-missing checks (narrower typed signatures)
+    // and BEFORE the collection-missing regex: the wordings are disjoint (that
+    // regex needs `collection`/`qmd://` adjacent to a not-found token, which this
+    // stderr lacks), so no existing branch changes behaviour (HQ-CLI-16, Sentry
+    // 7698235964). The stamped storeDir/ensureReason come from the pre-spawn
+    // ensure that ran for this exact store directory.
+    if (isQmdStoreMissingError({ stderr: normalized.stderr, stdout: normalized.stdout })) {
+        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);
+    }
     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);
     }
@@ -861,6 +989,13 @@ export function runQmd(args, options = {}) {
             execPath: options.execPath,
             spawn: options.spawn,
         });
+    // Self-provision qmd's store directory before the spawn so the benign
+    // pruned-cache / fresh-machine case simply works, and record the outcome so a
+    // residual store-open failure (a directory hq could not create) can be
+    // 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);
     const result = spawnQmd(invocation, args, {
         cwd: options.cwd,
         env: options.env ?? process.env,

package/dist/main.js

@@ -71,11 +71,14 @@ import { qmdMissingCollectionMessage } from "./utils/qmd-collection-missing-erro
 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 { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import { isAuthError } from "./utils/auth-error.js";
 import { browserLoginAbandonedMessage } from "./utils/browser-login-abandoned.js";
+import { callbackPortBusyMessage, DEFAULT_CALLBACK_PORT } from "./utils/callback-port-busy.js";
+import { DEFAULT_COGNITO } from "./utils/cognito-session.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import { canOfferTeamUpgrade, formatPlanGateError, isPlanGateError, offerTeamUpgrade, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
@@ -413,6 +416,23 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         deps.stderr.write(`hq: ${browserLoginAbandonedMessage(err)}\n`);
         deps.setExitCode(1);
     }
+    else if (callbackPortBusyMessage(err, DEFAULT_COGNITO.port ?? DEFAULT_CALLBACK_PORT)) {
+        // HQ-CLI-15: the caller's command fell back to the IMPLICIT browser
+        // sign-in, but the loopback OAuth callback port (127.0.0.1:<port>) was
+        // already held by another process, so @indigoai-us/hq-cloud's browserLogin
+        // rejected with a raw `listen EADDRINUSE` on that fixed port. That is the
+        // caller's local machine state — a second `hq login` still waiting for its
+        // browser sign-in, or a stray process on the port — the user fixes by
+        // finishing/stopping the other login and retrying, not an hq-cli defect.
+        // Print the fixed actionable remedy and skip Sentry so one busy port
+        // doesn't file a permanent, unfixable "crash". Placed with the
+        // abandoned-login carve-out (both mean "your HQ session couldn't be
+        // established interactively"). The match is STRUCTURAL (errno code + the
+        // configured callback port), so an EADDRINUSE on any OTHER port stays a
+        // genuine fault and still captures below.
+        deps.stderr.write(`hq: ${callbackPortBusyMessage(err, DEFAULT_COGNITO.port ?? DEFAULT_CALLBACK_PORT)}\n`);
+        deps.setExitCode(1);
+    }
     else if (isPlanGateError(err)) {
         // hq-pro's plan denials are expected product limits, never a CLI crash.
         // The shared vault client has already decoded and typed the small safe
@@ -521,7 +541,22 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         const moduleMissingMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg
             ? null
             : qmdModuleMissingMessage(err);
-        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg
+        // A qmd store-directory-missing failure (better-sqlite3 could not open its
+        // SQLite store because the directory does not exist) is the caller's local
+        // filesystem/environment — a pruned cache, a fresh machine, an INDEX_PATH
+        // into a deleted tree, or a directory hq could not create — not an hq-cli
+        // defect. finishRunQmd types it QmdStoreMissingError, carrying the resolved
+        // store directory and the errno reason hq's pre-spawn ensure recorded;
+        // print that self-describing remedy and skip capture (HQ-CLI-16, Sentry
+        // 7698235964). Evaluated AFTER the native-binding / collection-missing /
+        // terminated / llm-disabled / module-missing checks (all narrower or
+        // sibling typed signatures) and BEFORE the environmental / transport /
+        // generic branches; the signatures are disjoint, so ordering changes no
+        // existing branch.
+        const storeMissingMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg
+            ? null
+            : qmdStoreMissingMessage(err);
+        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg
             ? null
             : environmentalFsErrorMessage(err);
         // A LOCAL sync-state lock failure (@indigoai-us/hq-cloud's
@@ -538,7 +573,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 || envMsg
+        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || envMsg
             ? null
             : syncStateLockMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
@@ -551,7 +586,14 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // message that names the unreachable host, exit 1, and skip Sentry.
         // Ordered after the environmental check so a full disk keeps its exact
         // existing message.
-        const transportMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || envMsg || lockMsg
+        const transportMsg = qmdMsg ||
+            collectionMsg ||
+            terminatedMsg ||
+            llmDisabledMsg ||
+            moduleMissingMsg ||
+            storeMissingMsg ||
+            envMsg ||
+            lockMsg
             ? null
             : networkTransportErrorMessage(err);
         if (qmdMsg) {
@@ -569,6 +611,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (moduleMissingMsg) {
             deps.stderr.write(`hq: ${moduleMissingMsg}\n`);
         }
+        else if (storeMissingMsg) {
+            deps.stderr.write(`hq: ${storeMissingMsg}\n`);
+        }
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }

package/dist/utils/callback-port-busy.d.ts

@@ -0,0 +1,29 @@
+/** Fixed callback port for the loopback OAuth server when unset (mirrors DEFAULT_COGNITO). */
+export declare const DEFAULT_CALLBACK_PORT = 8765;
+/**
+ * The fixed, actionable remedy. Interpolates ONLY the numeric callback port (a
+ * bounded value drawn from config, never caller input or upstream error text),
+ * so this carve-out can never widen disclosure and needs no redaction pass.
+ */
+export declare function callbackPortBusyGuidance(port: number): string;
+/**
+ * The LOOSE predicate for a caller that just invoked browserLogin and is
+ * catching its own error (`hq auth login`/`hq login`): an EADDRINUSE by errno
+ * code OR message is the callback-port collision, because the callback server is
+ * the only listener that call could have opened. NOT for the shared boundary —
+ * use {@link callbackPortBusyMessage} there.
+ */
+export declare function isCallbackPortBusy(err: unknown): boolean;
+/**
+ * The STRUCTURAL classifier for the shared top-level boundary. Returns the fixed
+ * remedy ONLY when `err` is an EADDRINUSE whose `port` equals the configured
+ * callback `port`; otherwise returns `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture. A null result means "handle as usual (capture to Sentry)" — including
+ * an EADDRINUSE on ANY other port, which is a different listener and a genuine
+ * fault that must stay reportable. Matched on the errno SHAPE only (code + port),
+ * never on free text, so no upstream/caller string can reach the printed line.
+ */
+export declare function callbackPortBusyMessage(err: unknown, port: number): string | null;
+//# sourceMappingURL=callback-port-busy.d.ts.map

package/dist/utils/callback-port-busy.js

@@ -0,0 +1,87 @@
+// src/utils/callback-port-busy.ts
+//
+// Classify a browser-login CALLBACK-PORT COLLISION — the loopback OAuth server
+// @indigoai-us/hq-cloud's browserLogin binds (the fixed DEFAULT_COGNITO.port,
+// 8765 unless HQ_COGNITO_CALLBACK_PORT overrides it) could not be bound because
+// another process already holds it, so Node rejects with a raw ErrnoException
+// (`listen EADDRINUSE …`, code EADDRINUSE, port 8765, syscall listen). That is
+// the caller's LOCAL machine state — a second `hq login` still waiting for its
+// browser sign-in, or a stray process on the port — NOT an hq-cli defect: the
+// user fixes it by finishing/stopping the other login and retrying. So the
+// top-level handler prints an actionable line and exits non-zero but SKIPS
+// Sentry capture, mirroring the abandoned-browser-login (HQ-CLI-V), auth
+// (HQ-CLI-8), company-selection (HQ-CLI-7), expected-user-error (HQ-CLI-6), and
+// environmental-FS (HQ-CLI-2) carve-outs.
+//
+// HQ-CLI-15 (Sentry indigo-d0/hq-cli 7698014705): `hq integrations list
+// --company <slug> --json` refreshed an expiring session, the refresh failed,
+// and it fell back to the IMPLICIT browser sign-in on one of the ~100
+// ensureCognitoToken/ensureCognitoIdToken call sites. The callback port was
+// already held, so browserLogin rejected with a bare `listen EADDRINUSE:
+// address already in use 127.0.0.1:8765`. That Node error carries no `expected`
+// flag and is not an AuthError/CognitoAuthError/…, so every predicate in
+// handleTopLevelError returned false and the collision was captured as a
+// high-priority, unfixable "crash". `hq auth login` already classified the
+// identical condition in a file-private helper; this module lifts that
+// classification to the shared boundary so every implicit call site is covered
+// from one source of truth.
+//
+// Two predicates, differing ONLY by how much context the caller already has:
+//   - isCallbackPortBusy(err): the LOOSE form for a call site that KNOWS it just
+//     invoked browserLogin (`hq auth login`/`hq login`). There the only listener
+//     in play is the callback server, so an EADDRINUSE — by code or message — is
+//     unambiguously the callback port.
+//   - callbackPortBusyMessage(err, port): the STRUCTURAL form for the shared
+//     boundary, which sees arbitrary errors from every call site. It matches
+//     ONLY when err.code === 'EADDRINUSE' AND err.port equals the configured
+//     callback port, so an EADDRINUSE raised by any OTHER listener stays
+//     reportable (the boundary must never swallow a genuine listener defect).
+/** Fixed callback port for the loopback OAuth server when unset (mirrors DEFAULT_COGNITO). */
+export const DEFAULT_CALLBACK_PORT = 8765;
+/** Node's errno code for a `listen()` against an address already in use. */
+const EADDRINUSE = "EADDRINUSE";
+/**
+ * The fixed, actionable remedy. Interpolates ONLY the numeric callback port (a
+ * bounded value drawn from config, never caller input or upstream error text),
+ * so this carve-out can never widen disclosure and needs no redaction pass.
+ */
+export function callbackPortBusyGuidance(port) {
+    return (`The browser-login callback port (127.0.0.1:${port}) is already in use. ` +
+        "Another `hq auth login` may still be waiting for browser sign-in. Finish that login, " +
+        "or stop its terminal/process, then retry.");
+}
+/**
+ * The LOOSE predicate for a caller that just invoked browserLogin and is
+ * catching its own error (`hq auth login`/`hq login`): an EADDRINUSE by errno
+ * code OR message is the callback-port collision, because the callback server is
+ * the only listener that call could have opened. NOT for the shared boundary —
+ * use {@link callbackPortBusyMessage} there.
+ */
+export function isCallbackPortBusy(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const { code, message } = err;
+    return code === EADDRINUSE || message?.includes(EADDRINUSE) === true;
+}
+/**
+ * The STRUCTURAL classifier for the shared top-level boundary. Returns the fixed
+ * remedy ONLY when `err` is an EADDRINUSE whose `port` equals the configured
+ * callback `port`; otherwise returns `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture. A null result means "handle as usual (capture to Sentry)" — including
+ * an EADDRINUSE on ANY other port, which is a different listener and a genuine
+ * fault that must stay reportable. Matched on the errno SHAPE only (code + port),
+ * never on free text, so no upstream/caller string can reach the printed line.
+ */
+export function callbackPortBusyMessage(err, port) {
+    if (!err || typeof err !== "object")
+        return null;
+    const errno = err;
+    if (errno.code !== EADDRINUSE)
+        return null;
+    if (typeof errno.port !== "number" || errno.port !== port)
+        return null;
+    return callbackPortBusyGuidance(port);
+}
+//# sourceMappingURL=callback-port-busy.js.map

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

@@ -0,0 +1,20 @@
+/**
+ * True when `err` is a qmd store-directory-missing failure: better-sqlite3's
+ * fixed sentence appears in qmd's captured stderr/stdout. Accepts either the
+ * thrown error (reads its `stderr`/`stdout`) or a bare `{ stderr, stdout }`
+ * probe object. A true result means the caller should print the classified
+ * remedy, exit non-zero, and SKIP Sentry capture.
+ */
+export declare function isQmdStoreMissingError(err: unknown): boolean;
+/**
+ * If `err` is a qmd store-directory-missing failure, return the actionable
+ * remedy; otherwise return `null`. Mirrors qmdNativeBindingErrorMessage /
+ * qmdMissingCollectionMessage 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`/`ensureReason`
+ * fields (absent on a bare probe object — then the message names neither), never
+ * from qmd's output.
+ */
+export declare function qmdStoreMissingMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-store-missing-error.d.ts.map

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

@@ -0,0 +1,96 @@
+// src/utils/qmd-store-missing-error.ts
+//
+// Classify a qmd failure caused by a MISSING STORE DIRECTORY — the directory
+// qmd opens its SQLite index in does not exist — rather than an hq-cli code
+// defect. This is the caller's LOCAL filesystem/environment (a pruned cache dir,
+// a fresh machine, an INDEX_PATH pointing into a deleted tree, or a directory hq
+// could not create because of permissions / a read-only mount), not a bug HQ can
+// fix in code, so the CLI surfaces an actionable remedy and SKIPS Sentry
+// capture. Sibling of qmd-native-binding-error.ts (HQ-CLI-J, unbuilt bindings),
+// environmental-error.ts (HQ-CLI-2, full disk), and network-transport-error.ts
+// (HQ-CLI-G, connectivity): a failure that is NOT an hq-cli defect is printed
+// with an actionable message and never filed as a crash.
+//
+// HQ-CLI-16 (Sentry indigo-d0/hq-cli 7698235964): `hq index status` ran `qmd
+// collection list`, and @tobilu/qmd's better-sqlite3 threw `TypeError: Cannot
+// open database because the directory does not exist` the moment it opened its
+// store — qmd's getDefaultDbPath returns $INDEX_PATH verbatim before any mkdir,
+// else resolves ${XDG_CACHE_HOME||~/.cache}/qmd behind a mkdir whose failure it
+// swallows. runQmd wrapped the exit-1 in a plain QmdExitError, index-cmd's catch
+// re-threw it (narrowed to the sibling native-binding case only), and it reached
+// the boundary's final else, which captured it — an unfixable, per-user "crash"
+// whose title carries the caller's home path.
+//
+// Matching is deliberately narrow so it can neither be tripped by user input nor
+// silence a real bug: better-sqlite3's FIXED sentence is required in qmd's OWN
+// captured streams (stderr/stdout), NEVER the synthesized `message` — which
+// echoes the caller's argv — so a search query that merely contains the phrase
+// can never classify. 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 exact "directory does not exist" sentence — sufficient on its own. */
+const STORE_DIR_MISSING = /Cannot open database because the directory does not exist/i;
+/**
+ * qmd's OWN captured streams (stderr then stdout), joined. The synthesized
+ * `message` is deliberately NOT consulted: it embeds the caller's qmd arguments,
+ * so reading it would let a user query for this phrase trip the classifier.
+ */
+function capturedStreams(err) {
+    if (err === null || typeof err !== "object")
+        return "";
+    const record = err;
+    const stderr = typeof record.stderr === "string" ? record.stderr : "";
+    const stdout = typeof record.stdout === "string" ? record.stdout : "";
+    return `${stderr}\n${stdout}`;
+}
+/**
+ * True when `err` is a qmd store-directory-missing failure: better-sqlite3's
+ * fixed sentence appears in qmd's captured stderr/stdout. Accepts either the
+ * thrown error (reads its `stderr`/`stdout`) or a bare `{ stderr, stdout }`
+ * probe object. A true result means the caller should print the classified
+ * remedy, exit non-zero, and SKIP Sentry capture.
+ */
+export function isQmdStoreMissingError(err) {
+    return STORE_DIR_MISSING.test(capturedStreams(err));
+}
+/**
+ * The actionable remedy, naming the store directory that could not be opened and
+ * (when the store-directory ensure step recorded one) the errno reason it could
+ * not be created. Both are hq-DERIVED values — the resolved store path and a
+ * bounded errno phrase — never caller argv/query or upstream free text, so the
+ * line stays input-free. Deliberately does NOT point the user at `hq index sync`:
+ * reconciliation begins with the same `qmd collection list` and would hit the
+ * identical failure, a dead-end loop.
+ */
+function remedyMessage(storeDir, ensureReason) {
+    const where = storeDir
+        ? `hq's local search store directory (${storeDir}) could not be opened`
+        : "hq's local search store directory could not be opened";
+    const because = ensureReason
+        ? ` — hq could not create it: ${ensureReason}.`
+        : " — it does not exist.";
+    return (`${where}${because} This is your machine's filesystem, not an hq bug: ` +
+        "check that the directory (and its parent) exist and are writable, or point " +
+        "INDEX_PATH at a writable location, then run your command again.");
+}
+/**
+ * If `err` is a qmd store-directory-missing failure, return the actionable
+ * remedy; otherwise return `null`. Mirrors qmdNativeBindingErrorMessage /
+ * qmdMissingCollectionMessage 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`/`ensureReason`
+ * fields (absent on a bare probe object — then the message names neither), never
+ * from qmd's output.
+ */
+export function qmdStoreMissingMessage(err) {
+    if (!isQmdStoreMissingError(err))
+        return null;
+    const record = err;
+    const storeDir = typeof record.storeDir === "string" && record.storeDir.length > 0 ? record.storeDir : null;
+    const ensureReason = typeof record.ensureReason === "string" && record.ensureReason.length > 0
+        ? record.ensureReason
+        : null;
+    return remedyMessage(storeDir, ensureReason);
+}
+//# sourceMappingURL=qmd-store-missing-error.js.map

package/dist/utils/sentry-fingerprint.js

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

package/package.json

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