@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -29,11 +29,19 @@
  * ../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):
+ * The loader-error `code`s recovery classifies. The first two mean "a module
+ * could not be resolved"; `ENOENT` is the loader/resolver dialect where a module
+ * was present at one step and gone at the next (HQ-CLI-1M esm-load open, HQ-CLI-20
+ * cjs-load open, HQ-CLI-1S resolve-time lstat); `EVAL_THROW` is the synthetic code
+ * for a module-EVALUATION throw that carries NO real `code` (HQ-CLI-1T) — see
+ * {@link ModuleErrorDialect}.
+ */
+type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT" | "EVAL_THROW";
+/**
+ * The closed set of resolution-failure dialects, verified on Node v22.23.1 and
+ * the observed Node 24 synchronous ESM loader shape (the @sentry/node
+ * import-in-the-middle hook does not change the stack transfer):
  *   - `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
@@ -42,16 +50,51 @@ export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND";
  *                    '<abs>'` + `requireStack`.
  *   - `cjs-package`: CJS require of a bare specifier — `Cannot find module
  *                    '<name>'` + `requireStack`.
+ *   - `cjs-relative`: CJS require of a RELATIVE specifier — `Cannot find module
+ *                    './x'` (or `../x`) + `requireStack`. Node reports the RAW
+ *                    relative token, never a resolved path, so it is re-resolved
+ *                    from the importer's directory rather than reduced by
+ *                    packageNameOf (which would yield the un-probeable name `.`).
+ *   - `esm-enoent`:  ESM loader ENOENT (HQ-CLI-1M) — a module present at RESOLVE
+ *                    and gone at READ, so getSourceSync/openSync raises ENOENT
+ *                    (not ERR_MODULE_NOT_FOUND). `err.path` is the vanished file.
+ *   - `cjs-enoent`:  CJS loader ENOENT (HQ-CLI-20) — the CJS twin of esm-enoent: a
+ *                    require() whose target was present at RESOLVE (its filename
+ *                    held in Module._pathCache) and gone at READ, so the CJS
+ *                    loader's source read (defaultLoadImpl/loadSource, or the older
+ *                    Module._extensions..js handler) raises ENOENT with syscall
+ *                    'open' and a cjs/loader frame but NO ESM source-read frame. `err.path`
+ *                    is the vanished file.
+ *   - `resolve-enoent`: ESM/CJS RESOLVE-time ENOENT (HQ-CLI-1S) — a path component
+ *                    stat'ed OK, then vanished before realpathSync's lstat, so the
+ *                    resolver (finalizeResolution / Module._findPath→toRealPath)
+ *                    raises ENOENT with syscall `lstat`. `err.path` is the vanished
+ *                    component (which may be a package/scope directory).
+ *   - `eval-throw`:  a module-EVALUATION throw (HQ-CLI-1T) — a dependency file was
+ *                    found but still half-written, so require() returned an empty
+ *                    module and its top-level code threw a code-LESS TypeError /
+ *                    ReferenceError / SyntaxError under Module._compile /
+ *                    esm/module_job. The specifier is the bounded throw-site path.
  *   - `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";
+type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "cjs-relative" | "esm-enoent" | "cjs-enoent" | "resolve-enoent" | "eval-throw" | "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.
+ *   - `path`:     an absolute filesystem path (a `.js` file, or a package dir).
+ *   - `package`:  a bare package `name` resolvable from directory `from` upward.
+ *   - `relative`: a RELATIVE `specifier` (`./x`, `../x`) re-resolved the way
+ *                 Node's CJS resolver does from directory `from` —
+ *                 `path.resolve(from, specifier)` plus the `.js`/`.json`/`.node`
+ *                 and directory forms.
+ *   - `exists`:   an absolute path whose bare EXISTENCE is the readiness signal
+ *                 (HQ-CLI-1S) — the resolver lstat'ed this component, which may be
+ *                 a package/scope DIRECTORY whose contents precede a `package.json`,
+ *                 so the `path` kind's directory rule could stay false forever.
+ *                 Readiness still rides the lock / manifest-health / retired-sibling
+ *                 / quiet guards, exactly as for the loader-race dialects.
+ *   - `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";
@@ -60,6 +103,13 @@ export type ModuleErrorTarget = {
     kind: "package";
     name: string;
     from: string;
+} | {
+    kind: "relative";
+    specifier: string;
+    from: string;
+} | {
+    kind: "exists";
+    path: string;
 } | {
     kind: "unknown";
 };
@@ -71,7 +121,10 @@ export interface ClassifiedModuleError {
     /** The importer the message named (from-clause or requireStack[0]), or "". */
     importer: string;
     target: ModuleErrorTarget;
+    /** The thrown error's `name` for the eval-throw dialect (HQ-CLI-1T), else absent. */
+    errorName?: string;
 }
