@indigoai-us/hq-cli 5.130.0 → 5.132.0

package/dist/lib/work-context/preflight-contract.js

@@ -0,0 +1,85 @@
+/**
+ * Offline preflight ContextResult shapes that `hq mesh context reconcile --offline`
+ * can emit. migration_pending is a migrate-path status, not a preflight result.
+ *
+ * contractVersion is WORK_CONTEXT_CONTRACT_VERSION. Bump it only together with
+ * contracts/preflight/v<N>/ and the vendored copy in hq-core
+ * (core/hooks/SessionStart/preflight-fixtures.json). Each side pins the version
+ * in tests; a one-sided bump fails that side until the other is updated.
+ */
+import { WORK_CONTEXT_CONTRACT_VERSION, } from "./contract.js";
+export const PREFLIGHT_CONTRACT_VERSION = WORK_CONTEXT_CONTRACT_VERSION;
+/** Classifications reconcile actually returns on the offline preflight path. */
+export const OFFLINE_PREFLIGHT_CLASSIFICATIONS = [
+    "unresolved",
+    "needs_company",
+    "company_conflict",
+    "needs_project",
+    "needs_task",
+    "bound",
+    "untracked",
+];
+const FIXTURE_SESSION = "sid-preflight-fixture";
+const FIXTURE_OP = "op-preflight-fixture";
+function base(classification, kind, delivery) {
+    return {
+        contractVersion: PREFLIGHT_CONTRACT_VERSION,
+        kind,
+        classification,
+        delivery,
+        lifecycle: "open",
+        sessionId: FIXTURE_SESSION,
+        clientOperationId: FIXTURE_OP,
+    };
+}
+/**
+ * One representative result per emitted classification, using the kind and
+ * delivery the offline path actually returns (company-resolved results are
+ * kind "queued" / delivery "queued"; local-only results are delivery "clean").
+ */
+export function preflightFixtureFor(classification) {
+    switch (classification) {
+        case "unresolved":
+            return base("unresolved", "queued", "queued");
+        case "needs_company":
+            return base("needs_company", "needs_company", "clean");
+        case "company_conflict":
+            return base("company_conflict", "company_conflict", "clean");
+        case "needs_project":
+            return {
+                ...base("needs_project", "queued", "queued"),
+                companySlug: "acme",
+                companyUid: "cmp_acme",
+            };
+        case "needs_task":
+            return {
+                ...base("needs_task", "queued", "queued"),
+                companySlug: "acme",
+                companyUid: "cmp_acme",
+                projectId: "dispatch-proj",
+            };
+        case "bound":
+            return {
+                ...base("bound", "queued", "queued"),
+                companySlug: "acme",
+                companyUid: "cmp_acme",
+                projectId: "dispatch-proj",
+                taskId: "US-9",
+            };
+        case "untracked":
+            return base("untracked", "untracked", "clean");
+        default: {
+            const never = classification;
+            return never;
+        }
+    }
+}
+export function buildPreflightFixtures() {
+    return {
+        contractVersion: PREFLIGHT_CONTRACT_VERSION,
+        source: "hq-cli contracts/preflight/v1/fixtures.json",
+        classifications: [...OFFLINE_PREFLIGHT_CLASSIFICATIONS],
+        fixtures: OFFLINE_PREFLIGHT_CLASSIFICATIONS.map(preflightFixtureFor),
+    };
+}
+//# sourceMappingURL=preflight-contract.js.map

package/dist/main.js

@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { finishSentrySession, initSentry, Sentry } from "./sentry.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
-import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { environmentalFsErrorMessage, filesystemErrorCaptureContext, filesystemErrorMessage, } 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";
@@ -690,6 +690,12 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             lockMsg
             ? null
             : networkTransportErrorMessage(err);
