@indigoai-us/hq-cli 5.108.1 → 5.108.2

package/dist/utils/cognito-session.d.ts

@@ -18,8 +18,18 @@
  *   HQ_COGNITO_CALLBACK_PORT   — Loopback OAuth callback port
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
-import { loadCachedTokens, isExpiring, isMachineIdentity, type CognitoAuthConfig, type ClientInfo, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
+import { loadCachedTokens, isExpiring, isMachineIdentity, type CognitoAuthConfig, type CognitoTokens, type ClientInfo, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
 export { isExpiring, isMachineIdentity, loadCachedTokens };
+/** Person browser/login cache vs machine-creds USER_PASSWORD_AUTH mint. */
+export type CognitoTokenSource = "person" | "machine";
+/** Actor kind derived from the active token / machine-creds signal. */
+export type CognitoActorKind = "human" | "agent" | "unknown";
+/**
+ * Override for where machine-minted Cognito tokens are cached.
+ * Default: the work-mesh daemon state dir (`~/.hq/work-mesh/daemon`), so a
+ * machine mint never overwrites a person's `~/.hq/cognito-tokens.json`.
+ */
+export declare const HQ_MACHINE_TOKEN_STATE_DIR_ENV = "HQ_MACHINE_TOKEN_STATE_DIR";
 export declare const DEFAULT_COGNITO: CognitoAuthConfig;
 export declare const DEFAULT_VAULT_API_URL: string;
 /**
@@ -73,17 +83,85 @@ export declare function resolveDefaultHqRoot(opts?: {
     onMissing?: "throw" | "fallback";
 }): string;
 export declare const DEFAULT_HQ_ROOT: string;
+/**
+ * Directory used as `HQ_STATE_DIR` while minting/caching machine Cognito
+ * tokens. Never the person's `~/.hq` — agent boxes write under the daemon
+ * state dir so a mint cannot clobber a human login cache.
+ */
+export declare function machineTokenStateDir(home?: string, env?: NodeJS.ProcessEnv): string;
+/** Absolute path of the machine-token cache file (daemon state dir). */
+export declare function machineTokenCacheFile(home?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * True when `HQ_MACHINE_CREDS_FILE` is explicitly set (non-empty) in `env`.
+ * The mere presence of `~/.hq-agent/machine-creds.json` is NOT enough — minting
+ * and doctor "machine" reporting are opt-in via this env (systemd unit) or an
+ * explicit `{ tokenSource: "machine" }` caller option.
+ */
+export declare function isMachineCredsFileEnvSet(env?: NodeJS.ProcessEnv): boolean;
+export type EnsureCognitoTokenOptions = {
+    interactive?: boolean;
+    /**
+     * Force machine-credential minting (`"machine"`) or the person login cache
+     * (`"person"`). When omitted, machine minting is used only if
+     * `HQ_MACHINE_CREDS_FILE` is explicitly set and readable.
+     */
+    tokenSource?: CognitoTokenSource;
+};
+/**
+ * Whether this call should mint/cache via machine creds (USER_PASSWORD_AUTH).
+ * Opt-in only: explicit `{ tokenSource: "machine" }`, or `HQ_MACHINE_CREDS_FILE`
+ * set in the environment. Default-path `~/.hq-agent/machine-creds.json` alone
+ * never flips other CLI commands onto the machine path.
+ */
+export declare function wantsMachineCognitoTokens(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Which Cognito token source this process will use for doctor / reporting:
+ * machine only when `HQ_MACHINE_CREDS_FILE` is explicitly set and readable;
+ * otherwise the person login cache. Default-path machine-creds alone → person.
+ */
+export declare function resolveCognitoTokenSource(env?: NodeJS.ProcessEnv): CognitoTokenSource;
+/** Derive actor kind from an ID token's custom:entity* claims (no verify). */
+export declare function actorKindFromIdToken(idToken: string | undefined): CognitoActorKind;
+/**
+ * Peek the machine-token cache under the daemon state dir without minting.
+ * Used by doctor; never logs token material.
+ */
+export declare function loadMachineCachedTokens(home?: string, env?: NodeJS.ProcessEnv): CognitoTokens | null;
+/**
+ * Report token source + actor kind for `hq mesh daemon doctor`. Does not mint
+ * or hit the network. Machine identity without a readable cache still reports
+ * actorKind `agent` (the box identity signal).
+ */
+export declare function describeCognitoTokenSource(opts?: {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+}): {
+    tokenSource: CognitoTokenSource;
+    actorKind: CognitoActorKind;
+};
+/**
+ * Run `fn` with `HQ_STATE_DIR` pointed at the machine/daemon token cache so
+ * hq-cloud's mint writes never touch the person login file.
+ *
+ * When `HQ_STATE_DIR` is already set (tests / explicit callers), leave it alone
+ * so a pre-seeded machine session is still found — only redirect when unset.
+ */
+export declare function withMachineTokenStateDir<T>(fn: () => Promise<T>, opts?: {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<T>;
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in
- * as needed. Cache lives at ~/.hq/cognito-tokens.json.
+ * as needed. Person cache lives at ~/.hq/cognito-tokens.json. Machine minting
+ * is opt-in: `HQ_MACHINE_CREDS_FILE` explicitly set, or
+ * `{ tokenSource: "machine" }` — then USER_PASSWORD_AUTH and (when
+ * `HQ_STATE_DIR` is unset) a cache under the daemon state dir.
  *
  * Pass `interactive: false` from automated contexts (e.g. the `hq-auth-refresh`
  * bin invoked by the deploy skill) where failing fast is better than opening
  * a browser.
  */
-export declare function ensureCognitoToken(options?: {
-    interactive?: boolean;
-}): Promise<string>;
+export declare function ensureCognitoToken(options?: EnsureCognitoTokenOptions): Promise<string>;
 /**
  * Return a non-expired Cognito **ID** token (mirrors `ensureCognitoToken`'s
  * refresh/login flow but yields the id_token, not the access token).
@@ -95,9 +173,7 @@ export declare function ensureCognitoToken(options?: {
  * identities the vault API already authenticates with the ID token, so this is
  * identical to `ensureCognitoToken` there.
  */
-export declare function ensureCognitoIdToken(options?: {
-    interactive?: boolean;
-}): Promise<string>;
+export declare function ensureCognitoIdToken(options?: EnsureCognitoTokenOptions): Promise<string>;
 /**
  * The CLI's own ClientInfo. Resolved once at module load so every VaultClient
  * built in this process stamps the same name/version onto its requests.
@@ -117,7 +193,7 @@ export declare function buildVaultConfig(authToken: string): VaultServiceConfig;
  * means no valid session could be ensured non-interactively; the caller gets a
  * reason string and can decide what to do next. Never opens a browser.
  */
-export declare function refreshCachedSession(): Promise<{
+export declare function refreshCachedSession(options?: Pick<EnsureCognitoTokenOptions, "tokenSource">): Promise<{
     refreshed: boolean;
     reason?: string;
 }>;

package/dist/utils/cognito-session.js

@@ -25,9 +25,17 @@ import * as yaml from "js-yaml";
 import chalk from "chalk";
 import { loadCachedTokens, isExpiring, refreshTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
+import { daemonDir } from "../lib/mesh/live/daemon/paths.js";
+import { workMeshRoot } from "../lib/mesh/live/paths.js";
 // Re-export the cached-session primitives for callers that must deliberately
 // avoid the refresh/login behavior in the higher-level helpers below.
 export { isExpiring, isMachineIdentity, loadCachedTokens };
+/**
+ * Override for where machine-minted Cognito tokens are cached.
+ * Default: the work-mesh daemon state dir (`~/.hq/work-mesh/daemon`), so a
+ * machine mint never overwrites a person's `~/.hq/cognito-tokens.json`.
+ */
+export const HQ_MACHINE_TOKEN_STATE_DIR_ENV = "HQ_MACHINE_TOKEN_STATE_DIR";
 export const DEFAULT_COGNITO = {
     region: process.env.AWS_REGION ?? "us-east-1",
     userPoolDomain: process.env.HQ_COGNITO_DOMAIN ?? "vault-indigo-hq-prod",
@@ -223,9 +231,206 @@ function isHqRoot(dir) {
     }
 }
 export const DEFAULT_HQ_ROOT = resolveDefaultHqRoot();
+/**
+ * Directory used as `HQ_STATE_DIR` while minting/caching machine Cognito
+ * tokens. Never the person's `~/.hq` — agent boxes write under the daemon
+ * state dir so a mint cannot clobber a human login cache.
+ */
+export function machineTokenStateDir(home = os.homedir(), env = process.env) {
+    const override = env[HQ_MACHINE_TOKEN_STATE_DIR_ENV]?.trim();
+    if (override)
+        return override;
+    return daemonDir(workMeshRoot(home, env), home, env);
+}
+/** Absolute path of the machine-token cache file (daemon state dir). */
+export function machineTokenCacheFile(home = os.homedir(), env = process.env) {
+    return path.join(machineTokenStateDir(home, env), "cognito-tokens.json");
+}
+/**
+ * True when `HQ_MACHINE_CREDS_FILE` is explicitly set (non-empty) in `env`.
+ * The mere presence of `~/.hq-agent/machine-creds.json` is NOT enough — minting
+ * and doctor "machine" reporting are opt-in via this env (systemd unit) or an
+ * explicit `{ tokenSource: "machine" }` caller option.
+ */
+export function isMachineCredsFileEnvSet(env = process.env) {
+    const raw = env.HQ_MACHINE_CREDS_FILE;
+    return typeof raw === "string" && raw.trim().length > 0;
+}
+/**
+ * Whether this call should mint/cache via machine creds (USER_PASSWORD_AUTH).
+ * Opt-in only: explicit `{ tokenSource: "machine" }`, or `HQ_MACHINE_CREDS_FILE`
+ * set in the environment. Default-path `~/.hq-agent/machine-creds.json` alone
+ * never flips other CLI commands onto the machine path.
+ */
+export function wantsMachineCognitoTokens(options = {}, env = process.env) {
+    if (options.tokenSource === "person")
+        return false;
+    if (options.tokenSource === "machine") {
+        return isMachineIdentity();
+    }
+    if (!isMachineCredsFileEnvSet(env))
+        return false;
+    // Align process.env for hq-cloud's isMachineIdentity() when a synthetic env
+    // is supplied (doctor / tests).
+    const prevCreds = process.env.HQ_MACHINE_CREDS_FILE;
+    const nextCreds = env.HQ_MACHINE_CREDS_FILE;
+    if (nextCreds !== prevCreds) {
+        if (nextCreds === undefined)
+            delete process.env.HQ_MACHINE_CREDS_FILE;
+        else
+            process.env.HQ_MACHINE_CREDS_FILE = nextCreds;
+    }
+    try {
+        return isMachineIdentity();
+    }
+    finally {
+        if (nextCreds !== prevCreds) {
+            if (prevCreds === undefined)
+                delete process.env.HQ_MACHINE_CREDS_FILE;
+            else
+                process.env.HQ_MACHINE_CREDS_FILE = prevCreds;
+        }
+    }
+}
+/**
+ * Which Cognito token source this process will use for doctor / reporting:
+ * machine only when `HQ_MACHINE_CREDS_FILE` is explicitly set and readable;
+ * otherwise the person login cache. Default-path machine-creds alone → person.
+ */
+export function resolveCognitoTokenSource(env = process.env) {
+    return wantsMachineCognitoTokens({}, env) ? "machine" : "person";
+}
+function decodeJwtPayload(token) {
+    if (!token)
+        return null;
+    const parts = token.split(".");
+    if (parts.length < 2 || !parts[1])
+        return null;
+    try {
+        const json = Buffer.from(parts[1], "base64url").toString("utf8");
+        const parsed = JSON.parse(json);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Derive actor kind from an ID token's custom:entity* claims (no verify). */
+export function actorKindFromIdToken(idToken) {
+    const claims = decodeJwtPayload(idToken);
+    if (!claims)
+        return "unknown";
+    const entityType = claims["custom:entityType"];
+    const entityUid = claims["custom:entityUid"];
+    if (entityType === "agent" || (typeof entityUid === "string" && entityUid.startsWith("agt_"))) {
+        return "agent";
+    }
+    if (entityType === "outpost" || (typeof entityUid === "string" && entityUid.startsWith("out_"))) {
+        return "unknown";
+    }
+    return "human";
+}
+/**
+ * Peek the machine-token cache under the daemon state dir without minting.
+ * Used by doctor; never logs token material.
+ */
+export function loadMachineCachedTokens(home = os.homedir(), env = process.env) {
+    const file = machineTokenCacheFile(home, env);
+    try {
+        if (!fs.existsSync(file))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof raw.accessToken !== "string" ||
+            typeof raw.idToken !== "string" ||
+            raw.accessToken.length === 0 ||
+            raw.idToken.length === 0) {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Report token source + actor kind for `hq mesh daemon doctor`. Does not mint
+ * or hit the network. Machine identity without a readable cache still reports
+ * actorKind `agent` (the box identity signal).
+ */
+export function describeCognitoTokenSource(opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const env = opts.env ?? process.env;
+    const tokenSource = resolveCognitoTokenSource(env);
+    if (tokenSource === "machine") {
+        const cached = loadMachineCachedTokens(home, env);
+        const fromToken = actorKindFromIdToken(cached?.idToken);
+        return {
+            tokenSource,
+            actorKind: fromToken === "unknown" ? "agent" : fromToken,
+        };
+    }
+    // Honor HQ_STATE_DIR from the supplied env so doctor stays hermetic in tests.
+    const prevState = process.env.HQ_STATE_DIR;
+    const nextState = env.HQ_STATE_DIR;
+    if (nextState !== prevState) {
+        if (nextState === undefined)
+            delete process.env.HQ_STATE_DIR;
+        else
+            process.env.HQ_STATE_DIR = nextState;
+    }
+    try {
+        const person = loadCachedTokens();
+        return {
+            tokenSource,
+            actorKind: actorKindFromIdToken(person?.idToken),
+        };
+    }
+    finally {
+        if (nextState !== prevState) {
+            if (prevState === undefined)
+                delete process.env.HQ_STATE_DIR;
+            else
+                process.env.HQ_STATE_DIR = prevState;
+        }
+    }
+}
+/**
+ * Run `fn` with `HQ_STATE_DIR` pointed at the machine/daemon token cache so
+ * hq-cloud's mint writes never touch the person login file.
+ *
+ * When `HQ_STATE_DIR` is already set (tests / explicit callers), leave it alone
+ * so a pre-seeded machine session is still found — only redirect when unset.
+ */
+export async function withMachineTokenStateDir(fn, opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const env = opts.env ?? process.env;
+    const existing = env.HQ_STATE_DIR?.trim() || process.env.HQ_STATE_DIR?.trim() || "";
+    if (existing) {
+        return fn();
+    }
+    const prev = process.env.HQ_STATE_DIR;
+    process.env.HQ_STATE_DIR = machineTokenStateDir(home, env);
+    try {
+        return await fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.HQ_STATE_DIR;
+        else
+            process.env.HQ_STATE_DIR = prev;
+    }
+}
+async function ensureMachineTokens() {
+    return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO));
+}
 /**
  * Return a non-expired Cognito access token, refreshing or browser-logging-in
- * as needed. Cache lives at ~/.hq/cognito-tokens.json.
+ * as needed. Person cache lives at ~/.hq/cognito-tokens.json. Machine minting
+ * is opt-in: `HQ_MACHINE_CREDS_FILE` explicitly set, or
+ * `{ tokenSource: "machine" }` — then USER_PASSWORD_AUTH and (when
+ * `HQ_STATE_DIR` is unset) a cache under the daemon state dir.
  *
  * Pass `interactive: false` from automated contexts (e.g. the `hq-auth-refresh`
  * bin invoked by the deploy skill) where failing fast is better than opening
@@ -240,9 +445,10 @@ export async function ensureCognitoToken(options = {}) {
     // so vault-API calls from a machine identity send the ID token. The cached
     // token file keeps correct field semantics (real access token in
     // accessToken) for consumers that need token_use=access, e.g. the deploy
-    // API via the deploy skill.
-    if (isMachineIdentity()) {
-        const machine = await getValidMachineTokens(DEFAULT_COGNITO);
+    // API via the deploy skill. Cache path: daemon state dir when HQ_STATE_DIR
+    // is unset, never a silent overwrite of a person's ~/.hq.
+    if (wantsMachineCognitoTokens(options)) {
+        const machine = await ensureMachineTokens();
         return machine.idToken;
     }
     const cached = loadCachedTokens();
@@ -283,8 +489,8 @@ export async function ensureCognitoToken(options = {}) {
  */
 export async function ensureCognitoIdToken(options = {}) {
     const interactive = options.interactive ?? true;
-    if (isMachineIdentity()) {
-        const machine = await getValidMachineTokens(DEFAULT_COGNITO);
+    if (wantsMachineCognitoTokens(options)) {
+        const machine = await ensureMachineTokens();
         return machine.idToken;
     }
     const cached = loadCachedTokens();
@@ -342,12 +548,13 @@ export function buildVaultConfig(authToken) {
  * means no valid session could be ensured non-interactively; the caller gets a
  * reason string and can decide what to do next. Never opens a browser.
  */
-export async function refreshCachedSession() {
+export async function refreshCachedSession(options = {}) {
     // Machine identities have no refresh token; ensure a valid cached machine
     // session without forcing a re-mint when the cache is already healthy.
-    if (isMachineIdentity()) {
+    // Tokens land under the daemon state dir when HQ_STATE_DIR is unset.
+    if (wantsMachineCognitoTokens(options)) {
         try {
-            await getValidMachineTokens(DEFAULT_COGNITO);
+            await ensureMachineTokens();
             return { refreshed: true };
         }
         catch (err) {

package/dist/utils/qmd-model-download-error.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The actionable remedy shown to the caller. Input-free — nothing is
+ * interpolated from the error, the argv, or qmd's output — so there is no
+ * injection surface. The disposition holds for every reading of a vanished
+ * `.ipull` partial (a concurrent finisher, a cache eviction, a partially-written
+ * file): it is transient and retryable, and re-running resumes the download.
+ */
+export declare const QMD_MODEL_DOWNLOAD_REMEDY: string;
+/**
+ * True when `err` is a qmd interrupted-model-download failure: qmd's OWN captured
+ * streams carry BOTH an ENOENT-rename signature AND a `.ipull` partial-download
+ * marker. Requiring both keeps the gate narrow — a durable ENOSPC/EACCES/network
+ * failure matches neither the ENOENT code nor (for ENOSPC/EACCES) is it a
+ * transient race, so it stays a reportable QmdExitError. finishRunQmd calls this
+ * on the raw streams to type the condition {@link
+ * import('../lib/search-index/index.js').QmdModelDownloadError}.
+ */
+export declare function isQmdModelDownloadError(err: unknown): boolean;
+/**
+ * If `err` is a caller-/build-driven qmd model-download failure (a
+ * QmdModelDownloadError from `query`/`vsearch`/`embed`), return the actionable,
+ * input-free retry remedy; otherwise return `null`. Mirrors qmdLlmDisabledMessage
+ * so the top-level handler branches the same way: a non-null result means
+ * print-and-skip-Sentry, null means "handle as usual (capture to Sentry)".
+ */
+export declare function qmdModelDownloadMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-model-download-error.d.ts.map

package/dist/utils/qmd-model-download-error.js

@@ -0,0 +1,114 @@
+// src/utils/qmd-model-download-error.ts
+//
+// Classify a qmd failure caused by an INTERRUPTED MODEL DOWNLOAD — qmd crashed
+// with ENOENT while renaming its own partial `.ipull` download file into place —
+// rather than an hq-cli code defect. The partial file vanished before the rename
+// ran, the signature of ANOTHER qmd process on the same box finishing (or
+// clearing) the same download first. That is a transient, retryable LOCAL-CACHE
+// race hq cannot fix in code — hq cannot coordinate qmd children other users
+// start on the same host — so the CLI surfaces an actionable "re-run, it
+// resumes" remedy and SKIPS Sentry capture. Sibling of qmd-llm-disabled-error.ts
+// (HQ-CLI 7688850003) and qmd-store-missing-error.ts (HQ-CLI-16): a failure that
+// is NOT an hq-cli defect is printed with an actionable message and never filed
+// as a crash.
+//
+// HQ-CLI-1B (Sentry indigo-d0/hq-cli 7705711476, the newest event): `qmd query`
+// reached its reranking stage, its reranker-model downloader crashed uncaught
+// with `[Error: ENOENT: no such file or directory, rename '<cache>/…-reranker-…
+// .gguf.ipull' -> '<cache>/…-reranker-….gguf'] { errno: -2, code: 'ENOENT',
+// syscall: 'rename' }`, and qmd exited 1. hq-cli had no classifier for that
+// wording, so it took the same fall-through to capture as the query-document
+// crash — and because both share the (QmdExitError, qmd:query, exit:1)
+// fingerprint, an M1-only fix would leave this issue alive.
+//
+// The gate is deliberately narrow so it can neither be tripped by user input nor
+// silence a real bug:
+//   1. CLASS: only a QmdModelDownloadError (the typed subclass finishRunQmd
+//      raises) qualifies — never a plain QmdExitError carrying the same wording.
+//   2. INVOCATION: only the reads that fetch a model on demand — the caller
+//      reads query/vsearch (query expansion + reranking) and the index build
+//      embed. Any other subcommand returns null and stays captured.
+//   3. SIGNATURE: BOTH the ENOENT-rename shape AND the `.ipull` partial-download
+//      marker are required. A durable download failure (a full disk / ENOSPC, a
+//      permission error / EACCES, a network fault) has a DIFFERENT signature and
+//      stays a reportable QmdExitError, so this never silences a real fault.
+// The predicate reads qmd's OWN captured streams, never the synthesized message.
+/** ipull's suffix for an in-flight model download's partial file. */
+const IPULL_PARTIAL = /\.ipull\b/i;
+/** better-sqlite3-free: the ENOENT rename shape as qmd prints its MESSAGE form. */
+const ENOENT_RENAME_MESSAGE = /ENOENT:\s*no such file or directory,\s*rename/i;
+/** The ENOENT code/errno as the PROPERTIES form prints it (`code: 'ENOENT'` / `errno: -2`). */
+const ENOENT_TOKEN = /\bENOENT\b|errno:\s*-2\b/i;
+/** The rename syscall as the properties form prints it (`syscall: 'rename'`). */
+const RENAME_SYSCALL = /syscall:\s*['"]rename['"]/i;
+/** Reads that fetch a model on demand: query/vsearch expand + rerank, embed builds vectors. */
+const MODEL_FETCH_READS = new Set(["query", "vsearch", "embed"]);
+/**
+ * The actionable remedy shown to the caller. Input-free — nothing is
+ * interpolated from the error, the argv, or qmd's output — so there is no
+ * injection surface. The disposition holds for every reading of a vanished
+ * `.ipull` partial (a concurrent finisher, a cache eviction, a partially-written
+ * file): it is transient and retryable, and re-running resumes the download.
+ */
+export const QMD_MODEL_DOWNLOAD_REMEDY = "hq's local search couldn't finish downloading a model it needs: the partial " +
+    "download file disappeared before it could be saved, which usually means " +
+    "another hq or qmd process on this machine finished or cleared the same " +
+    "download. Re-run the command — the download resumes.";
+/**
+ * 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. A
+ * bare string is treated as captured text directly (test convenience). A value
+ * with no captured streams yields "".
+ */
+function capturedStreams(err) {
+    if (typeof err === "string")
+        return 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 || stdout ? `${stderr}\n${stdout}` : "";
+}
+/** True when `text` carries an ENOENT rename, in either qmd's message or props form. */
+function hasEnoentRename(text) {
+    if (ENOENT_RENAME_MESSAGE.test(text))
+        return true;
+    return ENOENT_TOKEN.test(text) && RENAME_SYSCALL.test(text);
+}
+/**
+ * True when `err` is a qmd interrupted-model-download failure: qmd's OWN captured
+ * streams carry BOTH an ENOENT-rename signature AND a `.ipull` partial-download
+ * marker. Requiring both keeps the gate narrow — a durable ENOSPC/EACCES/network
+ * failure matches neither the ENOENT code nor (for ENOSPC/EACCES) is it a
+ * transient race, so it stays a reportable QmdExitError. finishRunQmd calls this
+ * on the raw streams to type the condition {@link
+ * import('../lib/search-index/index.js').QmdModelDownloadError}.
+ */
+export function isQmdModelDownloadError(err) {
+    const text = capturedStreams(err);
+    if (!text)
+        return false;
+    return hasEnoentRename(text) && IPULL_PARTIAL.test(text);
+}
+/**
+ * If `err` is a caller-/build-driven qmd model-download failure (a
+ * QmdModelDownloadError from `query`/`vsearch`/`embed`), return the actionable,
+ * input-free retry remedy; otherwise return `null`. Mirrors qmdLlmDisabledMessage
+ * so the top-level handler branches the same way: a non-null result means
+ * print-and-skip-Sentry, null means "handle as usual (capture to Sentry)".
+ */
+export function qmdModelDownloadMessage(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "QmdModelDownloadError")
+        return null;
+    const args = Array.isArray(record.args) ? record.args : [];
+    const subcommand = args[0];
+    if (typeof subcommand !== "string" || !MODEL_FETCH_READS.has(subcommand))
+        return null;
+    return QMD_MODEL_DOWNLOAD_REMEDY;
+}
+//# sourceMappingURL=qmd-model-download-error.js.map

package/dist/utils/qmd-query-document-error.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The actionable remedy shown to the caller. Input-free: nothing is interpolated
+ * from the error, the argv, or qmd's output, so there is no injection surface —
+ * matching the bounded-fingerprint discipline of its siblings.
+ */
+export declare const QMD_QUERY_DOCUMENT_REMEDY: string;
+/**
+ * True when `err` carries, in qmd's OWN captured streams, a query-document
+ * syntax diagnostic — i.e. qmd's `query` parser rejected the positional as a
+ * malformed document. finishRunQmd calls this on the raw streams to type the
+ * condition {@link import('../lib/search-index/index.js').QmdQueryDocumentError}.
+ */
+export declare function isQmdQueryDocumentError(err: unknown): boolean;
+/**
+ * If `err` is a caller-driven qmd query-document failure (a QmdQueryDocumentError
+ * from `hq search --mode hybrid`, i.e. the `query` read), return the actionable,
+ * input-free remedy; otherwise return `null`. Mirrors qmdLlmDisabledMessage /
+ * qmdModuleMissingMessage so the top-level handler branches the same way: a
+ * non-null result means print-and-skip-Sentry, null means "handle as usual
+ * (capture to Sentry)".
+ */
+export declare function qmdQueryDocumentMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-query-document-error.d.ts.map