+export declare function hasCjsLoaderSourceReadFrame(stack: string): boolean;
 /**
  * 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
@@ -82,17 +135,60 @@ 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.
+ * STRUCTURAL: `err.code` must be exactly `ERR_MODULE_NOT_FOUND`,
+ * `MODULE_NOT_FOUND`, or — for the esm-loader ENOENT dialect — `ENOENT` under
+ * the full conjunction below. 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 structural fingerprint of a module-EVALUATION throw (HQ-CLI-1T). */
+export interface EvalThrowShape {
+    /** The thrown error's `name`, in {@link EVAL_THROW_NAMES}. */
+    errorName: string;
+    /** The absolute throw-site path (first path token in the stack). */
+    throwSite: string;
+}
+/**
+ * Detect a module-EVALUATION throw STRUCTURALLY, WITHOUT the node_modules
+ * boundary gate: an error with NO `code`, a `name` in the closed set
+ * {TypeError, ReferenceError, SyntaxError}, a CJS/ESM module-evaluation loader
+ * frame, and a resolvable throw-site path. This is the shape a half-written
+ * dependency file produces — require() read an empty module and returned `{}`, so
+ * calling one of its exports throws a code-less TypeError while the module's own
+ * top-level code runs. No message text is ever parsed. The caller applies its own
+ * packageRoot gate ({@link classifyEvalThrow} for recovery, the boundary for
+ * capture context), so this stays pure and reusable. Returns null for anything
+ * that is not this shape — a coded error (ERR_REQUIRE_ESM etc.), an Error /
+ * RangeError name, a throw with no loader frame, or no absolute throw site.
+ */
+export declare function evalThrowShape(err: unknown): EvalThrowShape | null;
+/**
+ * Classify a module-EVALUATION throw as a torn-install recovery candidate
+ * (HQ-CLI-1T) — the {@link evalThrowShape} fingerprint AND a throw site under
+ * `<packageRoot>/node_modules/`. A throw under the install's own `dist/` or
+ * `assets/`, outside the root, or with an unresolved root is NOT classified, so a
+ * genuine hq-cli code defect keeps its raw capture. Unlike the loader-race
+ * dialects the recovery seam gates this on a live writer signal before waiting.
+ * `packageRoot` comes from the seam's resolvePackageRoot (running-install → derived
+ * fallback). The target is `unknown` — an eval-throw carries no re-resolvable
+ * missing file, so recovery keys entirely on the writer signal + quiet window.
+ */
+export declare function classifyEvalThrow(err: unknown, packageRoot: string | null): 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;
+        isSymbolicLink?(): boolean;
+        size?: number;
+        mtimeMs?: number;
+    };
+    lstatSync?(p: string): {
+        isDirectory(): boolean;
+        isSymbolicLink?(): boolean;
+        size?: number;
+        mtimeMs?: number;
     };
     readFileSync(p: string, encoding: "utf-8"): string;
     readdirSync(p: string): string[];
