@indigoai-us/hq-cli 5.103.31 → 5.103.33

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.103.33] — 2026-08-30
+
+## [5.103.32] — 2026-08-29
+
 ## [5.103.31] — 2026-08-29
 
 ## [5.103.30] — 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

@@ -68,7 +68,13 @@ export function readActiveCompanySlug(hqRoot) {
 export function resolveCompanySlug(flag, hqRoot = DEFAULT_HQ_ROOT) {
     const slug = flag ?? readActiveCompanySlug(hqRoot);
     if (!slug) {
-        throw new Error("No company specified. Pass --company <slug> (or set an active company in .hq/config.json).");
+        // HQ-CLI-13 (Sentry 7695157352): neither `--company` nor an active company
+        // in `.hq/config.json` — ordinary caller state with a self-describing
+        // remedy, not an hq-cli defect. Mark it `expected` (via localSkillError) so
+        // the top-level boundary prints this line and skips Sentry, exactly as the
+        // resolveSkillUid local conditions do (HQ-CLI-10/11). The text is unchanged
+        // and already tells the caller what to do.
+        throw localSkillError("No company specified. Pass --company <slug> (or set an active company in .hq/config.json).");
     }
     return slug;
 }
@@ -354,10 +360,26 @@ export function registerSkillCommand(program, deps = {}) {
                 });
             }
             catch (err) {
-                throw new Error(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync failed: ${err instanceof Error ? err.message : String(err)}`);
+                // HQ-CLI-14 (Sentry 7695715459): registration and the local stamp
+                // already SUCCEEDED; only the upload failed. Do NOT flatten the
+                // inner error into a new generic Error — that discarded its class,
+                // `name`, `cause` and any `expected` marker, and spliced the
+                // caller's absolute SKILL.md path into a message Sentry then
+                // fingerprinted per home directory. Keep the partial-success context
+                // on stderr, then rethrow the ORIGINAL error so every classifier the
+                // boundary already has (expected, AuthError, plan-gate, EPIPE,
+                // environmental-fs, sync-state-lock, network-transport) applies to a
+                // sync failure exactly as it does everywhere else, and a genuine
+                // fault is captured under its own type and stack.
+                console.warn(chalk.yellow(`⚠ Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync failed.`));
+                throw err;
             }
             if (syncResult.aborted) {
-                throw new Error(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync aborted because the remote file conflicts.`);
+                // A remote-file conflict under hq-cli's own `onConflict: "abort"`
+                // choice is unambiguous caller state with a user-side remedy, not an
+                // hq-cli defect — mark it `expected` so it is printed and skipped for
+                // Sentry rather than filing a crash on its first occurrence.
+                throw localSkillError(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync aborted because the remote file conflicts.`);
             }
         }
         console.log(chalk.green(`Skill ready: ${registered.skillUid}`));

package/dist/lib/doctor/checks/integrations.js

@@ -128,6 +128,21 @@ function resultForGroup(entries, company) {
             remediation: serverRemediation ?? `hq integrations connect ${first.provider} --token-stdin${company ? ` --company ${company}` : ""}`,
         };
     }
+    if (first.kind === "re-add-with-auth") {
+        // Deliberately NOT the `re-add` branch. That one's default remediation is
+        // the API-key flow (`--token-stdin`), and this fault is the opposite case:
+        // an install that was created with no credential at all and needs a
+        // browser sign-in. Falling through to the reconnect default would be worse
+        // still, since there is no stored credential to refresh.
+        return {
+            status: "FAIL",
+            checkId: `${INTEGRATIONS_PREFIX}.re-add-with-auth.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}.`,
+            remediation: serverRemediation
+                ?? `Remove the integration and add it again, signing in this time: hq integrations connect ${first.provider}${company ? ` --company ${company}` : ""}`,
+        };
+    }
     if (first.kind === "contact-admin") {
         return {
             status: "FAIL",

package/dist/lib/integrations/health.d.ts

@@ -39,8 +39,18 @@ export interface IntegrationConnection extends AdminConnection {
  *
  * A server that DID say `fix_kind: "reconnect"` still classifies as
  * `reconnect`: that is a diagnosis, not an absence of one.
+ *
+ * `re-add-with-auth` is NOT a synonym for `re-add`. `re-add` means an API key
+ * has to be typed in again; this one means the install was created with no
+ * credential at all and needs a browser sign-in. Collapsing the two would print
+ * the API-key command against a connection that never had a key.
+ *
+ * This union is kept identical to the console's twin (`_connection-health.ts`
+ * `FixKind`) on purpose: a person who reads one surface and then the other must
+ * not find the same failure sorted into two different buckets. Any member added
+ * here has to be added there in the same change.
  */
-export type FindingKind = "reconnect" | "re-add" | "contact-admin" | "wait" | "provider-blocked" | "retryable" | "hq-configuration" | "undiagnosed";
+export type FindingKind = "reconnect" | "re-add" | "re-add-with-auth" | "contact-admin" | "wait" | "provider-blocked" | "retryable" | "hq-configuration" | "undiagnosed";
 export interface Finding {
     provider: string;
     connectionId: string;

package/dist/lib/integrations/health.js

@@ -19,6 +19,12 @@ import { bareProvider } from "./provider-slug.js";
 const RECONNECT_REASON_CODES = new Set([
     "oauth_refresh_invalid_grant",
     "oauth_refresh_unavailable",
+    // The stored grant carries no refresh token, so nothing can be renewed
+    // without the person signing in again. The legacy text heuristic below
+    // happens to match this string through its `refresh[\s_-]*token` branch, but
+    // that is coincidence rather than contract: it is listed here so the
+    // classification survives a rename of the heuristic.
+    "oauth_refresh_missing_refresh_token",
     "token_refresh_failed",
     "credentials_rejected",
 ]);
@@ -26,7 +32,27 @@ const RETRYABLE_REASON_CODES = new Set([
     "oauth_refresh_transient",
     "oauth_refresh_write_conflict",
 ]);
-const HQ_CONFIGURATION_REASON_CODE = "oauth_client_secret_unavailable";
+/**
+ * Faults that sit on HQ's side of the boundary.
+ *
+ * Neither is repairable by anyone at the customer: `oauth_client_secret_unavailable`
+ * means HQ could not read its own client secret, and `oauth_refresh_missing_client`
+ * means HQ has no OAuth client configured for the provider at all. Sending a
+ * person round a reconnect for either costs them a working credential and
+ * cannot succeed, which is why hq-pro answers both with `contact-support`
+ * ahead of its own role gate — a member sees the same instruction an owner does.
+ */
+const HQ_CONFIGURATION_REASON_CODES = new Set([
+    "oauth_client_secret_unavailable",
+    "oauth_refresh_missing_client",
+]);
+/**
+ * The install exists but was created without credentials, and the provider
+ * refused it. The repair is to add the integration again and sign in — NOT the
+ * `re-add` API-key flow, and not a reconnect of a credential that was never
+ * stored.
+ */
+const RE_ADD_WITH_AUTH_REASON_CODE = "unauthenticated_install_rejected";
 const UNSPECIFIED_REASON_CODE = "unspecified";
 /** Classify without echoing untrusted provider text, which may contain secrets. */
 export function classifyConnection(connection) {
@@ -45,10 +71,11 @@ export function classifyConnection(connection) {
     if (knownReasonCode && knownReasonCode !== UNSPECIFIED_REASON_CODE) {
         const finding = findingForKnownReasonCode(connection, provider, knownReasonCode);
         // Retryable and HQ-configuration reason codes diagnose conditions that a
-        // caller-specific remediation cannot change. Reconnect-class codes defer
-        // to the server's credential/role-aware remediation classification, so an
-        // install in progress is never interrupted by a reconnect.
-        return [withServerRemediation(connection, RECONNECT_REASON_CODES.has(knownReasonCode)
+        // caller-specific remediation cannot change. Role-dependent codes defer to
+        // the server's credential/role-aware remediation classification, so an
+        // install in progress is never interrupted by a reconnect and a member is
+        // never told to perform a repair only an owner or admin can carry out.
+        return [withServerRemediation(connection, defersToServerFixKind(knownReasonCode)
                 ? findingForServerFixKind(finding, connection.fix_kind)
                 : finding)];
     }
@@ -161,6 +188,32 @@ function findingForServerFixKind(fallback, fixKind) {
                 kind: "wait",
                 message: "is waiting for the Factory installation to complete",
             };
+        case "re-add-with-auth":
+            return {
+                ...fallback,
+                kind: "re-add-with-auth",
+                message: "was added without a sign-in, and the provider refused it",
+            };
+        case "contact-support":
+            // hq-pro answers `contact-support` only for a gap in HQ's own OAuth
+            // configuration, which is the same class `hq-configuration` already
+            // names. It gets that kind rather than a member of its own so both paths
+            // into the class carry the same VERDICT — an HQ administrator has to fix
+            // it and reconnecting will not — instead of one cause reaching a person
+            // under two different remediations.
+            //
+            // The message stays distinct, and `hq doctor` groups on the message, so a
+            // provider with both faults prints two lines under the one class. That is
+            // deliberate and matches every other class here (two `reconnect` rows with
+            // different causes already print separately). Collapsing them would mean
+            // stamping a row that arrived with NO reason code with the specific
+            // wording of one that did — a confident wrong answer, which is the exact
+            // failure this vocabulary exists to stop.
+            return {
+                ...fallback,
+                kind: "hq-configuration",
+                message: "is blocked by an HQ-side configuration gap",
+            };
         case "reconnect":
         default:
             return fallback;
@@ -181,13 +234,30 @@ function withServerRemediation(connection, finding) {
  * the legacy text heuristics, which remain below for old and unknown rows.
  */
 function knownReasonCodeFor(connection) {
-    const values = [connection.errorReason, connection.needsReauthReason, connection.degradedReason];
-    if (values.includes(HQ_CONFIGURATION_REASON_CODE))
-        return HQ_CONFIGURATION_REASON_CODE;
-    return values.find((value) => (typeof value === "string" &&
-        (RECONNECT_REASON_CODES.has(value) ||
-            RETRYABLE_REASON_CODES.has(value) ||
-            value === UNSPECIFIED_REASON_CODE)));
+    const values = [connection.errorReason, connection.needsReauthReason, connection.degradedReason]
+        .filter((value) => typeof value === "string");
+    // An HQ-side configuration fault outranks anything else recorded on the row:
+    // no customer-side repair can clear it, so a co-recorded reconnect code must
+    // not send someone to re-enter a credential that was never the problem.
+    const hqFault = values.find((value) => HQ_CONFIGURATION_REASON_CODES.has(value));
+    if (hqFault)
+        return hqFault;
+    return values.find((value) => (RECONNECT_REASON_CODES.has(value) ||
+        RETRYABLE_REASON_CODES.has(value) ||
+        value === RE_ADD_WITH_AUTH_REASON_CODE ||
+        value === UNSPECIFIED_REASON_CODE));
+}
+/**
+ * Whether the server's role- and credential-aware `fix_kind` should override
+ * the reason code's own classification.
+ *
+ * True for faults the customer CAN repair, because who repairs them depends on
+ * the caller's role — hq-pro answers a member with `contact-admin` where it
+ * answers an owner with the repair itself. False for HQ-side and retryable
+ * faults, whose remediation is the same for everyone.
+ */
+function defersToServerFixKind(code) {
+    return RECONNECT_REASON_CODES.has(code) || code === RE_ADD_WITH_AUTH_REASON_CODE;
 }
 function findingForKnownReasonCode(connection, provider, code) {
     if (RECONNECT_REASON_CODES.has(code)) {
@@ -208,11 +278,21 @@ function findingForKnownReasonCode(connection, provider, code) {
                 : "token refresh is temporarily unavailable; the stored credential remains intact",
         };
     }
+    if (code === RE_ADD_WITH_AUTH_REASON_CODE) {
+        return {
+            provider,
+            connectionId: connection.id,
+            kind: "re-add-with-auth",
+            message: "was added without a sign-in, and the provider refused it",
+        };
+    }
     return {
         provider,
         connectionId: connection.id,
         kind: "hq-configuration",
-        message: "the HQ OAuth client secret is unavailable",
+        message: code === "oauth_refresh_missing_client"
+            ? "cannot be refreshed because HQ has no OAuth client configured for this provider"
+            : "the HQ OAuth client secret is unavailable",
     };
 }
 function recordedReason(connection) {

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

@@ -64,17 +64,21 @@ import { registerDoctorCommand } from "./commands/doctor.js";
 import { registerMeshCommand } from "./commands/mesh.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { syncStateLockMessage } from "./utils/sync-state-lock-error.js";
 import { networkTransportErrorMessage } from "./utils/network-transport-error.js";
 import { qmdNativeBindingErrorMessage } from "./utils/qmd-native-binding-error.js";
 import { qmdMissingCollectionMessage } from "./utils/qmd-collection-missing-error.js";
 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";
@@ -412,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
@@ -520,9 +541,41 @@ 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
+        // `StateStoreLockError`: another HQ process on this machine holds the
+        // sync-state journal lock) is the caller's concurrency state, not an
+        // hq-cli defect — hq-cloud's own watcher/sync-runner treat lock contention
+        // as transient. Before HQ-CLI-14 the `hq skill create` sync step flattened
+        // it into a generic, path-bearing Error that reached the capture below and
+        // minted a new fingerprint per home directory. Print the input-free remedy,
+        // exit 1, and skip Sentry. The signatures do not overlap the neighbouring
+        // branches: a StateStoreLockError carries no `.code` (so
+        // environmentalFsErrorMessage returned null) and is not a fetch TypeError
+        // (so it is not a transport failure), and this ordering — after the
+        // 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
+            ? null
+            : syncStateLockMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
         // with a ConnectTimeoutError / ECONNREFUSED / ENOTFOUND cause) is the
         // caller's connectivity, not an hq-cli defect. Before this branch it fell
@@ -533,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
+        const transportMsg = qmdMsg ||
+            collectionMsg ||
+            terminatedMsg ||
+            llmDisabledMsg ||
+            moduleMissingMsg ||
+            storeMissingMsg ||
+            envMsg ||
+            lockMsg
             ? null
             : networkTransportErrorMessage(err);
         if (qmdMsg) {
@@ -551,9 +611,15 @@ 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`);
         }
