@indigoai-us/hq-cli 5.108.17 → 5.108.18

package/CHANGELOG.md

@@ -2,8 +2,44 @@
 
 ## [Unreleased]
 
+## [5.108.18] — 2026-09-07
+
+### Fixed
+
+- A global `hq` reinstall running underneath a starting command no longer
+  crashes it (Sentry HQ-CLI-1G/1H/1J/1K — 7713386011, 7713482655, 7713783135,
+  7714501738). `hq` resolves most of its command graph lazily as its first real
+  step, so when an external updater — the outpost `hq-cli-update` timer, an
+  agent box's self-update, or the desktop app — renames the installed package
+  aside and re-extracts it file by file (~16s every 6h on every box), a command
+  that started a moment earlier resolved a deferred import against a directory
+  that no longer held it and died with `ERR_MODULE_NOT_FOUND` /
+  `MODULE_NOT_FOUND`, filing a separate high-priority crash for each missing
+  path. hq-cli cannot stop the foreign updater, but the registration phase is
+  provably side-effect free (it runs before any command action), so a
+  resolution failure there is now caught: the CLI prints one informational line,
+  waits — bounded, default 90s, `HQ_INSTALL_SETTLE_TIMEOUT_MS` to override — for
+  the install to settle (shared update lock released, the missing target back,
+  the retired `.hq-cli-*` sibling gone, a healthy manifest), and then re-runs
+  the command once on the settled tree. A genuinely broken or incomplete install
+  still reports exactly once, with a reinstall remedy naming the missing module
+  and bounded diagnostics, so real packaging faults stay visible. The recovery
+  re-execs at most once per invocation and never runs a command twice.
+
 ## [5.108.17] — 2026-09-07
 
+### Fixed
+
+- The Work Mesh Live daemon's transcript watcher no longer rescans every file
+  under `~/.claude/projects` and `~/.codex/sessions` every 15 seconds. It keeps a
+  per-directory mtime cache and only relists directories that changed, re-stats
+  recently active files, revalidates every cached directory at least every five
+  minutes (content appends do not change a directory's mtime, so a session that
+  resumes after idling is still picked up), backs the interval off from 30 s to
+  120 s on busy machines, caps the entries examined per tick with per-root
+  budgets, never runs two ticks at once, and bounds its cache. Capped ticks skip
+  disappearance reconciliation so an unvisited session is never ended falsely.
+
 ## [5.108.16] — 2026-09-07
 
 ### Fixed
@@ -41,15 +77,6 @@
   at most every five minutes, and `held.jsonl` is capped at 20,000 lines with
   the oldest overflow dead-lettered as `HELD_OVERFLOW` (loss-free under failure
   and concurrent flushers). (#525)
-- The Work Mesh Live daemon's transcript watcher no longer rescans every file
-  under `~/.claude/projects` and `~/.codex/sessions` every 15 seconds. It keeps a
-  per-directory mtime cache and only relists directories that changed, re-stats
-  recently active files, revalidates every cached directory at least every five
-  minutes (content appends do not change a directory's mtime, so a session that
-  resumes after idling is still picked up), backs the interval off from 30 s to
-  120 s on busy machines, caps the entries examined per tick with per-root
-  budgets, never runs two ticks at once, and bounds its cache. Capped ticks skip
-  disappearance reconciliation so an unvisited session is never ended falsely.
 
 ## [5.108.14] — 2026-09-07
 
@@ -81,15 +108,6 @@
   `incomplete_install` context so the next occurrence is attributable. The drop
   is wired both at the top-level boundary and in the shared `beforeSend`, so it
   covers every capture route.
-- The Work Mesh Live daemon's transcript watcher no longer rescans every file
-  under `~/.claude/projects` and `~/.codex/sessions` every 15 seconds. It keeps a
-  per-directory mtime cache and only relists directories that changed, re-stats
-  recently active files, revalidates every cached directory at least every five
-  minutes (content appends do not change a directory's mtime, so a session that
-  resumes after idling is still picked up), backs the interval off from 30 s to
-  120 s on busy machines, caps the entries examined per tick with per-root
-  budgets, never runs two ticks at once, and bounds its cache. Capped ticks skip
-  disappearance reconciliation so an unvisited session is never ended falsely.
 
 ## [5.108.13] — 2026-09-06
 

package/dist/main.js

@@ -6,6 +6,8 @@
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
 import "./node-network-compat.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
@@ -46,10 +48,19 @@ import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 import { kickFlagRegistryReadiness } from "./lib/flag-registry.js";
 import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
+import { registerCommandsWithRecovery } from "./startup-registration.js";
+import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTreeTornError, } from "./utils/install-tree-torn.js";
 import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 /** Hard upper bound for non-user-visible release-health finalization. */
 const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
+/**
+ * The RUNNING install's own entrypoint (`<pkg>/dist/index.js`), used as the
+ * torn-install recovery re-exec target. It must be this resolved path — never
+ * `hq` from PATH — because a global reinstall leaves `bin/hq` absent for much of
+ * the rewrite window, while this path now holds the settled tree.
+ */
+const RUNNING_ENTRY_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
 const defaultStreamErrorDependencies = {
     stderr: process.stderr,
     exit: (code) => process.exit(code),
@@ -160,13 +171,31 @@ export async function runCli() {
         // `--help`, a bare `hq`, an unknown command, any command not on the
         // manifest — falls back to the complete graph, so its behaviour is
         // unchanged. See register-all.ts for the measurements that motivated this.
-        const lazy = findLazyCommand(process.argv);
-        if (lazy) {
-            await lazy.register(program);
-        }
-        else {
-            const { registerAllCommands } = await import("./register-all.js");
-            registerAllCommands(program);
+        // The same lazy/full registration as before, wrapped so it recovers ONCE if
+        // a global reinstall is tearing the install tree out from under these
+        // deferred imports (Sentry HQ-CLI-1G/1H/1J/1K). Which modules are imported,
+        // and in what order, is unchanged — only the failure handling is added.
+        const registration = await registerCommandsWithRecovery({
+            register: async () => {
+                const lazy = findLazyCommand(process.argv);
+                if (lazy) {
+                    await lazy.register(program);
+                }
+                else {
+                    const { registerAllCommands } = await import("./register-all.js");
+                    registerAllCommands(program);
+                }
+            },
+            argv: process.argv,
+            env: process.env,
+            entryPath: RUNNING_ENTRY_PATH,
+            stderr: process.stderr,
+        });
+        if (registration.reexecStatus !== undefined) {
+            // The re-exec'd child ran the command on the settled tree; carry its exit
+            // status out (after the finally block), exactly as the self-update re-exec.
+            reexecStatus = registration.reexecStatus;
+            return;
         }
         await program.parseAsync();
     }
@@ -337,6 +366,21 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         });
         deps.setExitCode(1);
     }
