@indigoai-us/hq-cli 5.108.1 → 5.108.3

package/dist/lib/mesh/live/validate-session-event.js

@@ -0,0 +1,128 @@
+/**
+ * Work Mesh Live — session-event validator (US-001).
+ *
+ * Uses Ajv draft 2020-12 against the verbatim schema copy. Prohibited content
+ * classes are rejected (additionalProperties: false). Error messages never
+ * echo prohibited marker values (redaction assertion surface).
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const SESSION_EVENT_SCHEMA_PATH = join(HERE, "session-event.schema.json");
+/** Expected SHA-256 of the canonical schema bytes (hq-pro + hq-cli must match). */
+export const SESSION_EVENT_SCHEMA_SHA256 = "be300120b4793a5c6f1e713bf9f72b2fd22f6ac082bef8eedfa507b684b09ccb";
+export const PROHIBITED_CONTENT_CLASSES = [
+    "prompts",
+    "model_output",
+    "transcripts",
+    "message_bodies",
+    "tokens",
+    "credentials",
+];
+/** Fixture field name → prohibited class. */
+export const PROHIBITED_FIELD_BY_CLASS = {
+    prompts: "prompt",
+    model_output: "modelOutput",
+    transcripts: "transcript",
+    message_bodies: "messageBody",
+    tokens: "token",
+    credentials: "credentials",
+};
+const REDACT_MARKERS = [
+    "REDACT_MARKER_PROMPT_",
+    "REDACT_MARKER_MODEL_OUTPUT_",
+    "REDACT_MARKER_TRANSCRIPT_",
+    "REDACT_MARKER_MESSAGE_BODY_",
+    "REDACT_MARKER_TOKEN_",
+    "REDACT_MARKER_CREDENTIALS_",
+];
+let cachedValidate;
+function loadSchema() {
+    return JSON.parse(readFileSync(SESSION_EVENT_SCHEMA_PATH, "utf8"));
+}
+export function getSessionEventValidator() {
+    if (cachedValidate)
+        return cachedValidate;
+    const ajv = new Ajv2020({
+        allErrors: true,
+        strict: false,
+        validateFormats: false,
+    });
+    cachedValidate = ajv.compile(loadSchema());
+    return cachedValidate;
+}
+/**
+ * Redact known prohibited markers from Ajv error text so diagnostics never
+ * leak prompt/token/credential material.
+ */
+export function redactValidationMessage(message) {
+    let out = message;
+    for (const marker of REDACT_MARKERS) {
+        if (out.includes(marker)) {
+            out = out.split(marker)[0] + "[REDACTED]";
+        }
+    }
+    // Also strip any bearer-shaped or op:// fragments that slipped through.
+    out = out.replace(/Bearer\s+[A-Za-z0-9._-]+/gi, "Bearer [REDACTED]");
+    out = out.replace(/op:\/\/[^\s"]+/g, "op://[REDACTED]");
+    return out;
+}
+function formatErrors(errors) {
+    if (!errors || errors.length === 0)
+        return ["validation_failed"];
+    return errors.map((e) => {
+        const path = e.instancePath || "/";
+        const msg = e.message ?? "invalid";
+        return redactValidationMessage(`${path}: ${msg}`);
+    });
+}
+export function validateSessionEvent(candidate) {
+    const validate = getSessionEventValidator();
+    const ok = validate(candidate);
+    if (ok)
+        return { ok: true, errors: [] };
+    return { ok: false, errors: formatErrors(validate.errors) };
+}
+export function sha256File(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+export function sha256SessionEventSchema() {
+    return sha256File(SESSION_EVENT_SCHEMA_PATH);
+}
+const HQ_PRO_SCHEMA_RELATIVE = "src/vault-service/work-mesh/live/session-event.schema.json";
+/** Walk up from `start` until a directory containing package.json is found. */
+function findRepoRoot(start) {
+    let dir = start;
+    for (;;) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Resolve the hq-pro canonical schema path when available.
+ *
+ * Order: `HQ_PRO_SCHEMA_PATH` env override (absolute path to the hq-pro
+ * schema file) → sibling checkout
+ * `../hq-pro/src/vault-service/work-mesh/live/session-event.schema.json`
+ * from the hq-cli repo root → null.
+ * Shipped code must not hardcode machine-specific worktree paths.
+ */
+export function resolveHqProSchemaPath() {
+    const envPath = process.env.HQ_PRO_SCHEMA_PATH?.trim();
+    if (envPath) {
+        return isAbsolute(envPath) ? envPath : resolve(envPath);
+    }
+    const repoRoot = findRepoRoot(HERE);
+    if (!repoRoot)
+        return null;
+    const sibling = resolve(repoRoot, "..", "hq-pro", HQ_PRO_SCHEMA_RELATIVE);
+    return existsSync(sibling) ? sibling : null;
+}
+//# sourceMappingURL=validate-session-event.js.map

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

@@ -38,6 +38,25 @@ export type QmdInvocation = {
     prefixArgs: string[];
     execDir?: string;
 };
+/**
+ * Bounded, hq-DERIVED evidence stamped onto a CAPTURED qmd spawn-level failure
+ * (the interpreter-missing and residual QmdBinaryMissingError cases). The
+ * reporting host (HQ-CLI-1A) shipped no platform log, so spawnSync's ENOENT
+ * could not be pinned to a missing command vs. a missing working directory. The
+ * boundary forwards this into a bounded Sentry context so the NEXT occurrence
+ * carries the evidence this one lacked. Every field is hq-derived — the errno
+ * code, the resolved `cwd`, `process.execPath`, the bundled launcher, and their
+ * existence at failure time — never caller argv or query text.
+ */
+export type QmdSpawnDiagnostics = {
+    errnoCode: string | null;
+    cwd: string | null;
+    cwdExists: boolean | null;
+    command: string;
+    commandExists: boolean;
+    launcher: string;
+    launcherExists: boolean;
+};
 /** Low-level spawn seam (defaults to `spawnSync`); injected in tests. */
 export type QmdSpawn = (cmd: string, args: string[], options: {
     cwd?: string;
@@ -59,6 +78,34 @@ export type QmdSpawn = (cmd: string, args: string[], options: {
 export declare function withNodeDirOnPath(env: NodeJS.ProcessEnv | undefined, execDir: string | undefined, platform?: NodeJS.Platform): NodeJS.ProcessEnv | undefined;
 export declare class QmdBinaryMissingError extends Error {
     name: string;
+    /**
+     * Present only when the failure came through the real spawn path (attribution
+     * available): the errno code and per-component existence booleans captured at
+     * failure time, forwarded to a bounded Sentry context by the boundary so the
+     * next occurrence carries the evidence the reported one lacked (HQ-CLI-1A).
+     * Absent on the legacy injected-runner path and the resolver's opaque throws,
+     * so their existing shapes are unchanged.
+     */
+    readonly spawnDiagnostics?: QmdSpawnDiagnostics;
+    constructor(message: string, spawnDiagnostics?: QmdSpawnDiagnostics);
+}
+/**
+ * qmd could not be SPAWNED because its working directory does not exist:
+ * spawnSync returned ENOENT while chdir-ing into `cwd` (the resolved hq root at
+ * every index call site) before it could exec the command. On Linux that ENOENT
+ * is byte-identical to a missing-command ENOENT — Node sets `error.path` to the
+ * COMMAND either way — so finishRunQmd disambiguates by existence and raises
+ * THIS typed carrier only when the working directory itself is absent. Carries
+ * the hq-DERIVED `workdir`, the `command` that was spawned, and the bounded
+ * `errnoCode`; a missing working directory is the caller's filesystem, so the
+ * boundary prints qmdWorkdirMissingMessage and SKIPS capture (HQ-CLI-1A).
+ */
+export declare class QmdWorkdirMissingError extends Error {
+    readonly workdir: string;
+    readonly command: string;
+    readonly errnoCode: string;
+    name: string;
+    constructor(message: string, workdir: string, command: string, errnoCode: string);
 }
 export declare class QmdExitError extends Error {
     readonly args: string[];
@@ -200,6 +247,51 @@ export declare class QmdStoreUnopenableError extends QmdExitError {
     name: string;
     constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string, storeDir?: string | undefined, probeReason?: string | undefined);
 }
+/**
+ * qmd's `query` subcommand (hybrid search) rejected the positional as a
+ * MALFORMED QUERY DOCUMENT: qmd 2.5.3 parses a multi-line positional as a query
+ * document and requires EVERY non-empty line to carry a lex:/vec:/hyde:/intent:/
+ * expand: prefix (dist/cli/qmd.js:2157-2217), throwing otherwise. That is the
+ * caller's INPUT SHAPE — a multi-line free-text query, most often a fleet agent
+ * forwarding a whole Slack message — not a bug HQ can fix in code.
+ *
+ * HQ-CLI-1B (Sentry indigo-d0/hq-cli 7705711476, 28 of 29 events): `hq search
+ * --mode hybrid` mapped to `qmd query` and handed the caller's multi-line query
+ * through unchanged; qmd exited 1 with `Line 1 is missing a lex:/vec:/hyde:/
+ * intent: prefix. …`. With no classifier the generic template raised a plain
+ * QmdExitError that reached the boundary's final else and was captured.
+ * buildSearchArgs now normalises free text to a single line so the common case
+ * never reaches qmd multi-line; this typed subclass lets the boundary classify a
+ * genuinely malformed structured document as the caller's input and stop
+ * fingerprinting on the query text: it is raised only from qmd's OWN captured
+ * streams and its message names the SUBCOMMAND only.
+ */
+export declare class QmdQueryDocumentError extends QmdExitError {
+    name: string;
+}
+/**
+ * A qmd MODEL DOWNLOAD did not finish: qmd crashed with ENOENT while renaming its
+ * own partial `.ipull` download file into place. The partial file was gone by the
+ * time 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, not a bug HQ can fix in code: hq cannot coordinate qmd
+ * children other users start on the same host, and reaching into qmd's model
+ * cache would be hq owning upstream state.
+ *
+ * HQ-CLI-1B (Sentry indigo-d0/hq-cli 7705711476, the newest event, on release
+ * 5.107.1): `qmd query` reached its reranking stage and its reranker-model
+ * downloader died uncaught with `[Error: ENOENT: no such file or directory,
+ * rename '<cache>/…-reranker-….gguf.ipull' -> '<cache>/…-reranker-….gguf']`.
+ * With no classifier it took the identical fall-through to capture as the
+ * query-document crash — and because both share the (QmdExitError, qmd:query,
+ * exit:1) fingerprint, a query-document-only fix would leave this issue alive.
+ * This typed subclass lets the boundary classify it and stop the capture: it is
+ * raised only from qmd's OWN captured streams and its message names the
+ * SUBCOMMAND only.
+ */
+export declare class QmdModelDownloadError extends QmdExitError {
+    name: string;
+}
 export type ResolveQmdBinOptions = {
     env?: Record<string, string | undefined>;
     isExecutable?: (candidate: string) => boolean;
@@ -424,6 +516,12 @@ export type RunQmdOptions = {
     execPath?: string;
     /** Invocation resolver seam (default {@link resolveQmdInvocation}). */
     resolveInvocation?: (options: ResolveQmdInvocationOptions) => QmdInvocation;
+    /**
+     * Existence-check seam threaded into finishRunQmd's spawn-failure
+     * disambiguation (default `fs.existsSync`); injected in tests so the missing
+     * cwd / interpreter branches are provable without touching the real disk.
+     */
+    exists?: (candidate: string) => boolean;
 };
 /** Run qmd with captured output and typed failures. */
 export declare function runQmd(args: string[], options?: RunQmdOptions): QmdProcessResult;

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

@@ -4,8 +4,10 @@ import { createRequire } from 'node:module';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isQmdModelDownloadError } from '../../utils/qmd-model-download-error.js';
 import { isQmdModuleMissingError } from '../../utils/qmd-module-missing-error.js';
 import { isQmdNativeBindingError } from '../../utils/qmd-native-binding-error.js';
+import { isQmdQueryDocumentError } from '../../utils/qmd-query-document-error.js';
 import { isQmdStoreMissingError } from '../../utils/qmd-store-missing-error.js';
 import { isQmdStoreUnopenableError } from '../../utils/qmd-store-unopenable-error.js';
 import { redactErrorText } from '../../utils/redact-error-text.js';
@@ -28,6 +30,43 @@ export function withNodeDirOnPath(env, execDir, platform = process.platform) {
 }
 export class QmdBinaryMissingError extends Error {
     name = 'QmdBinaryMissingError';
+    /**
+     * Present only when the failure came through the real spawn path (attribution
+     * available): the errno code and per-component existence booleans captured at
+     * failure time, forwarded to a bounded Sentry context by the boundary so the
+     * next occurrence carries the evidence the reported one lacked (HQ-CLI-1A).
+     * Absent on the legacy injected-runner path and the resolver's opaque throws,
+     * so their existing shapes are unchanged.
+     */
+    spawnDiagnostics;
+    constructor(message, spawnDiagnostics) {
+        super(message);
+        if (spawnDiagnostics)
+            this.spawnDiagnostics = spawnDiagnostics;
+    }
+}
+/**
+ * qmd could not be SPAWNED because its working directory does not exist:
+ * spawnSync returned ENOENT while chdir-ing into `cwd` (the resolved hq root at
+ * every index call site) before it could exec the command. On Linux that ENOENT
+ * is byte-identical to a missing-command ENOENT — Node sets `error.path` to the
+ * COMMAND either way — so finishRunQmd disambiguates by existence and raises
+ * THIS typed carrier only when the working directory itself is absent. Carries
+ * the hq-DERIVED `workdir`, the `command` that was spawned, and the bounded
+ * `errnoCode`; a missing working directory is the caller's filesystem, so the
+ * boundary prints qmdWorkdirMissingMessage and SKIPS capture (HQ-CLI-1A).
+ */
+export class QmdWorkdirMissingError extends Error {
+    workdir;
+    command;
+    errnoCode;
+    name = 'QmdWorkdirMissingError';
+    constructor(message, workdir, command, errnoCode) {
+        super(message);
+        this.workdir = workdir;
+        this.command = command;
+        this.errnoCode = errnoCode;
+    }
 }
 export class QmdExitError extends Error {
     args;
@@ -189,6 +228,51 @@ export class QmdStoreUnopenableError extends QmdExitError {
         this.probeReason = probeReason;
     }
 }
+/**
+ * qmd's `query` subcommand (hybrid search) rejected the positional as a
+ * MALFORMED QUERY DOCUMENT: qmd 2.5.3 parses a multi-line positional as a query
+ * document and requires EVERY non-empty line to carry a lex:/vec:/hyde:/intent:/
+ * expand: prefix (dist/cli/qmd.js:2157-2217), throwing otherwise. That is the
+ * caller's INPUT SHAPE — a multi-line free-text query, most often a fleet agent
+ * forwarding a whole Slack message — not a bug HQ can fix in code.
+ *
+ * HQ-CLI-1B (Sentry indigo-d0/hq-cli 7705711476, 28 of 29 events): `hq search
+ * --mode hybrid` mapped to `qmd query` and handed the caller's multi-line query
+ * through unchanged; qmd exited 1 with `Line 1 is missing a lex:/vec:/hyde:/
+ * intent: prefix. …`. With no classifier the generic template raised a plain
+ * QmdExitError that reached the boundary's final else and was captured.
+ * buildSearchArgs now normalises free text to a single line so the common case
+ * never reaches qmd multi-line; this typed subclass lets the boundary classify a
+ * genuinely malformed structured document as the caller's input and stop
+ * fingerprinting on the query text: it is raised only from qmd's OWN captured
+ * streams and its message names the SUBCOMMAND only.
+ */
+export class QmdQueryDocumentError extends QmdExitError {
+    name = 'QmdQueryDocumentError';
+}
+/**
+ * A qmd MODEL DOWNLOAD did not finish: qmd crashed with ENOENT while renaming its
+ * own partial `.ipull` download file into place. The partial file was gone by the
+ * time 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, not a bug HQ can fix in code: hq cannot coordinate qmd
+ * children other users start on the same host, and reaching into qmd's model
+ * cache would be hq owning upstream state.
+ *
+ * HQ-CLI-1B (Sentry indigo-d0/hq-cli 7705711476, the newest event, on release
+ * 5.107.1): `qmd query` reached its reranking stage and its reranker-model
+ * downloader died uncaught with `[Error: ENOENT: no such file or directory,
+ * rename '<cache>/…-reranker-….gguf.ipull' -> '<cache>/…-reranker-….gguf']`.
+ * With no classifier it took the identical fall-through to capture as the
+ * query-document crash — and because both share the (QmdExitError, qmd:query,
+ * exit:1) fingerprint, a query-document-only fix would leave this issue alive.
+ * This typed subclass lets the boundary classify it and stop the capture: it is
+ * raised only from qmd's OWN captured streams and its message names the
+ * SUBCOMMAND only.
+ */
+export class QmdModelDownloadError extends QmdExitError {
+    name = 'QmdModelDownloadError';
+}
 function isExecutable(candidate) {
     try {
         fs.accessSync(candidate, fs.constants.X_OK);
@@ -919,7 +1003,7 @@ function describeQmdTermination(stdout, stderr) {
     return '';
 }
 /** Normalise a spawn result and raise the typed qmd failures. */
-function finishRunQmd(result, bin, args) {
+function finishRunQmd(result, bin, args, attribution) {
     const normalized = {
         status: result.status,
         stdout: result.stdout ?? '',
@@ -928,6 +1012,54 @@ function finishRunQmd(result, bin, args) {
         signal: result.signal,
     };
     if (normalized.error) {
+        // A spawn-LEVEL failure: the child could not even be exec'd. When the real
+        // spawn path supplied attribution we can attribute it to the right
+        // component; the legacy injected-runner path passes none and keeps today's
+        // exact class and message.
+        if (attribution) {
+            const spawnError = normalized.error;
+            const errnoCode = typeof spawnError.code === 'string' ? spawnError.code : null;
+            const exists = attribution.exists ?? ((candidate) => fs.existsSync(candidate));
+            const cwd = attribution.cwd ?? null;
+            const cwdExists = cwd !== null ? exists(cwd) : null;
+            const commandExists = exists(attribution.command);
+            const launcherExists = exists(attribution.launcher);
+            // (a) MISSING WORKING DIRECTORY. On Linux spawnSync reports ENOENT with
+            // `error.path` set to the COMMAND both when the command is absent AND when
+            // chdir into `cwd` fails, so this cwd check MUST precede the command check
+            // below — a path-based test alone would keep blaming the interpreter for a
+            // directory that is simply gone (HQ-CLI-1A). The directory is the caller's
+            // filesystem, so it is raised as its own carrier and the boundary skips
+            // capture.
+            if (errnoCode === 'ENOENT' && cwd !== null && cwdExists === false) {
+                throw new QmdWorkdirMissingError(`qmd could not run: its working directory (${cwd}) does not exist`, cwd, attribution.command, errnoCode);
+            }
+            const diagnostics = {
+                errnoCode,
+                cwd,
+                cwdExists,
+                command: attribution.command,
+                commandExists,
+                launcher: attribution.launcher,
+                launcherExists,
+            };
+            // (b) MISSING INTERPRETER. The bundled qmd is launched as `<node> <qmd
+            // launcher>`; when the interpreter (`command`, distinct from the launcher)
+            // is what could not be executed, name IT rather than the launcher the
+            // reported message wrongly blamed. Still captured — an absent interpreter
+            // is a genuine defect — but now correct and self-describing.
+            if (errnoCode === 'ENOENT' &&
+                attribution.command !== attribution.launcher &&
+                commandExists === false) {
+                throw new QmdBinaryMissingError(`Unable to execute qmd: its Node interpreter (${attribution.command}) could not be executed: ${normalized.error.message}`, diagnostics);
+            }
+            // (c) RESIDUAL: an ENOENT the fix cannot attribute (a genuinely missing
+            // qmd, or a race where the directory/interpreter reappeared) or any other
+            // spawn errno (EACCES/EINVAL/…). Keep today's class and message byte-for-
+            // byte, and attach the bounded diagnostics so the next occurrence carries
+            // the per-component existence evidence.
+            throw new QmdBinaryMissingError(`Unable to execute qmd at ${bin}: ${normalized.error.message}`, diagnostics);
+        }
         throw new QmdBinaryMissingError(`Unable to execute qmd at ${bin}: ${normalized.error.message}`);
     }
     if (normalized.status === 0)
@@ -1036,6 +1168,35 @@ function finishRunQmd(result, bin, args) {
         const ensure = lastQmdStoreEnsure;
         throw new QmdStoreUnopenableError(`qmd ${subcommand} could not run: its local search store could not be opened`, args, normalized.status, normalized.stdout, normalized.stderr, ensure?.dir, ensure && !ensure.writable ? ensure.reason : undefined);
     }
+    // qmd's `query` subcommand rejected the positional as a MALFORMED QUERY
+    // DOCUMENT: qmd 2.5.3 parses a multi-line positional as a document and requires
+    // every non-empty line to carry a lex:/vec:/hyde:/intent:/expand: prefix, so a
+    // multi-line free-text query (a fleet agent forwarding a whole Slack message)
+    // exits 1 with a syntax diagnostic. That is the caller's INPUT SHAPE, not an
+    // hq-cli defect. Read qmd's OWN captured streams only, never the synthesized
+    // message, so a user query that merely contains the wording can never trip it.
+    // hq-cli side: buildSearchArgs now normalises free text to one line so this no
+    // longer fires for the common case; this branch types a genuinely malformed
+    // structured document so the boundary prints a query-free remedy and skips
+    // capture. Placed AFTER the store checks and BEFORE the collection-missing
+    // regex; the wordings are disjoint (that regex needs collection/qmd:// adjacent
+    // to a not-found token, absent here), so no existing branch changes behaviour
+    // (HQ-CLI-1B / Sentry 7705711476).
+    if (isQmdQueryDocumentError({ stderr: normalized.stderr, stdout: normalized.stdout })) {
+        throw new QmdQueryDocumentError(`qmd ${subcommand} could not run: the query was read as a malformed query document`, args, normalized.status, normalized.stdout, normalized.stderr);
+    }
+    // A qmd MODEL DOWNLOAD died with ENOENT renaming its own partial `.ipull` file
+    // — 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, not
+    // an hq-cli defect (hq cannot coordinate qmd children other users start on the
+    // host). Require BOTH the ENOENT-rename signature AND the `.ipull` marker so a
+    // durable failure (ENOSPC/EACCES/network) keeps its reportable path. Read qmd's
+    // OWN captured streams only. Placed with the query-document check, before the
+    // collection-missing regex; the signatures are disjoint, so no existing branch
+    // changes behaviour (HQ-CLI-1B / Sentry 7705711476, the newest event).
+    if (isQmdModelDownloadError({ stderr: normalized.stderr, stdout: normalized.stdout })) {
+        throw new QmdModelDownloadError(`qmd ${subcommand} could not run: a model download did not finish (its partial file disappeared)`, args, normalized.status, normalized.stdout, normalized.stderr);
+    }
     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);
     }
@@ -1081,13 +1242,24 @@ export function runQmd(args, options = {}) {
     // idempotent; only the real spawn path needs it (the injected-runner path
     // above never opens a store).
     ensureQmdStoreDir(options.env ?? process.env, { cwd: options.cwd });
+    const launcher = invocationBin(invocation);
     const result = spawnQmd(invocation, args, {
         cwd: options.cwd,
         env: options.env ?? process.env,
         platform: options.platform,
         spawn: options.spawn,
     });
-    return finishRunQmd(result, invocationBin(invocation), args);
+    // Thread attribution so finishRunQmd can attribute a spawn-level ENOENT to the
+    // right component — the working directory, the Node interpreter, or a
+    // genuinely missing qmd — instead of blaming the launcher for all three
+    // (HQ-CLI-1A). `command` is the process actually spawned; `launcher` is qmd's
+    // file identity.
+    return finishRunQmd(result, launcher, args, {
+        command: invocation.command,
+        launcher,
+        cwd: options.cwd,
+        exists: options.exists,
+    });
 }
 function containsIndexedMarkdown(directory) {
     if (!fs.existsSync(directory))

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

@@ -0,0 +1,18 @@
+/**
+ * Atomic owner-only file writes with symlink and path guards for work-context.
+ */
+/**
+ * Resolve symlinks on an existing path; for a missing leaf, resolve the parent
+ * and re-append the basename so we never rename onto a symlink.
+ */
+export declare function resolveRealTarget(target: string): string;
+/**
+ * Ensure parent dir exists as a real directory (not a symlink), mode 0700.
+ */
+export declare function ensureOwnerDir(dir: string): string;
+/**
+ * Atomically replace target with data at mode 0600 (same-dir tmp + rename).
+ */
+export declare function atomicWriteFile(target: string, data: string | Buffer): void;
+export declare function atomicWriteJson(target: string, value: unknown): void;
+//# sourceMappingURL=atomic.d.ts.map

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

@@ -0,0 +1,132 @@
+/**
+ * Atomic owner-only file writes with symlink and path guards for work-context.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { UnsafeConfigPathError } from "./errors.js";
+function fsyncDir(dir) {
+    try {
+        const fd = fs.openSync(dir, "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        // Best-effort: some platforms reject directory fsync.
+    }
+}
+/**
+ * Resolve symlinks on an existing path; for a missing leaf, resolve the parent
+ * and re-append the basename so we never rename onto a symlink.
+ */
+export function resolveRealTarget(target) {
+    try {
+        return fs.realpathSync(target);
+    }
+    catch {
+        // Leaf may not exist yet.
+    }
+    let cur = path.dirname(target);
+    const base = path.basename(target);
+    for (let i = 0; i < 40; i += 1) {
+        try {
+            const lst = fs.lstatSync(cur);
+            if (lst.isSymbolicLink()) {
+                throw new UnsafeConfigPathError(`Refusing write through symlink: ${cur}`);
+            }
+            const real = fs.realpathSync(cur);
+            return path.join(real, base);
+        }
+        catch (err) {
+            if (err instanceof UnsafeConfigPathError)
+                throw err;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                break;
+            cur = parent;
+        }
+    }
+    return target;
+}
+/**
+ * Ensure parent dir exists as a real directory (not a symlink), mode 0700.
+ */
+export function ensureOwnerDir(dir) {
+    const resolved = (() => {
+        try {
+            if (fs.existsSync(dir)) {
+                const lst = fs.lstatSync(dir);
+                if (lst.isSymbolicLink()) {
+                    throw new UnsafeConfigPathError(`Refusing directory that is a symlink: ${dir}`);
+                }
+                return fs.realpathSync(dir);
+            }
+        }
+        catch (err) {
+            if (err instanceof UnsafeConfigPathError)
+                throw err;
+        }
+        return dir;
+    })();
+    fs.mkdirSync(resolved, { recursive: true, mode: 0o700 });
+    try {
+        fs.chmodSync(resolved, 0o700);
+    }
+    catch {
+        // ignore chmod failures on exotic FS
+    }
+    const lst = fs.lstatSync(resolved);
+    if (lst.isSymbolicLink()) {
+        throw new UnsafeConfigPathError(`Refusing directory that is a symlink: ${resolved}`);
+    }
+    return fs.realpathSync(resolved);
+}
+/**
+ * Atomically replace target with data at mode 0600 (same-dir tmp + rename).
+ */
+export function atomicWriteFile(target, data) {
+    const realTarget = resolveRealTarget(target);
+    const dir = ensureOwnerDir(path.dirname(realTarget));
+    const finalPath = path.join(dir, path.basename(realTarget));
+    const tmp = path.join(dir, `.${path.basename(finalPath)}.tmp.${process.pid}.${Date.now()}`);
+    let fd;
+    try {
+        fd = fs.openSync(tmp, "wx", 0o600);
+        fs.writeSync(fd, typeof data === "string" ? Buffer.from(data, "utf8") : data);
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        fs.renameSync(tmp, finalPath);
+        fsyncDir(dir);
+        try {
+            fs.chmodSync(finalPath, 0o600);
+        }
+        catch {
+            // ignore
+        }
+    }
+    catch (err) {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* already closed */
+            }
+        }
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* temp may not exist */
+        }
+        throw err;
+    }
+}
+export function atomicWriteJson(target, value) {
+    atomicWriteFile(target, `${JSON.stringify(value, null, 2)}\n`);
+}
+//# sourceMappingURL=atomic.js.map