+        else if (lockMsg) {
+            deps.stderr.write(`hq: ${lockMsg}\n`);
+        }
         else if (transportMsg) {
             deps.stderr.write(`hq: ${transportMsg}\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/dist/utils/sync-state-lock-error.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The `name` @indigoai-us/hq-cloud stamps on a state-store lock failure, and the
+ * prefix it puts on every such message (`super(\`state-store lock: ${message}\`)`).
+ * EITHER signal identifies the class. A unit test pins BOTH against the installed
+ * dependency so a future rename fails loudly in CI here rather than silently
+ * resuming Sentry noise.
+ */
+export declare const SYNC_STATE_LOCK_ERROR_NAME = "StateStoreLockError";
+export declare const SYNC_STATE_LOCK_MESSAGE_PREFIX = "state-store lock: ";
+/**
+ * If `err` is a LOCAL sync-state lock failure, return a short, input-free,
+ * actionable user-facing message; otherwise return `null`.
+ *
+ * A non-null result means the caller should PRINT the message, exit non-zero,
+ * and SKIP Sentry capture — the condition is another HQ process holding this
+ * machine's sync-state lock, not a bug HQ can fix. A null result means "handle
+ * this as usual (capture to Sentry)". The `in-process-async-holder` reason is
+ * deliberately excluded and still captures.
+ *
+ * The returned message never echoes the lock path or any other caller input, so
+ * the whole class groups as ONE Sentry-free condition instead of minting a new
+ * fingerprint per home directory. It is a fixed, bounded string, so no redaction
+ * or length cap is required.
+ */
+export declare function syncStateLockMessage(err: unknown): string | null;
+//# sourceMappingURL=sync-state-lock-error.d.ts.map

package/dist/utils/sync-state-lock-error.js

@@ -0,0 +1,78 @@
+// src/utils/sync-state-lock-error.ts
+//
+// Classify a LOCAL sync-state lock failure — another HQ process on THIS machine
+// already holds the sync-state journal lock — as the caller's machine/
+// concurrency state rather than an hq-cli code defect. Sibling of
+// `environmental-error.ts` (HQ-CLI-2, full disk / read-only fs) and
+// `network-transport-error.ts` (HQ-CLI-G, connectivity): a failure that is not
+// an hq-cli defect is surfaced to the user with an actionable message and
+// skipped for Sentry capture.
+//
+// HQ-CLI-14 (Sentry 7695715459): `hq skill create` registered and stamped the
+// skill, then its sync step called @indigoai-us/hq-cloud's `share()`, which
+// surfaced a `StateStoreLockError: state-store lock: cannot acquire
+// <HOME>/.hq/sync-state-v3/<digest>/append.lock`. hq-cloud's OWN consumers treat
+// lock contention as transient — its watcher reschedules on it and its
+// sync-runner defers only the `in-process-async-holder` reason — so a local
+// lock failure is concurrency state the user resolves by waiting for (or
+// quitting) the other HQ sync, not a reportable hq-cli crash. Before this the
+// caller flattened every sync failure into a generic, path-bearing Error, so the
+// lock class fell through the top-level boundary's closed allowlist and filed a
+// crash whose message minted a new Sentry fingerprint per home directory.
+//
+// Matching is STRUCTURAL, never `instanceof`: `StateStoreLockError` is not
+// re-exported from `@indigoai-us/hq-cloud`'s package entry (only `.`,
+// `./outposts*` and `./package.json` are exported), so a consumer cannot name
+// the class. Both signals below are computed from the value itself, mirroring
+// the style `environmental-error.ts` and `network-transport-error.ts` already
+// use.
+/**
+ * The `name` @indigoai-us/hq-cloud stamps on a state-store lock failure, and the
+ * prefix it puts on every such message (`super(\`state-store lock: ${message}\`)`).
+ * EITHER signal identifies the class. A unit test pins BOTH against the installed
+ * dependency so a future rename fails loudly in CI here rather than silently
+ * resuming Sentry noise.
+ */
+export const SYNC_STATE_LOCK_ERROR_NAME = "StateStoreLockError";
+export const SYNC_STATE_LOCK_MESSAGE_PREFIX = "state-store lock: ";
+/**
+ * The one `reason` hq-cloud treats as a DISTINCT internal condition rather than
+ * ordinary foreign contention: this process already holds the async scope lock,
+ * so a synchronous contender cannot spin without deadlocking the holder
+ * (state-store.ts's `in-process async holder for …`). That is same-process
+ * reentrancy — a condition HQ could actually fix — so it is NOT suppressed and
+ * stays on the captured path, exactly as hq-cloud's own sync-runner special-cases
+ * it.
+ */
+const IN_PROCESS_ASYNC_HOLDER_REASON = "in-process-async-holder";
+function isStateStoreLockError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return (err.name === SYNC_STATE_LOCK_ERROR_NAME ||
+        err.message.startsWith(SYNC_STATE_LOCK_MESSAGE_PREFIX));
+}
+/**
+ * If `err` is a LOCAL sync-state lock failure, return a short, input-free,
+ * actionable user-facing message; otherwise return `null`.
+ *
+ * A non-null result means the caller should PRINT the message, exit non-zero,
+ * and SKIP Sentry capture — the condition is another HQ process holding this
+ * machine's sync-state lock, not a bug HQ can fix. A null result means "handle
+ * this as usual (capture to Sentry)". The `in-process-async-holder` reason is
+ * deliberately excluded and still captures.
+ *
+ * The returned message never echoes the lock path or any other caller input, so
+ * the whole class groups as ONE Sentry-free condition instead of minting a new
+ * fingerprint per home directory. It is a fixed, bounded string, so no redaction
+ * or length cap is required.
+ */
+export function syncStateLockMessage(err) {
+    if (!isStateStoreLockError(err))
+        return null;
+    if (err.reason === IN_PROCESS_ASYNC_HOLDER_REASON)
+        return null;
+    return ("Another HQ process on this machine is holding the local sync state, so HQ " +
+        "could not update it. Wait for the other HQ sync to finish (or quit it), " +
+        "then run `hq sync` to finish syncing.");
+}
+//# sourceMappingURL=sync-state-lock-error.js.map

package/package.json

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