+        // Windows EPERM/EACCES/EBUSY/UNKNOWN filesystem failures are not proven
+        // caller-owned conditions. Keep them at error level and attach bounded,
+        // installation-independent context so OneDrive/antivirus/path-length
+        // hypotheses can be separated without creating one issue per host path.
+        const fsContext = filesystemErrorCaptureContext(err);
+        const fsMsg = fsContext ? filesystemErrorMessage(err) : null;
         if (qmdMsg) {
             deps.stderr.write(`hq: ${qmdMsg}\n`);
         }
@@ -735,6 +741,10 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (transportMsg) {
             deps.stderr.write(`hq: ${transportMsg}\n`);
         }
+        else if (fsMsg && fsContext) {
+            deps.sentry.captureException(err, fsContext);
+            deps.stderr.write(`hq: ${fsMsg}\n`);
+        }
         else {
             // A genuinely unclassified fault is still captured exactly once. Two
             // shapes attach bounded, hq-derived context so the next occurrence

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

@@ -153,6 +153,45 @@ export declare function wantsMachineCognitoTokens(options?: Pick<EnsureCognitoTo
  * not flip this to machine.
  */
 export declare function resolveCognitoTokenSource(env?: NodeJS.ProcessEnv): CognitoTokenSource;
+/**
+ * Refresh wrote a different Cognito subject than the active cache.
+ * Callers must not fall through to browser login or machine mint — that
+ * would replace the operator session the refusal is protecting.
+ */
+export declare class IdentitySwapRefusal extends Error {
+    constructor(message: string);
+}
+export declare function isIdentitySwapRefusal(err: unknown): err is IdentitySwapRefusal;
+/** `sub` plus `custom:entityUid` from an unverified JWT. Either may be absent. */
+export declare function cognitoSubjectFromToken(token: string | undefined): {
+    sub: string | null;
+    entityUid: string | null;
+};
+/** Stable subject key. Null when neither sub nor entity uid is present. */
+export declare function cognitoSubjectKey(tokens: {
+    idToken?: string;
+    accessToken?: string;
+} | null | undefined): string | null;
+/** Doctor/status line. Claims only — never token material. */
+export declare function formatCognitoSubject(tokens: {
+    idToken?: string;
+    accessToken?: string;
+} | null | undefined): string;
+/**
+ * Person cache as stored on disk for `env`. Does not consult hq-cloud's
+ * in-memory fallback, which can surface a different session when the file
+ * is missing or unreadable.
+ */
+export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessEnv): CognitoTokens | null;
+/**
+ * Refresh the active person session and refuse a subject change.
+ *
+ * hq-cloud's `refreshTokens` saves as soon as Cognito responds, and on a
+ * cache miss or unreadable file it can refresh an in-memory session for a
+ * different subject (same app client). Snapshot the active file first; if
+ * the response subject differs, put the bytes back and leave them there.
+ */
+export declare function refreshActivePersonTokens(cached: CognitoTokens, env?: NodeJS.ProcessEnv): Promise<CognitoTokens>;
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
 export declare function actorKindFromIdToken(idToken: string | undefined): CognitoActorKind;
 /**

package/dist/utils/cognito-session.js

@@ -409,6 +409,115 @@ function decodeJwtPayload(token) {
         return null;
     }
 }
+/**
+ * Refresh wrote a different Cognito subject than the active cache.
+ * Callers must not fall through to browser login or machine mint — that
+ * would replace the operator session the refusal is protecting.
+ */
+export class IdentitySwapRefusal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IdentitySwapRefusal";
+    }
+}
+export function isIdentitySwapRefusal(err) {
+    return err instanceof IdentitySwapRefusal;
+}
+/** `sub` plus `custom:entityUid` from an unverified JWT. Either may be absent. */
+export function cognitoSubjectFromToken(token) {
+    const claims = decodeJwtPayload(token);
+    const sub = typeof claims?.sub === "string" && claims.sub.length > 0 ? claims.sub : null;
+    const entity = claims?.["custom:entityUid"];
+    const entityUid = typeof entity === "string" && entity.length > 0 ? entity : null;
+    return { sub, entityUid };
+}
+/** Stable subject key. Null when neither sub nor entity uid is present. */
+export function cognitoSubjectKey(tokens) {
+    if (!tokens)
+        return null;
+    const fromId = cognitoSubjectFromToken(tokens.idToken);
+    const fromAccess = cognitoSubjectFromToken(tokens.accessToken);
+    const sub = fromId.sub ?? fromAccess.sub;
+    const entityUid = fromId.entityUid ?? fromAccess.entityUid;
+    if (!sub && !entityUid)
+        return null;
+    return `${sub ?? ""}|${entityUid ?? ""}`;
+}
+/** Doctor/status line. Claims only — never token material. */
+export function formatCognitoSubject(tokens) {
+    if (!tokens)
+        return "sub=- entityUid=-";
+    const fromId = cognitoSubjectFromToken(tokens.idToken);
+    const fromAccess = cognitoSubjectFromToken(tokens.accessToken);
+    return `sub=${fromId.sub ?? fromAccess.sub ?? "-"} entityUid=${fromId.entityUid ?? fromAccess.entityUid ?? "-"}`;
+}
+function readTokenFile(file) {
+    try {
+        if (!fs.existsSync(file))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof raw.accessToken !== "string" || typeof raw.idToken !== "string")
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Person cache as stored on disk for `env`. Does not consult hq-cloud's
+ * in-memory fallback, which can surface a different session when the file
+ * is missing or unreadable.
+ */
+export function readPersonTokenFile(home = os.homedir(), env = process.env) {
+    return readTokenFile(personTokenCacheFile(home, env));
+}
+function restoreTokenFile(file, before) {
+    if (before) {
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = path.join(dir, `.cognito-tokens.json.restore.${process.pid}`);
+        fs.writeFileSync(tmp, before, { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        return;
+    }
+    if (fs.existsSync(file))
+        fs.unlinkSync(file);
+}
+/**
+ * Refresh the active person session and refuse a subject change.
+ *
+ * hq-cloud's `refreshTokens` saves as soon as Cognito responds, and on a
+ * cache miss or unreadable file it can refresh an in-memory session for a
+ * different subject (same app client). Snapshot the active file first; if
+ * the response subject differs, put the bytes back and leave them there.
+ */
+export async function refreshActivePersonTokens(cached, env = process.env) {
+    const file = personTokenCacheFile(os.homedir(), env);
+    const onDisk = readTokenFile(file);
+    const diskKey = cognitoSubjectKey(onDisk);
+    const cachedKey = cognitoSubjectKey(cached);
+    if (diskKey && cachedKey && diskKey !== cachedKey) {
+        const message = `refusing token refresh: cached subject ${formatCognitoSubject(cached)} ` +
+            `does not match active subject ${formatCognitoSubject(onDisk)}; token file left unchanged`;
+        console.error(message);
+        throw new IdentitySwapRefusal(message);
+    }
+    const activeTokens = diskKey && cachedKey && diskKey === cachedKey ? onDisk : cached;
+    const activeKey = cognitoSubjectKey(activeTokens);
+    const before = fs.existsSync(file) ? fs.readFileSync(file) : null;
+    const refreshed = await refreshTokens(DEFAULT_COGNITO, activeTokens.refreshToken, activeTokens.accessToken);
+    const nextKey = cognitoSubjectKey(refreshed);
+    if (activeKey && nextKey && nextKey !== activeKey) {
+        restoreTokenFile(file, before);
+        const message = `refusing token refresh: refreshed subject ${formatCognitoSubject(refreshed)} ` +
+            `does not match active subject ${formatCognitoSubject(activeTokens)}; token file left unchanged`;
+        console.error(message);
+        throw new IdentitySwapRefusal(message);
+    }
+    return refreshed;
+}
 /** Derive actor kind from an ID token's custom:entity* claims (no verify). */
 export function actorKindFromIdToken(idToken) {
     const claims = decodeJwtPayload(idToken);
@@ -616,10 +725,12 @@ async function ensureCognitoTokenUnserialized(options) {
             if (interactive) {
                 console.error(chalk.dim("  Refreshing expiring HQ session..."));
             }
-            const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+            const refreshed = await refreshActivePersonTokens(cached);
             return refreshed.accessToken;
         }
         catch (err) {
+            if (isIdentitySwapRefusal(err))
+                throw err;
             // Transient/network/server errors stay person errors — never mint machine.
             if (!isDefinitivePersonAuthRejection(err)) {
                 throw err;
@@ -676,10 +787,12 @@ async function ensureCognitoIdTokenUnserialized(options) {
             if (interactive) {
                 console.error(chalk.dim("  Refreshing expiring HQ session..."));
             }
-            const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+            const refreshed = await refreshActivePersonTokens(cached);
             return refreshed.idToken;
         }
         catch (err) {
+            if (isIdentitySwapRefusal(err))
+                throw err;
             if (!isDefinitivePersonAuthRejection(err)) {
                 throw err;
             }
@@ -778,10 +891,13 @@ async function refreshCachedSessionUnserialized(options) {
         return { refreshed: true };
     }
     try {
-        await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+        await refreshActivePersonTokens(cached);
         return { refreshed: true };
     }
     catch (err) {
+        if (isIdentitySwapRefusal(err)) {
+            return { refreshed: false, reason: err.message };
+        }
         // Transient/network/server refresh errors stay person failures.
         if (!isDefinitivePersonAuthRejection(err)) {
             return {

package/dist/utils/environmental-error.d.ts

@@ -7,4 +7,22 @@
  * result means "this is a normal error; handle it as usual (capture to Sentry)".
  */
 export declare function environmentalFsErrorMessage(err: unknown): string | null;
+export type FilesystemErrorCaptureContext = {
+    fingerprint: ["fs-error", string, string, string];
+    tags: Record<string, string>;
+    extra: {
+        fs_path: string;
+        fs_reason: string;
+    };
+};
+/** Return only the registered command path, never positional user data. */
+export declare function hqCommand(argv?: readonly string[]): string;
+/**
+ * Build stable Sentry context for known OS filesystem refusals. The failure is
+ * intentionally still captured: this is instrumentation for the OneDrive /
+ * antivirus / path-length hypotheses, not an expected-error suppression.
+ */
+export declare function filesystemErrorCaptureContext(err: unknown, argv?: readonly string[]): FilesystemErrorCaptureContext | null;
+/** Plain operator guidance for a captured filesystem failure. */
+export declare function filesystemErrorMessage(err: unknown): string | null;
 //# sourceMappingURL=environmental-error.d.ts.map

package/dist/utils/environmental-error.js

@@ -1,16 +1,20 @@
 // src/utils/environmental-error.ts
 //
 // Classify errors that stem from the user's machine/filesystem state rather
-// than an HQ code defect. These are unactionable from our side: a full disk, an
-// exhausted quota, or a read-only filesystem. The CLI surfaces a clear,
-// actionable message and does NOT report them to Sentry — otherwise a single
-// full disk floods the issue tracker with identical, unfixable crash reports.
+// than an HQ code defect. Full-disk conditions have a known remedy and remain
+// quiet; permission and file-lock conditions remain captured with bounded
+// attribution so the next occurrence can identify the real cause.
 //
 // HQ-CLI-2: `hq reindex` hit ENOSPC in the operation-lock temp-file write
 // (`fs.openSync` → "ENOSPC: no space left on device, open") and the raw error
 // propagated uncaught to the CLI's top-level handler, which captured it to
 // Sentry and exited silently — 5 stack-trace crashes in 6 seconds, with no
 // message telling the user their disk was full.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { COMMAND_CATALOG } from "../command-catalog.generated.js";
+import { CLI_VERSION } from "../cli-version.js";
+import { redactErrorText } from "./redact-error-text.js";
 /**
  * Node errno codes for "the filesystem cannot accept this write" — purely
  * environmental, never a code bug. Mapped to the message shown to the user.
@@ -20,6 +24,24 @@ const ENVIRONMENTAL_FS_CODES = {
     EDQUOT: "Disk quota exceeded. Free up space (or raise your quota) and try again.",
     EROFS: "The filesystem is read-only, so HQ can't write here. Check the mount/permissions and try again.",
 };
+const MAX_CAUSE_DEPTH = 4;
+function errorRecord(value) {
+    return value !== null && typeof value === "object" ? value : null;
+}
+function findErrorWithCode(err, codes) {
+    const seen = new Set();
+    let current = err;
+    for (let depth = 0; depth <= MAX_CAUSE_DEPTH; depth += 1) {
+        const record = errorRecord(current);
+        if (!record || seen.has(record))
+            return null;
+        seen.add(record);
+        if (typeof record.code === "string" && codes.has(record.code))
+            return record;
+        current = record.cause;
+    }
+    return null;
+}
 /**
  * If `err` is an environmental disk/quota/read-only filesystem error, return a
  * short, user-facing message explaining it; otherwise return `null`.
@@ -29,9 +51,220 @@ const ENVIRONMENTAL_FS_CODES = {
  * result means "this is a normal error; handle it as usual (capture to Sentry)".
  */
 export function environmentalFsErrorMessage(err) {
-    const code = err?.code;
-    if (typeof code !== "string")
+    const record = findErrorWithCode(err, new Set(Object.keys(ENVIRONMENTAL_FS_CODES)));
+    return record && typeof record.code === "string"
+        ? ENVIRONMENTAL_FS_CODES[record.code] ?? null
+        : null;
+}
+const CAPTURED_FS_CODES = new Set(["EPERM", "EACCES", "EBUSY", "UNKNOWN"]);
+const CAPTURED_FS_SYSCALLS = new Set(["open", "symlink", "rename", "unlink"]);
+function stringField(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function pathFromMessage(message, syscall) {
+    const text = stringField(message);
+    if (!text)
+        return null;
+    const escapedSyscall = syscall.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = new RegExp(`${escapedSyscall}\\s+['"]([^'"]+)['"]`, "i").exec(text);
+    return match?.[1] ?? null;
+}
+function findFilesystemError(err) {
+    const seen = new Set();
+    let current = err;
+    for (let depth = 0; depth <= MAX_CAUSE_DEPTH; depth += 1) {
+        const record = errorRecord(current);
+        if (!record || seen.has(record))
+            return null;
+        seen.add(record);
+        const code = stringField(record.code);
+        const syscall = stringField(record.syscall);
+        if (code && syscall && CAPTURED_FS_CODES.has(code) && CAPTURED_FS_SYSCALLS.has(syscall)) {
+            const rawPath = stringField(record.path) ??
+                stringField(record.dest) ??
+                pathFromMessage(record.message, syscall) ??
+                "unknown";
+            return { record, code, syscall, rawPath };
+        }
+        current = record.cause;
+    }
+    return null;
+}
+function canonicalPath(rawPath) {
+    if (rawPath === "unknown")
+        return "";
+    const resolved = path.resolve(rawPath);
+    try {
+        return path.normalize(requireRealpath(resolved));
+    }
+    catch {
+        // The failed path may not exist. Resolving its parent still canonicalizes
+        // symlinked HQ roots without turning missing-file attribution into a throw.
+        const parent = path.dirname(resolved);
+        try {
+            return path.join(requireRealpath(parent), path.basename(resolved));
+        }
+        catch {
+            return resolved;
+        }
+    }
+}
+function requireRealpath(candidate) {
+    // Keep the filesystem read behind one tiny seam so the classifier remains
+    // safe when the failed target has already disappeared.
+    return fs.realpathSync.native(candidate);
+}
+function pathSegments(value) {
+    return value
+        .replaceAll("\\", "/")
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => segment.toLowerCase());
+}
+function pathKind(rawPath, resolvedPath) {
+    if (rawPath === "unknown")
+        return "other";
+    const segments = pathSegments(`${resolvedPath}/${rawPath}`);
+    if (segments.includes("node_modules") || segments.includes(".pnpm"))
+        return "install-tree";
+    if (segments.includes("worktree") || segments.includes("worktrees"))
+        return "worktree";
+    if (segments.includes("companies"))
+        return "companies";
+    if (segments.includes("workspace"))
+        return "workspace";
+    if (segments.includes("hq"))
+        return "hq-root";
+    return "other";
+}
+function syncedFolder(resolvedPath) {
+    if (!resolvedPath)
+        return "none";
+    const segments = pathSegments(resolvedPath);
+    // iCloud is identified from canonical path components, not a display-name
+    // substring: Desktop/Documents aliases can point into this container.
+    for (let i = 0; i + 1 < segments.length; i += 1) {
+        if (segments[i] === "library" && segments[i + 1] === "mobile documents")
+            return "icloud";
+    }
+    if (segments.some((segment) => segment === "onedrive" || segment.startsWith("onedrive -")))
+        return "onedrive";
+    if (segments.includes("dropbox"))
+        return "dropbox";
+    if (segments.some((segment) => segment === "google drive" || segment === "google-drive" || segment === "googledrive")) {
+        return "google-drive";
+    }
+    return "none";
+}
+function redactedPath(rawPath) {
+    if (rawPath === "unknown")
+        return "unknown";
+    const segments = rawPath.replaceAll("\\", "/").split("/").filter(Boolean);
+    const tail = segments.slice(-2).join("/");
+    return redactErrorText(tail) || "unknown";
+}
+function fileAttributes(record, rawPath) {
+    const metadata = [record.fileAttributes, record.attributes]
+        .map(stringField)
+        .filter((value) => value !== null)
+        .join(" ")
+        .toLowerCase();
+    if (metadata.includes("offline") || record.offline === true)
+        return "offline";
+    if (metadata.includes("readonly") || metadata.includes("read-only") || record.readonly === true)
+        return "readonly";
+    const leaf = rawPath.replaceAll("\\", "/").split("/").filter(Boolean).at(-1) ?? rawPath;
+    if (metadata.includes("hidden") || record.hidden === true || leaf.startsWith("."))
+        return "hidden";
+    return "none";
+}
+function findRegisteredCommand(commands, token) {
+    return commands.find((command) => command.name === token || command.aliases.includes(token)) ?? null;
+}
+function optionTakesValue(command, token) {
+    const optionName = token.split("=", 1)[0];
+    return command.options.some((option) => {
+        const names = option.flags
+            .split(",")
+            .map((flag) => flag.trim().split(/\s+/, 1)[0])
+            .filter((name) => Boolean(name));
+        return names.includes(optionName) && /(?:<[^>]+>|\[[^\]]+\])/.test(option.flags);
+    });
+}
+/** Return only the registered command path, never positional user data. */
+export function hqCommand(argv = process.argv) {
+    const commandPath = [];
+    let commands = COMMAND_CATALOG;
+    let currentCommand = null;
+    for (let index = 2; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token || token === "--")
+            break;
+        if (token.startsWith("-")) {
+            if (!token.includes("=") && currentCommand && optionTakesValue(currentCommand, token)) {
+                index += 1;
+            }
+            continue;
+        }
+        const command = findRegisteredCommand(commands, token);
+        if (!command)
+            break;
+        commandPath.push(command.name);
+        currentCommand = command;
+        commands = command.subcommands;
+    }
+    return commandPath.join(" ") || "unknown";
+}
+function pathLengthBucket(rawPath) {
+    if (rawPath.length < 200)
+        return "<200";
+    if (rawPath.length <= 260)
+        return "200-260";
+    return ">260";
+}
+/**
+ * Build stable Sentry context for known OS filesystem refusals. The failure is
+ * intentionally still captured: this is instrumentation for the OneDrive /
+ * antivirus / path-length hypotheses, not an expected-error suppression.
+ */
+export function filesystemErrorCaptureContext(err, argv = process.argv) {
+    const details = findFilesystemError(err);
+    if (!details)
+        return null;
+    const resolvedPath = canonicalPath(details.rawPath);
+    const safePath = redactedPath(details.rawPath);
+    const command = hqCommand(argv);
+    return {
+        fingerprint: ["fs-error", details.code, details.syscall, command],
+        tags: {
+            fs_code: details.code,
+            fs_syscall: details.syscall,
+            path_kind: pathKind(details.rawPath, resolvedPath),
+            synced_folder: syncedFolder(resolvedPath),
+            path_len_bucket: pathLengthBucket(details.rawPath),
+            file_attributes: fileAttributes(details.record, details.rawPath),
+            hq_command: command,
+            platform: process.platform,
+            hq_cli_version: CLI_VERSION,
+        },
+        extra: {
+            fs_path: safePath,
+            fs_reason: redactErrorText(`${details.code} ${details.syscall} failed at ${safePath}`),
+        },
+    };
+}
+/** Plain operator guidance for a captured filesystem failure. */
+export function filesystemErrorMessage(err) {
+    const details = findFilesystemError(err);
+    if (!details)
         return null;
-    return ENVIRONMENTAL_FS_CODES[code] ?? null;
+    const resolvedPath = canonicalPath(details.rawPath);
+    const safePath = redactedPath(details.rawPath);
+    const synced = syncedFolder(resolvedPath);
+    const permissionDenied = details.code === "EACCES" || details.code === "EPERM";
+    const remedy = permissionDenied && process.platform !== "win32" && synced === "none"
+        ? "Check file and folder permissions, close the file, then retry."
+        : "Close the file or exclude its folder from cloud sync; if it persists, check permissions, then retry.";
+    return `Filesystem operation ${details.syscall} failed (${details.code}) at ${safePath}. ${remedy}`;
 }
 //# sourceMappingURL=environmental-error.js.map

package/dist/utils/expected-cli-error.d.ts

@@ -5,6 +5,8 @@
 export interface ExpectedUserError extends Error {
     expected: true;
 }
+/** Stamp an existing Error with the boundary's caller-owned disposition. */
+export declare function markExpectedUserError<T extends Error>(err: T): T & ExpectedUserError;
 /**
  * True when `err` is an Error explicitly marked `expected === true`. A non-null
  * result means the top-level handler should print `err.message` and skip Sentry

package/dist/utils/expected-cli-error.js

@@ -16,6 +16,10 @@
 // ("Only a company owner can approve or reject queued integration writes"); the
 // thrown error propagated to the top-level handler, which captured it to Sentry
 // as an error-level crash and printed nothing to the user.
+/** Stamp an existing Error with the boundary's caller-owned disposition. */
+export function markExpectedUserError(err) {
+    return Object.assign(err, { expected: true });
+}
 /**
  * True when `err` is an Error explicitly marked `expected === true`. A non-null
  * result means the top-level handler should print `err.message` and skip Sentry

package/dist/utils/self-update.js

@@ -282,7 +282,10 @@ async function updateAndReexec(argv, flavor, known, deps) {
     // A resident mesh daemon keeps the old JS loaded after a global install.
     // Service restart is best-effort and cannot turn a successful update red.
     try {
-        const restart = (deps.restartDaemon ?? restartDaemonServiceIfInstalled)();
+        const restart = (deps.restartDaemon ?? (() => restartDaemonServiceIfInstalled({
+            env,
+            hqRoot: env.HQ_ROOT,
+        })))();
         if (restart?.message)
             console.error(chalk.yellow(`  ${restart.message}`));
     }

package/dist/utils/vault-api.d.ts

@@ -11,6 +11,7 @@ export interface VaultApiOptions {
     method?: string;
     body?: Record<string, unknown>;
     query?: Record<string, string>;
+    headers?: Record<string, string>;
     signal?: AbortSignal;
 }
 /**