@indigoai-us/hq-cli 5.108.1 → 5.108.3

package/dist/lib/work-context/repo-remote.js

@@ -0,0 +1,200 @@
+/**
+ * Deterministic company ownership from the enclosing git remote (US-007A).
+ *
+ * Walks up from cwd to find a .git dir/file, reads origin's URL from .git/config
+ * (no git subprocess), normalises to owner/name, and matches against
+ * companies/manifest.yaml repos. Zero or multiple matches → no signal.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseUserYaml } from "../../utils/user-yaml-error.js";
+/**
+ * Normalise a git remote URL to `owner/name`.
+ * Handles https://github.com/owner/name(.git), git@github.com:owner/name(.git),
+ * and ssh://git@github.com/owner/name(.git). Returns null when unrecognised.
+ */
+export function normalizeRemoteOwnerName(remoteUrl) {
+    const raw = remoteUrl.trim();
+    if (!raw)
+        return null;
+    let owner = "";
+    let name = "";
+    const scp = /^git@([^:]+):(.+)$/i.exec(raw);
+    if (scp) {
+        const rest = scp[2].replace(/\/+$/, "").replace(/\.git$/i, "");
+        const parts = rest.split("/").filter(Boolean);
+        if (parts.length >= 2) {
+            owner = parts[parts.length - 2];
+            name = parts[parts.length - 1];
+        }
+    }
+    else {
+        try {
+            const withScheme = /^[a-z+]+:\/\//i.test(raw) ? raw : `https://${raw}`;
+            const u = new URL(withScheme);
+            const parts = u.pathname
+                .replace(/\/+$/, "")
+                .replace(/\.git$/i, "")
+                .split("/")
+                .filter(Boolean);
+            if (parts.length >= 2) {
+                owner = parts[parts.length - 2];
+                name = parts[parts.length - 1];
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!owner || !name)
+        return null;
+    if (!/^[A-Za-z0-9._-]+$/.test(owner) || !/^[A-Za-z0-9._-]+$/.test(name)) {
+        return null;
+    }
+    return `${owner}/${name}`;
+}
+/** Walk up from startDir looking for a `.git` directory or file. */
+export function findEnclosingGitDir(startDir) {
+    let cur = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(cur, ".git");
+        try {
+            if (fs.existsSync(candidate)) {
+                const st = fs.lstatSync(candidate);
+                if (st.isDirectory())
+                    return candidate;
+                if (st.isFile()) {
+                    // Linked worktree: `.git` file contains `gitdir: <path>`
+                    const text = fs.readFileSync(candidate, "utf8");
+                    const m = /^\s*gitdir:\s*(.+)\s*$/m.exec(text);
+                    if (m?.[1]) {
+                        const gitdir = path.resolve(cur, m[1].trim());
+                        if (fs.existsSync(gitdir))
+                            return gitdir;
+                    }
+                    return null;
+                }
+            }
+        }
+        catch {
+            return null;
+        }
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            return null;
+        cur = parent;
+    }
+}
+/**
+ * Read `remote.origin.url` from a `.git/config` (ini-style). No subprocess.
+ */
+export function readOriginRemoteUrl(gitDir) {
+    const configPath = path.join(gitDir, "config");
+    if (!fs.existsSync(configPath))
+        return null;
+    let text;
+    try {
+        text = fs.readFileSync(configPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let inOrigin = false;
+    for (const line of text.split(/\r?\n/)) {
+        const section = /^\s*\[([^\]]+)\]\s*$/.exec(line);
+        if (section) {
+            inOrigin = /^remote\s+"origin"$/i.test(section[1].trim());
+            continue;
+        }
+        if (!inOrigin)
+            continue;
+        const url = /^\s*url\s*=\s*(.+?)\s*$/i.exec(line);
+        if (url?.[1])
+            return url[1].trim();
+    }
+    return null;
+}
+/**
+ * Match normalised `owner/name` against companies/manifest repos.
+ * A repo entry matches if it equals owner/name (case-insensitive) or is a URL
+ * that normalises to the same owner/name. Exactly one company → its slug;
+ * zero or more than one → null.
+ */
+export function matchCompanySlugForRepo(ownerName, companies) {
+    const target = ownerName.trim().toLowerCase();
+    if (!target || !target.includes("/"))
+        return null;
+    const matches = [];
+    for (const [slug, entry] of Object.entries(companies)) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const repos = entry.repos;
+        if (!Array.isArray(repos))
+            continue;
+        for (const raw of repos) {
+            if (typeof raw !== "string" || !raw.trim())
+                continue;
+            const trimmed = raw.trim();
+            let candidate = null;
+            if (trimmed.includes("://") ||
+                trimmed.startsWith("git@") ||
+                /@[^/]+:/.test(trimmed)) {
+                candidate = normalizeRemoteOwnerName(trimmed);
+            }
+            else if (trimmed.includes("/")) {
+                candidate = trimmed.replace(/\.git$/i, "");
+            }
+            if (candidate && candidate.toLowerCase() === target) {
+                matches.push(slug);
+                break;
+            }
+        }
+    }
+    if (matches.length === 1)
+        return matches[0];
+    return null;
+}
+export function readCompaniesManifestMap(hqRoot) {
+    const mPath = path.join(hqRoot, "companies", "manifest.yaml");
+    if (!fs.existsSync(mPath))
+        return null;
+    try {
+        const parsed = parseUserYaml(fs.readFileSync(mPath, "utf8"), mPath);
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            !("companies" in parsed) ||
+            typeof parsed.companies !== "object" ||
+            parsed.companies === null) {
+            return null;
+        }
+        return parsed.companies;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Derive the deterministic remote-owner company slug from cwd + HQ manifest.
+ * Returns null when there is no unique match.
+ */
+export function deriveRemoteOwnerSlug(opts) {
+    const cwd = opts.cwd?.trim() ? path.resolve(opts.cwd) : process.cwd();
+    const hqRoot = opts.hqRoot?.trim() ? path.resolve(opts.hqRoot) : undefined;
+    if (!hqRoot)
+        return null;
+    const gitDir = findEnclosingGitDir(cwd);
+    if (!gitDir)
+        return null;
+    const origin = readOriginRemoteUrl(gitDir);
+    if (!origin)
+        return null;
+    const ownerName = normalizeRemoteOwnerName(origin);
+    if (!ownerName)
+        return null;
+    const reader = opts.readManifest ?? readCompaniesManifestMap;
+    const companies = reader(hqRoot);
+    if (!companies)
+        return null;
+    return matchCompanySlugForRepo(ownerName, companies);
+}
+//# sourceMappingURL=repo-remote.js.map

package/dist/lib/work-context/state.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Per-session local state file: ~/.hq/work-context/sessions/<sid>.json
+ * Written only by hq mesh context. Owner 0600. Metadata-only — never prompts/tokens.
+ */
+import type { ClassificationState } from "./contract.js";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
+export type DecisionOptionKind = "bind_existing" | "create_project" | "create_task" | "untracked" | "keep_default" | "override_evidence";
+export interface SessionDecisionOption {
+    optionId: string;
+    label?: string;
+    kind?: DecisionOptionKind;
+    projectId?: string;
+    taskId?: string;
+}
+export interface SessionDecision {
+    decisionId: string;
+    options: SessionDecisionOption[];
+    expiresAt?: string;
+    /**
+     * When true, UserPromptSubmit injects a one-time clarification (US-007B/US-010).
+     * Set only after work-signal threshold; never re-armed after cancel/timeout.
+     */
+    askAfter?: boolean;
+    /** US-017B correction pointer when company_conflict follows an existing binding. */
+    correctionPath?: string;
+}
+/** Local-only origin of the session state writer (never sent on the wire). */
+export type SessionEventSource = "hook" | "transcript";
+/** Local-only harness label when network schema cannot carry it (US-018). */
+export type LocalHarnessLabel = "claude-desktop" | "codex";
+/** Local tracking for an in-flight or completed cross-company migrate (US-017B). */
+export interface SessionMigrationRecord {
+    operationId: string;
+    digest: string;
+    sourceCompanyUid: string;
+    destinationCompanyUid: string;
+    destinationCompanySlug?: string;
+    destination?: {
+        projectId?: string;
+        taskId?: string;
+    };
+    submittedAt: string;
+    /** Set when the destination receipt arrives. */
+    receiptId?: string;
+    completedAt?: string;
+}
+export interface SessionStateFile {
+    contractVersion: typeof WORK_CONTEXT_CONTRACT_VERSION;
+    sessionId: string;
+    companyUid?: string;
+    companySlug?: string;
+    contextStatus: ClassificationState;
+    projectId?: string;
+    taskId?: string;
+    bindingEpisodeId?: string;
+    /** Binding / session OCC version from the last server receipt. */
+    version?: number;
+    decision?: SessionDecision;
+    /** Cross-company migrate tracking (pending until receiptId is set). */
+    migration?: SessionMigrationRecord;
+    /** Local consent receipt for explicit untracked. */
+    untrackedReceipt?: {
+        origin: "user";
+        at: string;
+        noBackfill: true;
+    };
+    /**
+     * LOCAL-ONLY. Count of file-writing tools (Edit/Write/MultiEdit/NotebookEdit/
+     * file-writing Bash) bumped by PostToolUse (US-010). Used for askAfter.
+     */
+    toolWrites?: number;
+    /** LOCAL-ONLY. First observe/register time for the 10-minute ask threshold. */
+    startedAt?: string;
+    /** LOCAL-ONLY. True once any turn has been observed for this session. */
+    hasTurn?: boolean;
+    /**
+     * LOCAL-ONLY. How this state was established. Hook path (US-007A/US-010) omits
+     * this or sets "hook". Transcript-watch fallback sets "transcript" (US-018).
+     * Distinct from the network SessionEvent `source` enum (`hooks` | `transcript`).
+     */
+    source?: SessionEventSource;
+    /**
+     * LOCAL-ONLY legacy label. AMEND-001 put `claude-desktop` on the network
+     * harness enum; transcript-watch no longer writes this.
+     */
+    localHarness?: LocalHarnessLabel;
+    /**
+     * LOCAL-ONLY. Channel-card / Atlas marker for transcript-sourced sessions
+     * before SESSION_STATE sync (kept after AMEND-001).
+     */
+    transcriptMarker?: "from transcript";
+    updatedAt: string;
+}
+/** Allowlisted keys that may appear in the durable state projection. */
+export declare const SESSION_STATE_ALLOWLIST: Set<string>;
+export declare function readSessionState(sessionId: string, root: string): SessionStateFile | null;
+export declare function writeSessionState(state: SessionStateFile, root: string): string;
+/** Strip any non-allowlisted fields before durable write. */
+export declare function projectSessionState(state: SessionStateFile): SessionStateFile;
+/**
+ * Merge prior local-only counters into a new state write so PostToolUse bumps
+ * and reconcile updates do not clobber each other.
+ */
+export declare function mergeLocalSessionFields(next: SessionStateFile, prior: SessionStateFile | null): SessionStateFile;
+/** True when a durable state file was written by the hook / reconcile path. */
+export declare function isHookWrittenSessionState(state: SessionStateFile | null): boolean;
+/** Authoritative prior scope usable for company precedence. */
+export declare function authoritativeCompanyFromState(state: SessionStateFile | null): {
+    slug?: string;
+    uid?: string;
+} | null;
+//# sourceMappingURL=state.d.ts.map

package/dist/lib/work-context/state.js

@@ -0,0 +1,162 @@
+/**
+ * Per-session local state file: ~/.hq/work-context/sessions/<sid>.json
+ * Written only by hq mesh context. Owner 0600. Metadata-only — never prompts/tokens.
+ */
+import * as fs from "node:fs";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
+import { atomicWriteJson, ensureOwnerDir } from "./atomic.js";
+import { NotTrackingError } from "./errors.js";
+import { isSafeWorkContextSegment, workContextSessionPath, workContextSessionsDir, } from "./paths.js";
+/** Allowlisted keys that may appear in the durable state projection. */
+export const SESSION_STATE_ALLOWLIST = new Set([
+    "contractVersion",
+    "sessionId",
+    "companyUid",
+    "companySlug",
+    "contextStatus",
+    "projectId",
+    "taskId",
+    "bindingEpisodeId",
+    "version",
+    "decision",
+    "migration",
+    "untrackedReceipt",
+    "toolWrites",
+    "startedAt",
+    "hasTurn",
+    "source",
+    "localHarness",
+    "transcriptMarker",
+    "updatedAt",
+]);
+export function readSessionState(sessionId, root) {
+    if (!isSafeWorkContextSegment(sessionId))
+        return null;
+    const filePath = workContextSessionPath(sessionId, root);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        if (raw.sessionId !== sessionId)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSessionState(state, root) {
+    if (!isSafeWorkContextSegment(state.sessionId)) {
+        throw new NotTrackingError(`Unsafe session id for state file: ${state.sessionId}`, "NOT_TRACKING");
+    }
+    const projected = projectSessionState(state);
+    try {
+        ensureOwnerDir(workContextSessionsDir(root));
+        const dest = workContextSessionPath(state.sessionId, root);
+        atomicWriteJson(dest, projected);
+        return dest;
+    }
+    catch (err) {
+        throw new NotTrackingError(`Failed to persist session state: ${err instanceof Error ? err.message : String(err)}`, "NOT_TRACKING");
+    }
+}
+/** Strip any non-allowlisted fields before durable write. */
+export function projectSessionState(state) {
+    const out = {
+        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+        sessionId: state.sessionId,
+        contextStatus: state.contextStatus,
+        updatedAt: state.updatedAt,
+    };
+    if (state.companyUid)
+        out.companyUid = state.companyUid;
+    if (state.companySlug)
+        out.companySlug = state.companySlug;
+    if (state.projectId)
+        out.projectId = state.projectId;
+    if (state.taskId)
+        out.taskId = state.taskId;
+    if (state.bindingEpisodeId)
+        out.bindingEpisodeId = state.bindingEpisodeId;
+    if (typeof state.version === "number" && Number.isInteger(state.version)) {
+        out.version = state.version;
+    }
+    if (state.decision)
+        out.decision = state.decision;
+    if (state.migration)
+        out.migration = state.migration;
+    if (state.untrackedReceipt)
+        out.untrackedReceipt = state.untrackedReceipt;
+    if (typeof state.toolWrites === "number" && state.toolWrites >= 0) {
+        out.toolWrites = Math.floor(state.toolWrites);
+    }
+    if (state.startedAt)
+        out.startedAt = state.startedAt;
+    if (state.hasTurn)
+        out.hasTurn = true;
+    if (state.source)
+        out.source = state.source;
+    if (state.localHarness)
+        out.localHarness = state.localHarness;
+    if (state.transcriptMarker)
+        out.transcriptMarker = state.transcriptMarker;
+    return out;
+}
+/**
+ * Merge prior local-only counters into a new state write so PostToolUse bumps
+ * and reconcile updates do not clobber each other.
+ */
+export function mergeLocalSessionFields(next, prior) {
+    if (!prior)
+        return next;
+    const out = { ...next };
+    if (out.toolWrites === undefined && typeof prior.toolWrites === "number") {
+        out.toolWrites = prior.toolWrites;
+    }
+    if (!out.startedAt && prior.startedAt)
+        out.startedAt = prior.startedAt;
+    if (!out.hasTurn && prior.hasTurn)
+        out.hasTurn = true;
+    // Preserve an existing one-time decision unless the caller replaces it.
+    if (!out.decision && prior.decision)
+        out.decision = prior.decision;
+    if (!out.untrackedReceipt && prior.untrackedReceipt) {
+        out.untrackedReceipt = prior.untrackedReceipt;
+    }
+    if (!out.source && prior.source)
+        out.source = prior.source;
+    if (!out.localHarness && prior.localHarness) {
+        out.localHarness = prior.localHarness;
+    }
+    if (!out.transcriptMarker && prior.transcriptMarker) {
+        out.transcriptMarker = prior.transcriptMarker;
+    }
+    if (!out.bindingEpisodeId && prior.bindingEpisodeId) {
+        out.bindingEpisodeId = prior.bindingEpisodeId;
+    }
+    return out;
+}
+/** True when a durable state file was written by the hook / reconcile path. */
+export function isHookWrittenSessionState(state) {
+    if (!state)
+        return false;
+    return state.source !== "transcript";
+}
+/** Authoritative prior scope usable for company precedence. */
+export function authoritativeCompanyFromState(state) {
+    if (!state)
+        return null;
+    const writable = new Set([
+        "unresolved",
+        "needs_project",
+        "needs_task",
+        "bound",
+        "migration_pending",
+    ]);
+    if (!writable.has(state.contextStatus))
+        return null;
+    if (!state.companyUid && !state.companySlug)
+        return null;
+    return { slug: state.companySlug, uid: state.companyUid };
+}
+//# sourceMappingURL=state.js.map

package/dist/main.js

@@ -73,6 +73,9 @@ import { qmdLlmDisabledMessage } from "./utils/qmd-llm-disabled-error.js";
 import { qmdModuleMissingMessage } from "./utils/qmd-module-missing-error.js";
 import { qmdStoreMissingMessage } from "./utils/qmd-store-missing-error.js";
 import { qmdStoreUnopenableMessage } from "./utils/qmd-store-unopenable-error.js";
+import { qmdQueryDocumentMessage } from "./utils/qmd-query-document-error.js";
+import { qmdModelDownloadMessage } from "./utils/qmd-model-download-error.js";
+import { qmdWorkdirMissingMessage } from "./utils/qmd-workdir-missing-error.js";
 import { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isVarlockEnvError } from "./run/env-graph-guard.js";
@@ -377,6 +380,26 @@ const defaultTopLevelErrorDependencies = {
         process.exitCode = code;
     },
 };
+/**
+ * Bounded Sentry context for a CAPTURED qmd spawn-level failure (the
+ * interpreter-missing and residual QmdBinaryMissingError cases). finishRunQmd
+ * stamps the errno code and per-component existence booleans onto the error at
+ * failure time; because the reporting host (HQ-CLI-1A) shipped no platform log,
+ * this is the evidence the next occurrence carries. Read STRUCTURALLY off the
+ * error's own `spawnDiagnostics` field (the boundary reconstructs typed carriers
+ * structurally in tests). Only hq-DERIVED paths (the resolved cwd,
+ * process.execPath, the bundled launcher) and a bounded errno code appear —
+ * never caller argv or query text. Returns undefined when the error carries no
+ * such diagnostics, so the generic capture stays a bare captureException(err).
+ */
+function qmdSpawnFailureCaptureContext(err) {
+    if (err === null || typeof err !== "object")
+        return undefined;
+    const diagnostics = err.spawnDiagnostics;
+    if (diagnostics === null || typeof diagnostics !== "object")
+        return undefined;
+    return { contexts: { qmd_spawn_failure: diagnostics } };
+}
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export async function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies) {
     // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
@@ -599,6 +622,50 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         const storeUnopenableMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg
             ? null
             : qmdStoreUnopenableMessage(err);
+        // A qmd `query` (hybrid search) failure whose positional was rejected as a
+        // MALFORMED QUERY DOCUMENT — qmd 2.5.3 requires a lex:/vec:/hyde:/intent:/
+        // expand: prefix on every line of a multi-line document — is the caller's
+        // INPUT SHAPE, not an hq-cli defect. The common case (a fleet agent
+        // forwarding a whole multi-line Slack message) is normalised to one line in
+        // buildSearchArgs so it never reaches qmd multi-line; this branch is the
+        // backstop for a genuinely malformed structured document. finishRunQmd types
+        // it QmdQueryDocumentError; print the query-free remedy and skip capture
+        // (HQ-CLI-1B / Sentry 7705711476, 28 of 29 events). Scoped to the `query`
+        // read. Evaluated AFTER the earlier qmd typed signatures and BEFORE the
+        // environmental / transport / generic branches; the wordings are disjoint,
+        // so ordering changes no existing branch.
+        const queryDocumentMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg
+            ? null
+            : qmdQueryDocumentMessage(err);
+        // A qmd MODEL DOWNLOAD that died with ENOENT renaming its own partial
+        // `.ipull` file is a transient LOCAL-CACHE race (another qmd process on the
+        // same box finished or cleared the same download first), not an hq-cli
+        // defect — hq cannot coordinate qmd children other users start on the host.
+        // finishRunQmd types it QmdModelDownloadError (gated on BOTH the ENOENT
+        // rename signature AND the .ipull marker, so a durable ENOSPC/EACCES/network
+        // failure stays reportable); print the retry remedy and skip capture
+        // (HQ-CLI-1B / Sentry 7705711476, the newest event). Scoped to the reads
+        // that fetch a model (query/vsearch/embed).
+        const modelDownloadMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg
+            ? null
+            : qmdModelDownloadMessage(err);
+        // A qmd spawn-level failure whose ENOENT was a MISSING WORKING DIRECTORY
+        // (the resolved hq root the qmd child was handed as `cwd` does not exist).
+        // finishRunQmd types it QmdWorkdirMissingError, carrying the hq-derived
+        // directory; the boundary prints a self-describing remedy naming that
+        // directory and skips capture — a working directory that does not exist is
+        // the caller's filesystem, the same disposition as the store-missing /
+        // store-unopenable branches. Before this branch it was MISATTRIBUTED to a
+        // missing qmd (QmdBinaryMissingError, remedy `Install @tobilu/qmd`) and,
+        // with no boundary branch for it, captured as a crash (HQ-CLI-1A, Sentry
+        // 7705642434). Evaluated immediately AFTER the store-unopenable /
+        // query-document / model-download checks and BEFORE the environmental /
+        // transport / generic branches; the carrier's name is disjoint from every
+        // neighbour and it carries no `.code` environmentalFsErrorMessage could
+        // read, so ordering changes no existing branch.
+        const workdirMissingMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg
+            ? null
+            : qmdWorkdirMissingMessage(err);
         // An hq STATE-TREE write that failed for an environmental errno
         // (permission/quota/read-only/parent-gone) is typed at the write site as an
         // HqStateWriteError carrying the exact hq-DERIVED path it tried to write.
@@ -608,10 +675,10 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // remedy and skip capture. Placed with the environmental-fs family — BEFORE
         // the generic envMsg computation — so this typed carrier wins even though
         // it also carries an errno `code` environmentalFsErrorMessage could read.
-        const stateWriteMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg
+        const stateWriteMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg
             ? null
             : hqStateWriteErrorMessage(err);
-        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || stateWriteMsg
+        const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg
             ? null
             : environmentalFsErrorMessage(err);
         // A LOCAL sync-state lock failure (@indigoai-us/hq-cloud's
@@ -628,7 +695,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // environmental-fs check, before network-transport — is pinned by tests.
         // The `in-process-async-holder` reason is deliberately NOT suppressed here
         // (see sync-state-lock-error.ts); it stays captured.
-        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || stateWriteMsg || envMsg
+        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg || envMsg
             ? null
             : syncStateLockMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
@@ -648,6 +715,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             moduleMissingMsg ||
             storeMissingMsg ||
             storeUnopenableMsg ||
+            queryDocumentMsg ||
+            modelDownloadMsg ||
+            workdirMissingMsg ||
             stateWriteMsg ||
             envMsg ||
             lockMsg
@@ -674,6 +744,15 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (storeUnopenableMsg) {
             deps.stderr.write(`hq: ${storeUnopenableMsg}\n`);
         }
+        else if (queryDocumentMsg) {
+            deps.stderr.write(`hq: ${queryDocumentMsg}\n`);
+        }
+        else if (modelDownloadMsg) {
+            deps.stderr.write(`hq: ${modelDownloadMsg}\n`);
+        }
+        else if (workdirMissingMsg) {
+            deps.stderr.write(`hq: ${workdirMissingMsg}\n`);
+        }
         else if (stateWriteMsg) {
             deps.stderr.write(`hq: ${stateWriteMsg}\n`);
         }
@@ -687,7 +766,17 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             deps.stderr.write(`hq: ${transportMsg}\n`);
         }
         else {
-            deps.sentry.captureException(err);
+            // A genuinely unclassified fault is still captured exactly once. When it
+            // is a qmd spawn-level failure the fix could not attribute, attach the
+            // bounded existence context so the next occurrence carries the evidence
+            // the reported HQ-CLI-1A event lacked; every other error captures bare.
+            const spawnContext = qmdSpawnFailureCaptureContext(err);
+            if (spawnContext) {
+                deps.sentry.captureException(err, spawnContext);
+            }
+            else {
+                deps.sentry.captureException(err);
+            }
             // Always emit something. Printing only when unexpectedCliErrorMessage()
             // returned a value meant every error class except IntegrationsCliError
             // exited 1 with zero bytes on stdout AND stderr — a silent failure the