@@ -107,6 +203,13 @@ export interface InstallTreeFs {
  *                exact ancestor walk `getPackageJSONURL` performs, done WITHOUT
  *                `createRequire` so an ESM-only / export-conditioned package
  *                cannot false-negative.
+ *   - `relative`: re-resolve `path.resolve(from, specifier)` as Node's CJS
+ *                require would — a real file (exact / `.js` / `.json` / `.node`),
+ *                or a directory whose package.json `main` (or that main's index)
+ *                or own `index.*` is a real file. A bare or partially-extracted
+ *                directory is NOT loadable and reads as not-present.
+ *   - `exists`:  the path exists at all (any file type) — presence only, because
+ *                the vanished component may be a package/scope directory.
  *   - `unknown`: true (readiness turns on the other signals).
  * Any filesystem error reads as "not present" rather than throwing.
  */
@@ -123,7 +226,25 @@ export interface WaitForInstallTreeSettledArgs {
     isPidAlive?: (pid: number) => boolean;
     pollMs?: number;
     quietMs?: number;
+    /** Short observation window for an unchanged, lock-free broken tree. */
+    staleProbeMs?: number;
     deadlineMs: number;
+    /**
+     * Ceiling on the CUMULATIVE time observed under a FRESH foreign lock held by a
+     * live pid. Locked time does NOT consume `deadlineMs` (the budget for the tree
+     * to settle once no cooperating writer is visible); it is bounded separately by
+     * this ceiling so the wait can never hang. Defaults to
+     * {@link DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS}.
+     */
+    lockWaitMs?: number;
+    /**
+     * Invoked exactly once — at the first poll where the total wait has reached
+     * `deadlineMs` while a fresh foreign lock is still held (the moment the
+     * pre-lock-aware wait would have given up). Lets the seam print a one-line
+     * notice that the pause is a live updater, not a hang. Never invoked when no
+     * lock is seen or the lock clears before the deadline.
+     */
+    onLockExtended?: () => void;
 }
 export interface WaitForInstallTreeSettledResult {
     settled: boolean;
@@ -132,20 +253,88 @@ export interface WaitForInstallTreeSettledResult {
     sawLock: boolean;
     /** An npm retired/staging sibling (`.hq-cli-<rand>`) was observed at least once. */
     sawRetired: boolean;
+    /** A fresh foreign lock was held on the FINAL poll of an unsettled wait. */
+    lockHeldAtEnd: boolean;
+    /** Cumulative wall time observed under a fresh foreign lock held by a live pid. */
+    lockedMs: number;
+    /** The bounded `tool` of the last fresh foreign lock seen, or "" if none. */
+    lockTool: string;
+    /** Whether a relevant install-tree path changed during this wait. */
+    sawTreeChange?: boolean;
+    /** True when the lock-free tree stayed unchanged for `staleProbeMs`. */
+    staleTree?: boolean;
+    /** Presence on the final poll; null means the sibling directory was unreadable. */
+    retiredSiblingPresent?: boolean | null;
+    /** A stable partial retired-sibling scan ended the wait without claiming the tree is stale. */
+    retiredSiblingUnverified?: boolean;
+    retiredSiblingKind?: RetiredSiblingKind;
+    installTargetState?: InstallTargetState;
+    updaterPidAlive?: UpdaterPidAlive;
 }
+type RetiredSiblingKind = "npm_hash_retired" | "hq_staging" | "hq_backup" | "other" | "unknown";
+type InstallTargetState = "missing" | "manifest_valid" | "manifest_invalid" | "unreadable" | "unknown";
+type UpdaterPidAlive = "true" | "false" | "unknown";
+type VersionGatePhase = "preflight" | "lock_acquired" | "installer_running" | "verifying" | "rollback" | "complete" | "failed" | "unknown";
 /**
  * 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.
+ * wait exhausts its bounds. 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.
+ *
+ * The wait is LOCK-AWARE and bounded, so a live cooperating writer (the desktop
+ * app, the box's update timer, another `hq`) cannot make a legitimately-in-progress
+ * reinstall look stale:
+ *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
+ *     by `deadlineMs`. If the target is still missing and the observable tree
+ *     signature stays unchanged for `staleProbeMs`, the wait returns `staleTree`
+ *     early. When only a named retired npm sibling's deep scan is incomplete,
+ *     a stable partial signature ends the wait early as `retiredSiblingUnverified`
+ *     instead. That outcome preserves uncertainty and tells the user to wait for
+ *     any installer before attempting a repair. Any observed signature change
+ *     keeps the ordinary settle deadline in force. `deadlineMs === 0` evaluates
+ *     readiness once.
+ *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
+ *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
+ *     10-minute staleness window) and does NOT consume the settle budget. When
+ *     that ceiling is reached with the lock still held, the result is unsettled
+ *     with `lockHeldAtEnd` true so the seam can report a distinct `lock-held`
+ *     outcome and remedy rather than telling the user to reinstall over a live
+ *     writer.
+ * Each poll's REAL elapsed interval (now() deltas) is attributed to the locked or
+ * unlocked bucket by whether a fresh foreign lock was held when the interval
+ * began, so a starved event loop only makes the wait coarser, never unbounded. A
+ * stale lock (dead pid, older than the staleness window, unparseable) or our own
+ * pid never extends anything. The whole wait is bounded (≤ `deadlineMs +
+ * lockWaitMs`), and the unchanged-tree path normally returns after the much
+ * shorter `staleProbeMs` observation window.
  */
 export declare function waitForInstallTreeSettled(args: WaitForInstallTreeSettledArgs): Promise<WaitForInstallTreeSettledResult>;
+export interface InstallRewriteSignalArgs {
+    /** 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;
+    fs?: InstallTreeFs;
+    isPidAlive?: (pid: number) => boolean;
+}
+/**
+ * Whether a global reinstall is PROVABLY rewriting the install tree right now —
+ * the positive writer signal the eval-throw gate requires before it will pay a
+ * settle wait. True iff (i) a fresh foreign update lock is held, (ii) packageRoot's
+ * manifest is absent or name-mismatched (mid-extraction), or (iii) a
+ * `.<leaf>-<hash>` retired sibling sits beside it. Crucially it is POSITIVE: a
+ * benign filesystem error that merely prevents READING the manifest or LISTING the
+ * parent (EACCES/EPERM) is NOT a signal, so a persistent third-party load-time
+ * defect on an otherwise-usable install never pays a spurious 90s wait. Every
+ * dependency is injectable so the recovery seam stays hermetic.
+ */
+export declare function installRewriteInProgress(args: InstallRewriteSignalArgs): boolean;
 /** The recovery OUTCOME, which — not the dialect — decides capture. */
-export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed";
+export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed" | "lock-held" | "stale_tree" | "retired_unverified";
+type InstallTreeState = "in_flight" | "stale";
 export type InstallTreeTornDiagnostics = {
     dialect: ModuleErrorDialect;
     code: ModuleNotFoundCode;
@@ -153,11 +342,27 @@ export type InstallTreeTornDiagnostics = {
     importer: string;
     packageRoot: string;
     outcome: InstallTreeTornOutcome;
+    treeState: InstallTreeState;
     attempt: 1 | 2;
     waitedMs: number;
     sawLock: boolean;
     sawRetired: boolean;
+    sawTreeChange: boolean;
+    /** A fresh foreign lock was still held when the wait gave up (→ 'lock-held'). */
+    lockHeldAtEnd: boolean;
+    /** Cumulative wall time the wait spent under a fresh foreign lock. */
+    lockedMs: number;
+    /** The bounded `tool` of the last fresh foreign lock seen, or "". */
+    lockTool: string;
     node: string;
+    /** Presence on the final poll when the scope directory could be observed. */
+    retiredSiblingPresent?: boolean;
+    /** The thrown error's `name` for the eval-throw dialect (HQ-CLI-1T), else "". */
+    errorName: string;
+    retiredSiblingKind: RetiredSiblingKind;
+    installTargetState: InstallTargetState;
+    versionGatePhase: VersionGatePhase;
+    updaterPidAlive: UpdaterPidAlive;
 };
 export interface InstallTreeTornInit {
     /** The original loader error, carried unchanged as `cause`. */
@@ -169,6 +374,20 @@ export interface InstallTreeTornInit {
     waitedMs: number;
     sawLock: boolean;
     sawRetired: boolean;
+    sawTreeChange?: boolean;
+    treeState?: InstallTreeState;
+    /** Whether a fresh foreign lock was held when the wait gave up (default false). */
+    lockHeldAtEnd?: boolean;
+    /** Cumulative time under a fresh foreign lock (default 0). */
+    lockedMs?: number;
+    /** The last fresh foreign lock's `tool`, bounded on construction (default ""). */
+    lockTool?: string;
+    /** Final retired sibling presence, or null when the scope directory was unreadable. */
+    retiredSiblingPresent?: boolean | null;
+    retiredSiblingKind?: RetiredSiblingKind;
+    installTargetState?: InstallTargetState;
+    versionGatePhase?: VersionGatePhase;
+    updaterPidAlive?: UpdaterPidAlive;
 }
 /**
  * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived
@@ -183,11 +402,13 @@ export declare class InstallTreeTornError extends Error {
 }
 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): {
+export declare function installTreeTornCaptureContext(err: InstallTreeTornError, homeDirectory?: string): {
     contexts: {
         install_tree_torn: InstallTreeTornDiagnostics;
     };
 };
+/** Replace a home-directory prefix without matching similarly-named sibling folders. */
+export declare function scrubHomeDirectoryPrefix(value: string, homeDirectory?: string): string;
 /**
  * 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,
@@ -195,10 +416,25 @@ export declare function installTreeTornCaptureContext(err: InstallTreeTornError)
  * appended by {@link installTreeTornStderrLine}.
  */
 export declare const INSTALL_TREE_TORN_REMEDY: string;
+/** Fixed repair guidance for an unchanged tree with no active updater signal. */
+export declare const INSTALL_TREE_STALE_REMEDY: string;
+/** Guidance when a retired package sibling's activity could not be verified. */
+export declare const INSTALL_TREE_RETIRED_UNVERIFIED_REMEDY: string;
+/**
+ * The fixed, input-free remedy for the 'lock-held' outcome: a cooperating writer
+ * held the shared update lock past its own staleness ceiling. Telling the user to
+ * `npm i -g` here would collide with a live installer mid-rename — the exact race
+ * update-lock.ts exists to prevent — so this remedy tells them to let the running
+ * update finish and NEVER to reinstall over it. Interpolates NOTHING.
+ */
+export declare const INSTALL_TREE_LOCK_HELD_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.
+ * outcome's fixed remedy plus the bounded, hq-derived missing specifier — the only
+ * interpolated value, never argv. A 'lock-held' outcome selects the "let the
+ * update finish" remedy (never the reinstall advice); every other outcome keeps
+ * {@link INSTALL_TREE_TORN_REMEDY} byte-for-byte.
  */
 export declare function installTreeTornStderrLine(err: InstallTreeTornError): string;
+export {};
 //# sourceMappingURL=install-tree-torn.d.ts.map