+    else if (isInstallTreeTornError(err)) {
+        // HQ-CLI-1G/1H/1J/1K: a global reinstall tore the install tree out from
+        // under a starting `hq` and the bounded settle-wait + single re-exec could
+        // not recover it (a still-incomplete tree, a foreign updater, or a failed
+        // re-exec). Print the fixed reinstall remedy naming the bounded missing
+        // specifier, and STILL capture WITH bounded diagnostics — a genuinely
+        // pruned or incomplete install must stay visible. Mirrors the package-root
+        // branch's print-and-capture shape; a class-instance check disjoint from
+        // every neighbour, so no existing ordering changes. A SUCCESSFUL recovery
+        // never reaches here (it returns the child's status), so this line and this
+        // capture only ever mark a real, unrecovered break.
+        deps.stderr.write(`hq: ${installTreeTornStderrLine(err)}\n`);
+        deps.sentry.captureException(err, installTreeTornCaptureContext(err));
+        deps.setExitCode(1);
+    }
     else if (isVaultAccessDeniedError(err)) {
         // ARM B (Sentry 7709408531): `hq skill create`'s post-register vault sync
         // was DENIED by S3 — an AWS SDK v3 403 from an hq-pro IAM session-policy

package/dist/startup-registration.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The command-registration recovery seam for the "install tree torn out from
+ * under a starting `hq`" condition (Sentry HQ-CLI-1G/1H/1J/1K).
+ *
+ * `runCli` registers commands as its last step before `program.parseAsync()` —
+ * the lazy command import or `import("./register-all.js")` and everything those
+ * pull in. That is the ONE place a module-resolution failure is provably safe to
+ * recover from: it is inside hq-cli's own graph, it runs before `parseAsync` and
+ * before the preAction hook, so no command action, telemetry, or stdin read has
+ * happened yet, and a single re-exec can therefore never run a command twice.
+ *
+ * This wraps the existing `register()` call with exactly that recovery, driven by
+ * the classifier / probe / settle wait / carrier in ./utils/install-tree-torn.ts.
+ * It changes nothing about WHICH modules are imported or in what order — only the
+ * failure handling around the existing imports. Dependency-injected in the house
+ * style of handleTopLevelError so the whole seam is unit-testable without real
+ * spawns, waits, or a real install tree.
+ */
+import { type WaitForInstallTreeSettledArgs, type WaitForInstallTreeSettledResult } from "./utils/install-tree-torn.js";
+/**
+ * Set on the re-exec'd child so it can NEVER wait or re-exec again — distinct
+ * from self-update's HQ_RESCUE_SELF_UPDATED so the two recovery paths cannot
+ * shadow each other.
+ */
+export declare const INSTALL_TREE_RECOVERY_GUARD_ENV = "HQ_INSTALL_TREE_RECOVERED";
+/** Operator override for the settle wait's deadline. */
+export declare const INSTALL_SETTLE_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_TIMEOUT_MS";
+/** Default settle deadline (ms). Overridable by {@link INSTALL_SETTLE_TIMEOUT_ENV}. */
+export declare const DEFAULT_INSTALL_SETTLE_TIMEOUT_MS = 90000;
+/**
+ * The single dim, informational line emitted when — and only when — a wait
+ * actually happens. It tells a human why the command paused and is the e2e's
+ * synchronization point; it is never a remedy and never sets an error exit code.
+ */
+export declare const INSTALL_TREE_WAIT_NOTICE = "hq: the hq-cli install is being updated underneath this command; waiting for it to finish\u2026";
+/** Resolve the settle deadline from the environment (0 = evaluate once; default on invalid). */
+export declare function resolveSettleTimeoutMs(env: NodeJS.ProcessEnv): number;
+/** Minimal view of a `spawnSync` result the seam relies on. */
+export interface RecoverySpawnResult {
+    status: number | null;
+    error?: Error;
+}
+export interface RegisterRecoveryDeps {
+    spawn?: (command: string, args: string[], options: {
+        stdio: "inherit";
+        env: NodeJS.ProcessEnv;
+    }) => RecoverySpawnResult;
+    resolveInstall?: () => {
+        packageRoot: string | null;
+    };
+    lockPath?: () => string;
+    waitForSettled?: (args: WaitForInstallTreeSettledArgs) => Promise<WaitForInstallTreeSettledResult>;
+    /** node flags to forward to the re-exec child (defaults to process.execArgv). */
+    execArgv?: readonly string[];
+}
+export interface RegisterCommandsWithRecoveryArgs {
+    /** Runs the existing registration (lazy command import or register-all import). */
+    register: () => Promise<void>;
+    argv: readonly string[];
+    env: NodeJS.ProcessEnv;
+    /** The RUNNING install's own `dist/index.js` — the safe re-exec target. */
+    entryPath: string;
+    stderr: Pick<typeof process.stderr, "write">;
+    deps?: RegisterRecoveryDeps;
+}
+export interface RegisterCommandsWithRecoveryResult {
+    /** Set only when a re-exec ran: its exit status becomes this invocation's. */
+    reexecStatus?: number;
+}
+/**
+ * Register commands, recovering once from a torn-install module-resolution
+ * failure. On a clean registration this returns `{}` and touches nothing else.
+ * On a classified failure it waits (bounded) for the install to settle and
+ * re-execs the running install's own entrypoint once; a child (guarded), an
+ * unsettled wait, or a failed spawn each throws an {@link InstallTreeTornError}
+ * carrying bounded diagnostics so a genuinely broken install stays visible.
+ */
+export declare function registerCommandsWithRecovery(args: RegisterCommandsWithRecoveryArgs): Promise<RegisterCommandsWithRecoveryResult>;
+//# sourceMappingURL=startup-registration.d.ts.map

package/dist/startup-registration.js

@@ -0,0 +1,134 @@
+/**
+ * The command-registration recovery seam for the "install tree torn out from
+ * under a starting `hq`" condition (Sentry HQ-CLI-1G/1H/1J/1K).
+ *
+ * `runCli` registers commands as its last step before `program.parseAsync()` —
+ * the lazy command import or `import("./register-all.js")` and everything those
+ * pull in. That is the ONE place a module-resolution failure is provably safe to
+ * recover from: it is inside hq-cli's own graph, it runs before `parseAsync` and
+ * before the preAction hook, so no command action, telemetry, or stdin read has
+ * happened yet, and a single re-exec can therefore never run a command twice.
+ *
+ * This wraps the existing `register()` call with exactly that recovery, driven by
+ * the classifier / probe / settle wait / carrier in ./utils/install-tree-torn.ts.
+ * It changes nothing about WHICH modules are imported or in what order — only the
+ * failure handling around the existing imports. Dependency-injected in the house
+ * style of handleTopLevelError so the whole seam is unit-testable without real
+ * spawns, waits, or a real install tree.
+ */
+import { spawnSync } from "node:child_process";
+import { resolveRunningInstall } from "./utils/version-gate.js";
+import { updateLockPath } from "./utils/update-lock.js";
+import { classifyModuleNotFound, InstallTreeTornError, waitForInstallTreeSettled, } from "./utils/install-tree-torn.js";
+/**
+ * Set on the re-exec'd child so it can NEVER wait or re-exec again — distinct
+ * from self-update's HQ_RESCUE_SELF_UPDATED so the two recovery paths cannot
+ * shadow each other.
+ */
+export const INSTALL_TREE_RECOVERY_GUARD_ENV = "HQ_INSTALL_TREE_RECOVERED";
+/** Operator override for the settle wait's deadline. */
+export const INSTALL_SETTLE_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_TIMEOUT_MS";
+/** Default settle deadline (ms). Overridable by {@link INSTALL_SETTLE_TIMEOUT_ENV}. */
+export const DEFAULT_INSTALL_SETTLE_TIMEOUT_MS = 90_000;
+/**
+ * The single dim, informational line emitted when — and only when — a wait
+ * actually happens. It tells a human why the command paused and is the e2e's
+ * synchronization point; it is never a remedy and never sets an error exit code.
+ */
+export const INSTALL_TREE_WAIT_NOTICE = "hq: the hq-cli install is being updated underneath this command; waiting for it to finish…";
+/** Resolve the settle deadline from the environment (0 = evaluate once; default on invalid). */
+export function resolveSettleTimeoutMs(env) {
+    const raw = env[INSTALL_SETTLE_TIMEOUT_ENV];
+    if (typeof raw !== "string" || raw.trim() === "")
+        return DEFAULT_INSTALL_SETTLE_TIMEOUT_MS;
+    if (!/^\d+$/.test(raw.trim()))
+        return DEFAULT_INSTALL_SETTLE_TIMEOUT_MS;
+    return Number.parseInt(raw.trim(), 10);
+}
+/**
+ * Register commands, recovering once from a torn-install module-resolution
+ * failure. On a clean registration this returns `{}` and touches nothing else.
+ * On a classified failure it waits (bounded) for the install to settle and
+ * re-execs the running install's own entrypoint once; a child (guarded), an
+ * unsettled wait, or a failed spawn each throws an {@link InstallTreeTornError}
+ * carrying bounded diagnostics so a genuinely broken install stays visible.
+ */
+export async function registerCommandsWithRecovery(args) {
+    const { register, argv, env, entryPath, stderr } = args;
+    const deps = args.deps ?? {};
+    try {
+        await register();
+        return {};
+    }
+    catch (err) {
+        const classified = classifyModuleNotFound(err);
+        // Not a module-resolution failure — rethrow the SAME object to the existing
+        // boundary, preserving today's behaviour exactly.
+        if (!classified)
+            throw err;
+        const packageRoot = resolvePackageRoot(deps);
+        // A child that already recovered must never wait or re-exec again: report
+        // once and let the boundary capture it.
+        if (env[INSTALL_TREE_RECOVERY_GUARD_ENV] === "1") {
+            throw new InstallTreeTornError({
+                cause: err,
+                classified,
+                packageRoot,
+                outcome: "guarded",
+                attempt: 2,
+                waitedMs: 0,
+                sawLock: false,
+                sawRetired: false,
+            });
+        }
+        stderr.write(`${INSTALL_TREE_WAIT_NOTICE}\n`);
+        const lockPath = (deps.lockPath ?? updateLockPath)();
+        const waitFor = deps.waitForSettled ?? waitForInstallTreeSettled;
+        const result = await waitFor({
+            target: classified.target,
+            packageRoot,
+            lockPath,
+            deadlineMs: resolveSettleTimeoutMs(env),
+        });
+        if (!result.settled) {
+            throw new InstallTreeTornError({
+                cause: err,
+                classified,
+                packageRoot,
+                outcome: "unsettled",
+                attempt: 1,
+                waitedMs: result.waitedMs,
+                sawLock: result.sawLock,
+                sawRetired: result.sawRetired,
+            });
+        }
+        const spawn = deps.spawn ?? spawnSync;
+        const execArgv = deps.execArgv ?? process.execArgv;
+        const child = spawn(process.execPath, [...execArgv, entryPath, ...argv.slice(2)], { stdio: "inherit", env: { ...env, [INSTALL_TREE_RECOVERY_GUARD_ENV]: "1" } });
+        if (child.error) {
+            throw new InstallTreeTornError({
+                cause: err,
+                classified,
+                packageRoot,
+                outcome: "reexec-failed",
+                attempt: 1,
+                waitedMs: result.waitedMs,
+                sawLock: result.sawLock,
+                sawRetired: result.sawRetired,
+            });
+        }
+        // A signal-killed child has status null; surface it as a failure exit rather
+        // than pretending the command completed (mirrors self-update's reexecHq).
+        return { reexecStatus: child.status ?? 1 };
+    }
+}
+/** Resolve the running install's package dir, tolerating any resolver failure. */
+function resolvePackageRoot(deps) {
+    try {
+        return (deps.resolveInstall ?? resolveRunningInstall)().packageRoot;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=startup-registration.js.map

package/dist/utils/install-tree-torn.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Detection and bounded, recovery-safe reporting for the "install tree torn out
+ * from under a starting `hq`" condition (Sentry HQ-CLI-1G/1H/1J/1K —
+ * 7713386011, 7713482655, 7713783135, 7714501738).
+ *
+ * hq-cli resolves most of its module graph lazily INSIDE `runCli` (the lazy
+ * command module or `import("./register-all.js")`, plus everything those pull in
+ * — nested `@aws-sdk/*`, `js-yaml`, `@indigoai-us/hq-cloud`). An EXTERNAL global
+ * reinstall — the outpost `hq-cli-update` systemd timer every 6h, the agent
+ * boxes' `self_update`, the desktop app — renames the installed package dir
+ * aside (`.hq-cli-<rand>`), recreates it empty, and re-extracts it file by file
+ * over ~16s. A process that started just before that rename resolves its
+ * deferred imports against a directory that no longer holds them and dies with
+ * ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND. None of those writers is the process's
+ * OWN updater (the version-gate and self-updater install synchronously under the
+ * shared lock and never overlap their own imports), so hq-cli cannot stop them —
+ * but it CAN detect the condition at the one seam where it is provably
+ * side-effect free (the registration phase, before `parseAsync` and before the
+ * preAction hook), wait (bounded) for the install to settle, and re-run itself
+ * once on the settled tree.
+ *
+ * This module is the reusable core of that recovery: a STRUCTURAL, closed
+ * classifier for the loader-error dialects Node raises; a readiness probe that
+ * re-resolves the missing target exactly as Node's resolver does; a bounded
+ * settle wait keyed on the same signals the writer leaves behind; and the typed
+ * carrier + boundary helpers (house style of package-root-diagnostics.ts) that
+ * keep a genuinely-broken install VISIBLE in Sentry with bounded, hq-derived
+ * diagnostics. The recovery seam that drives them lives in
+ * ../startup-registration.ts; version-gate.ts / self-update.ts / update-lock.ts
+ * are only READ (their exported symbols), never modified.
+ */
+/** The two loader-error `code`s that mean "a module could not be resolved". */
+export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND";
+/**
+ * The closed set of resolution-failure dialects, verified on Node v22.23.1 (the
+ * @sentry/node import-in-the-middle hook does not change the shapes):
+ *   - `esm-path`:    ESM importer, an absolute file (or legacyMainResolve dir)
+ *                    target — `err.url` set, or `Cannot find package '<abs>'…`.
+ *   - `esm-package`: ESM importer, a bare specifier — `Cannot find package
+ *                    '<name>' imported from <importer>`, no `err.url`.
+ *   - `cjs-path`:    CJS require of an absolute path — `Cannot find module
+ *                    '<abs>'` + `requireStack`.
+ *   - `cjs-package`: CJS require of a bare specifier — `Cannot find module
+ *                    '<name>'` + `requireStack`.
+ *   - `unknown`:     a module-not-found whose message did not parse; recovery
+ *                    still waits on the lock / retired-dir / quiet signals.
+ */
+export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "unknown";
+/**
+ * The missing thing, re-resolvable by the readiness probe:
+ *   - `path`:    an absolute filesystem path (a `.js` file, or a package dir).
+ *   - `package`: a bare package `name` resolvable from directory `from` upward.
+ *   - `unknown`: the message did not parse; treated as "present" by the probe so
+ *                readiness turns only on the lock / retired-dir / quiet signals.
+ */
+export type ModuleErrorTarget = {
+    kind: "path";
+    path: string;
+} | {
+    kind: "package";
+    name: string;
+    from: string;
+} | {
+    kind: "unknown";
+};
+export interface ClassifiedModuleError {
+    code: ModuleNotFoundCode;
+    dialect: ModuleErrorDialect;
+    /** The raw specifier the message named (absolute path or bare name), or "". */
+    specifier: string;
+    /** The importer the message named (from-clause or requireStack[0]), or "". */
+    importer: string;
+    target: ModuleErrorTarget;
+}
+/**
+ * Reduce a bare specifier to its PACKAGE name: `@scope/name/sub` → `@scope/name`,
+ * `name/sub` → `name`, `name` → `name`. This is the unit the readiness probe
+ * re-resolves (Node looks up `node_modules/<package>/package.json`, never the
+ * subpath, when it raises the bare-specifier dialects).
+ */
+export declare function packageNameOf(specifier: string): string;
+/**
+ * Classify a thrown value as a module-resolution failure and extract the missing
+ * target, or return `null` for anything that is not one. The decision is
+ * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND` or
+ * `MODULE_NOT_FOUND` — no argv, env, or free text is ever consulted, and any
+ * other error (including an import-time throw of another class) returns `null`
+ * so it is rethrown to the existing boundary unchanged.
+ */
+export declare function classifyModuleNotFound(err: unknown): ClassifiedModuleError | null;
+/** The filesystem surface the probe and wait use, injectable for hermetic tests. */
+export interface InstallTreeFs {
+    existsSync(p: string): boolean;
+    statSync(p: string): {
+        isDirectory(): boolean;
+    };
+    readFileSync(p: string, encoding: "utf-8"): string;
+    readdirSync(p: string): string[];
+}
+/**
+ * Whether the missing target is now present on disk — the readiness signal the
+ * settle wait polls. It re-resolves the SAME step Node's resolver took:
+ *   - `path`:    the file must exist; a directory target must additionally hold
+ *                a `package.json` (the legacyMainResolve case).
+ *   - `package`: walk from `from` toward the filesystem root and return true as
+ *                soon as `<dir>/node_modules/<name>/package.json` exists — the
+ *                exact ancestor walk `getPackageJSONURL` performs, done WITHOUT
+ *                `createRequire` so an ESM-only / export-conditioned package
+ *                cannot false-negative.
+ *   - `unknown`: true (readiness turns on the other signals).
+ * Any filesystem error reads as "not present" rather than throwing.
+ */
+export declare function installTargetPresent(target: ModuleErrorTarget, fs?: InstallTreeFs): boolean;
+export interface WaitForInstallTreeSettledArgs {
+    target: ModuleErrorTarget;
+    /** The running install's package dir (from resolveRunningInstall), or null. */
+    packageRoot: string | null;
+    /** The shared update-lock path ($HOME/.hq/locks/cli-update.lock). */
+    lockPath: string;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    fs?: InstallTreeFs;
+    isPidAlive?: (pid: number) => boolean;
+    pollMs?: number;
+    quietMs?: number;
+    deadlineMs: number;
+}
+export interface WaitForInstallTreeSettledResult {
+    settled: boolean;
+    waitedMs: number;
+    /** A FRESH update lock held by another pid was observed at least once. */
+    sawLock: boolean;
+    /** An npm retired/staging sibling (`.hq-cli-<rand>`) was observed at least once. */
+    sawRetired: boolean;
+}
+/**
+ * Poll until the install tree has been continuously READY for `quietMs`, or the
+ * `deadlineMs` passes. READY means: (i) no FRESH update lock held by another pid,
+ * (ii) the missing target is present, and — when `packageRoot` is known —
+ * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and
+ * (iv) no `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem
+ * error makes its condition "not ready" rather than throwing. `deadlineMs === 0`
+ * evaluates readiness exactly once (no waiting); otherwise the whole wait is
+ * bounded, so the caller can never hang.
+ */
+export declare function waitForInstallTreeSettled(args: WaitForInstallTreeSettledArgs): Promise<WaitForInstallTreeSettledResult>;
+/** The recovery OUTCOME, which — not the dialect — decides capture. */
+export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed";
+export type InstallTreeTornDiagnostics = {
+    dialect: ModuleErrorDialect;
+    code: ModuleNotFoundCode;
+    specifier: string;
+    importer: string;
+    packageRoot: string;
+    outcome: InstallTreeTornOutcome;
+    attempt: 1 | 2;
+    waitedMs: number;
+    sawLock: boolean;
+    sawRetired: boolean;
+    node: string;
+};
+export interface InstallTreeTornInit {
+    /** The original loader error, carried unchanged as `cause`. */
+    cause: unknown;
+    classified: ClassifiedModuleError;
+    packageRoot: string | null;
+    outcome: InstallTreeTornOutcome;
+    attempt: 1 | 2;
+    waitedMs: number;
+    sawLock: boolean;
+    sawRetired: boolean;
+}
+/**
+ * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived
+ * diagnostics. Fixed `name`/`message` (no argv, path, or free text in either),
+ * `cause` = the original loader error, and a bounded `diagnostics` object whose
+ * only interpolated strings are the hq-derived specifier/importer/packageRoot,
+ * each capped. Mirrors PackageRootResolutionError's construction discipline.
+ */
+export declare class InstallTreeTornError extends Error {
+    readonly diagnostics: InstallTreeTornDiagnostics;
+    constructor(init: InstallTreeTornInit);
+}
+export declare function isInstallTreeTornError(err: unknown): err is InstallTreeTornError;
+/** The exact Sentry `contexts` payload for a captured torn-install failure. */
+export declare function installTreeTornCaptureContext(err: InstallTreeTornError): {
+    contexts: {
+        install_tree_torn: InstallTreeTornDiagnostics;
+    };
+};
+/**
+ * The fixed, input-free operator remedy. It names the likely writers (so a
+ * human knows this was not their command's fault) and the reinstall commands,
+ * and interpolates NOTHING — the only per-event value is the bounded specifier
+ * appended by {@link installTreeTornStderrLine}.
+ */
+export declare const INSTALL_TREE_TORN_REMEDY: string;
+/**
+ * The single actionable stderr line for a captured torn-install failure: the
+ * fixed remedy plus the bounded, hq-derived missing specifier — the only
+ * interpolated value, never argv.
+ */
+export declare function installTreeTornStderrLine(err: InstallTreeTornError): string;
+//# sourceMappingURL=install-tree-torn.d.ts.map

package/dist/utils/install-tree-torn.js

@@ -0,0 +1,359 @@
+/**
+ * Detection and bounded, recovery-safe reporting for the "install tree torn out
+ * from under a starting `hq`" condition (Sentry HQ-CLI-1G/1H/1J/1K —
+ * 7713386011, 7713482655, 7713783135, 7714501738).
+ *
+ * hq-cli resolves most of its module graph lazily INSIDE `runCli` (the lazy
+ * command module or `import("./register-all.js")`, plus everything those pull in
+ * — nested `@aws-sdk/*`, `js-yaml`, `@indigoai-us/hq-cloud`). An EXTERNAL global
+ * reinstall — the outpost `hq-cli-update` systemd timer every 6h, the agent
+ * boxes' `self_update`, the desktop app — renames the installed package dir
+ * aside (`.hq-cli-<rand>`), recreates it empty, and re-extracts it file by file
+ * over ~16s. A process that started just before that rename resolves its
+ * deferred imports against a directory that no longer holds them and dies with
+ * ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND. None of those writers is the process's
+ * OWN updater (the version-gate and self-updater install synchronously under the
+ * shared lock and never overlap their own imports), so hq-cli cannot stop them —
+ * but it CAN detect the condition at the one seam where it is provably
+ * side-effect free (the registration phase, before `parseAsync` and before the
+ * preAction hook), wait (bounded) for the install to settle, and re-run itself
+ * once on the settled tree.
+ *
+ * This module is the reusable core of that recovery: a STRUCTURAL, closed
+ * classifier for the loader-error dialects Node raises; a readiness probe that
+ * re-resolves the missing target exactly as Node's resolver does; a bounded
+ * settle wait keyed on the same signals the writer leaves behind; and the typed
+ * carrier + boundary helpers (house style of package-root-diagnostics.ts) that
+ * keep a genuinely-broken install VISIBLE in Sentry with bounded, hq-derived
+ * diagnostics. The recovery seam that drives them lives in
+ * ../startup-registration.ts; version-gate.ts / self-update.ts / update-lock.ts
+ * are only READ (their exported symbols), never modified.
+ */
+import * as nodeFs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CLI_NAME } from "../cli-version.js";
+import { boundedDiagnosticValue } from "./package-root-diagnostics.js";
+import { isLockStale } from "./update-lock.js";
+/** Byte caps for the (hq-derived, path-shaped) diagnostic strings. */
+const SPECIFIER_BYTES = 256;
+const IMPORTER_BYTES = 256;
+const PACKAGE_ROOT_BYTES = 256;
+const ESM_PACKAGE_RE = /^Cannot find package '([^']+)' imported from (.+)$/s;
+const CJS_MODULE_RE = /^Cannot find module '([^']+)'/s;
+const ESM_MODULE_IMPORTED_RE = /^Cannot find module '([^']+)' imported from (.+)$/s;
+/**
+ * Reduce a bare specifier to its PACKAGE name: `@scope/name/sub` → `@scope/name`,
+ * `name/sub` → `name`, `name` → `name`. This is the unit the readiness probe
+ * re-resolves (Node looks up `node_modules/<package>/package.json`, never the
+ * subpath, when it raises the bare-specifier dialects).
+ */
+export function packageNameOf(specifier) {
+    const parts = specifier.split("/");
+    if (specifier.startsWith("@"))
+        return parts.slice(0, 2).join("/");
+    return parts[0] ?? specifier;
+}
+/**
+ * Classify a thrown value as a module-resolution failure and extract the missing
+ * target, or return `null` for anything that is not one. The decision is
+ * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND` or
+ * `MODULE_NOT_FOUND` — no argv, env, or free text is ever consulted, and any
+ * other error (including an import-time throw of another class) returns `null`
+ * so it is rethrown to the existing boundary unchanged.
+ */
+export function classifyModuleNotFound(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    const code = record.code;
+    if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND")
+        return null;
+    const message = typeof record.message === "string" ? record.message : "";
+    // (a) ESM path — `err.url` is a `file:` URL. This is checked first because the
+    // ESM path message ALSO matches the imported-from dialect (d); the url is the
+    // authoritative resolved target.
+    if (typeof record.url === "string" && record.url.startsWith("file:")) {
+        const target = fileURLToPath(record.url);
+        const importer = ESM_MODULE_IMPORTED_RE.exec(message)?.[2] ?? "";
+        return { code, dialect: "esm-path", specifier: target, importer, target: { kind: "path", path: target } };
+    }
+    // (b) ESM `Cannot find package '<spec>' imported from <importer>`. `<spec>` is
+    // a bare name for the ordinary case, or an ABSOLUTE `<dir>/index.js` token for
+    // the legacyMainResolve variant (a package dir that exists but has no usable
+    // package.json/main) — the latter is a path target.
+    const esmPkg = ESM_PACKAGE_RE.exec(message);
+    if (esmPkg) {
+        const spec = esmPkg[1];
+        const importer = esmPkg[2];
+        if (path.isAbsolute(spec)) {
+            return { code, dialect: "esm-path", specifier: spec, importer, target: { kind: "path", path: spec } };
+        }
+        return {
+            code,
+            dialect: "esm-package",
+            specifier: spec,
+            importer,
+            target: { kind: "package", name: spec, from: path.dirname(importer) },
+        };
+    }
+    // (c) CJS `Cannot find module '<spec>'` (+ Require stack). Absolute → a path
+    // target; bare → the package the require named, resolved from requireStack[0].
+    if (code === "MODULE_NOT_FOUND") {
+        const cjs = CJS_MODULE_RE.exec(message);
+        if (cjs) {
+            const spec = cjs[1];
+            const requireStack = Array.isArray(record.requireStack) ? record.requireStack : [];
+            const importer = typeof requireStack[0] === "string" ? requireStack[0] : "";
+            if (path.isAbsolute(spec)) {
+                return { code, dialect: "cjs-path", specifier: spec, importer, target: { kind: "path", path: spec } };
+            }
+            return {
+                code,
+                dialect: "cjs-package",
+                specifier: spec,
+                importer,
+                target: { kind: "package", name: packageNameOf(spec), from: path.dirname(importer) },
+            };
+        }
+    }
+    // (d) ESM `Cannot find module '<abs>' imported from <importer>` WITHOUT a url
+    // (defensive — the url arm normally wins). The specifier is the resolved
+    // absolute path.
+    const esmMod = ESM_MODULE_IMPORTED_RE.exec(message);
+    if (esmMod) {
+        const spec = esmMod[1];
+        return { code, dialect: "esm-path", specifier: spec, importer: esmMod[2], target: { kind: "path", path: spec } };
+    }
+    // (e) A module-not-found whose message did not parse — still recover, keyed on
+    // the lock / retired-dir / quiet signals only.
+    return { code, dialect: "unknown", specifier: "", importer: "", target: { kind: "unknown" } };
+}
+const nodeInstallTreeFs = {
+    existsSync: (p) => nodeFs.existsSync(p),
+    statSync: (p) => nodeFs.statSync(p),
+    readFileSync: (p, encoding) => nodeFs.readFileSync(p, encoding),
+    readdirSync: (p) => nodeFs.readdirSync(p),
+};
+/** Liveness probe with update-lock.ts's semantics (ESRCH dead, EPERM alive). */
+function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Whether the missing target is now present on disk — the readiness signal the
+ * settle wait polls. It re-resolves the SAME step Node's resolver took:
+ *   - `path`:    the file must exist; a directory target must additionally hold
+ *                a `package.json` (the legacyMainResolve case).
+ *   - `package`: walk from `from` toward the filesystem root and return true as
+ *                soon as `<dir>/node_modules/<name>/package.json` exists — the
+ *                exact ancestor walk `getPackageJSONURL` performs, done WITHOUT
+ *                `createRequire` so an ESM-only / export-conditioned package
+ *                cannot false-negative.
+ *   - `unknown`: true (readiness turns on the other signals).
+ * Any filesystem error reads as "not present" rather than throwing.
+ */
+export function installTargetPresent(target, fs = nodeInstallTreeFs) {
+    try {
+        if (target.kind === "unknown")
+            return true;
+        if (target.kind === "path") {
+            if (!fs.existsSync(target.path))
+                return false;
+            try {
+                if (fs.statSync(target.path).isDirectory()) {
+                    return fs.existsSync(path.join(target.path, "package.json"));
+                }
+            }
+            catch {
+                return false;
+            }
+            return true;
+        }
+        // package: ancestor walk from `from`.
+        let dir = path.resolve(target.from);
+        for (;;) {
+            const manifest = path.join(dir, "node_modules", target.name, "package.json");
+            if (fs.existsSync(manifest))
+                return true;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return false;
+            dir = parent;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/** The scope/leaf split of CLI_NAME, e.g. `@indigoai-us` / `hq-cli`. */
+function cliNameParts() {
+    const slash = CLI_NAME.indexOf("/");
+    if (slash === -1)
+        return { scope: null, leaf: CLI_NAME };
+    return { scope: CLI_NAME.slice(0, slash), leaf: CLI_NAME.slice(slash + 1) };
+}
+/** Whether a FRESH update lock is held by a DIFFERENT live pid (blocks readiness). */
+function freshForeignLockHeld(lockPath, nowMs, isPidAlive, fs) {
+    let raw;
+    try {
+        raw = fs.readFileSync(lockPath, "utf-8");
+    }
+    catch {
+        return false; // no lock (ENOENT) or unreadable — not a fresh foreign holder
+    }
+    if (isLockStale(raw, nowMs, isPidAlive))
+        return false;
+    try {
+        const info = JSON.parse(raw);
+        if (info.pid === process.pid)
+            return false; // our own lock never blocks us
+    }
+    catch {
+        return false; // isLockStale already treats unparseable as stale, unreachable
+    }
+    return true;
+}
+/** Whether an npm retired/staging sibling (`.<leaf>-*`) sits beside packageRoot. */
+function retiredSiblingPresent(packageRoot, fs) {
+    const { leaf } = cliNameParts();
+    const stagingPrefix = `.${leaf}-`;
+    const parent = path.dirname(packageRoot);
+    const entries = fs.readdirSync(parent); // caller treats a throw as "not ready"
+    return entries.some((entry) => entry.startsWith(stagingPrefix));
+}
+/** Whether packageRoot's own manifest is healthy (`name === CLI_NAME`). */
+function packageRootHealthy(packageRoot, fs) {
+    const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"));
+    return manifest.name === CLI_NAME;
+}
+/**
+ * Poll until the install tree has been continuously READY for `quietMs`, or the
+ * `deadlineMs` passes. READY means: (i) no FRESH update lock held by another pid,
+ * (ii) the missing target is present, and — when `packageRoot` is known —
+ * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and
+ * (iv) no `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem
+ * error makes its condition "not ready" rather than throwing. `deadlineMs === 0`
+ * evaluates readiness exactly once (no waiting); otherwise the whole wait is
+ * bounded, so the caller can never hang.
+ */
+export async function waitForInstallTreeSettled(args) {
+    const now = args.now ?? Date.now;
+    const sleep = args.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const fs = args.fs ?? nodeInstallTreeFs;
+    const isPidAlive = args.isPidAlive ?? defaultIsPidAlive;
+    const pollMs = args.pollMs ?? 250;
+    const quietMs = args.quietMs ?? 1500;
+    const deadlineMs = args.deadlineMs;
+    const start = now();
+    let readySince = null;
+    let sawLock = false;
+    let sawRetired = false;
+    for (;;) {
+        const t = now();
+        const foreignLock = freshForeignLockHeld(args.lockPath, t, isPidAlive, fs);
+        if (foreignLock)
+            sawLock = true;
+        let ready = !foreignLock && installTargetPresent(args.target, fs);
+        if (ready && args.packageRoot) {
+            try {
+                if (!packageRootHealthy(args.packageRoot, fs))
+                    ready = false;
+            }
+            catch {
+                ready = false;
+            }
+            if (ready) {
+                try {
+                    if (retiredSiblingPresent(args.packageRoot, fs)) {
+                        sawRetired = true;
+                        ready = false;
+                    }
+                }
+                catch {
+                    ready = false;
+                }
+            }
+        }
+        if (ready) {
+            if (readySince === null)
+                readySince = t;
+        }
+        else {
+            readySince = null;
+        }
+        const waitedMs = t - start;
+        if (ready && (deadlineMs === 0 || t - readySince >= quietMs)) {
+            return { settled: true, waitedMs, sawLock, sawRetired };
+        }
+        if (waitedMs >= deadlineMs) {
+            return { settled: false, waitedMs, sawLock, sawRetired };
+        }
+        await sleep(pollMs);
+    }
+}
+/** The fixed, input-free carrier message (grouping cardinality stays bounded). */
+const INSTALL_TREE_TORN_MESSAGE = "hq-cli install tree was being rewritten while this command started";
+/**
+ * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived
+ * diagnostics. Fixed `name`/`message` (no argv, path, or free text in either),
+ * `cause` = the original loader error, and a bounded `diagnostics` object whose
+ * only interpolated strings are the hq-derived specifier/importer/packageRoot,
+ * each capped. Mirrors PackageRootResolutionError's construction discipline.
+ */
+export class InstallTreeTornError extends Error {
+    diagnostics;
+    constructor(init) {
+        super(INSTALL_TREE_TORN_MESSAGE);
+        this.name = "InstallTreeTornError";
+        this.cause = init.cause;
+        this.diagnostics = {
+            dialect: init.classified.dialect,
+            code: init.classified.code,
+            specifier: boundedDiagnosticValue(init.classified.specifier, SPECIFIER_BYTES),
+            importer: boundedDiagnosticValue(init.classified.importer, IMPORTER_BYTES),
+            packageRoot: boundedDiagnosticValue(init.packageRoot ?? "", PACKAGE_ROOT_BYTES),
+            outcome: init.outcome,
+            attempt: init.attempt,
+            waitedMs: init.waitedMs,
+            sawLock: init.sawLock,
+            sawRetired: init.sawRetired,
+            node: process.version,
+        };
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export function isInstallTreeTornError(err) {
+    return err instanceof InstallTreeTornError;
+}
+/** The exact Sentry `contexts` payload for a captured torn-install failure. */
+export function installTreeTornCaptureContext(err) {
+    return { contexts: { install_tree_torn: err.diagnostics } };
+}
+/**
+ * The fixed, input-free operator remedy. It names the likely writers (so a
+ * human knows this was not their command's fault) and the reinstall commands,
+ * and interpolates NOTHING — the only per-event value is the bounded specifier
+ * appended by {@link installTreeTornStderrLine}.
+ */
+export const INSTALL_TREE_TORN_REMEDY = "the hq-cli install was being updated by another process (the box's hq-cli-update " +
+    "timer, the desktop app, or another hq command) while this command started. " +
+    "Re-run your command; if it keeps failing, reinstall with " +
+    "`npm i -g @indigoai-us/hq-cli` (or `pnpm add -g @indigoai-us/hq-cli`).";
+/**
+ * The single actionable stderr line for a captured torn-install failure: the
+ * fixed remedy plus the bounded, hq-derived missing specifier — the only
+ * interpolated value, never argv.
+ */
+export function installTreeTornStderrLine(err) {
+    const specifier = err.diagnostics.specifier;
+    return specifier
+        ? `${INSTALL_TREE_TORN_REMEDY} (missing: ${specifier})`
+        : INSTALL_TREE_TORN_REMEDY;
+}
+//# sourceMappingURL=install-tree-torn.js.map

package/dist/utils/sentry-fingerprint.js

@@ -91,6 +91,18 @@ const KNOWN_ERROR_NAMES = new Set([
     // listed defensively so a future capture path cannot mint an unbounded group
     // (HQ-CLI-1A).
     "QmdWorkdirMissingError",
+    // A torn-install failure the bounded settle-wait + single re-exec could not
+    // recover (HQ-CLI-1G/1H/1J/1K). Fingerprinted on its own branch below by the
+    // bounded `diagnostics.outcome`, so the whole family groups into ≤3 issues.
+    "InstallTreeTornError",
+]);
+/**
+ * The CLOSED set of InstallTreeTornError recovery outcomes worth their own
+ * group. Anything else collapses to `outcome:other`, so the axis stays finite;
+ * the carrier's message is fixed, so this outcome IS the only discriminator.
+ */
+const KNOWN_INSTALL_TREE_OUTCOMES = new Set([
+    "guarded", "unsettled", "reexec-failed",
 ]);
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";
@@ -200,6 +212,20 @@ export function sentryFingerprintFor(err) {
             qmdDispositionToken(record.status, record.signal),
         ];
     }
+    // A torn-install failure carries neither an rpcCode nor an HTTP status; its
+    // only bounded discriminator is the recovery `diagnostics.outcome`. Keyed
+    // BEFORE the rpc/status branches so the family groups into ≤3 predictable
+    // issues (guarded / unsettled / reexec-failed) rather than one fungible bucket.
+    if (rawName === "InstallTreeTornError") {
+        const diagnostics = record.diagnostics;
+        const outcome = diagnostics !== null && typeof diagnostics === "object"
+            ? diagnostics.outcome
+            : undefined;
+        const token = typeof outcome === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(outcome)
+            ? `outcome:${outcome}`
+            : "outcome:other";
+        return [DEFAULT_GROUPING, "InstallTreeTornError", token];
+    }
     const name = KNOWN_ERROR_NAMES.has(rawName) ? rawName : FALLBACK_ERROR_NAME;
     const rpcCode = record.rpcCode;
     if (typeof rpcCode === "number" && Number.isInteger(rpcCode)) {

package/package.json

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