@indigoai-us/hq-cli 5.109.10 → 5.109.12

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

@@ -31,10 +31,12 @@
  */
 /**
  * The loader-error `code`s recovery classifies. The first two mean "a module
- * could not be resolved"; `ENOENT` is the esm-loader dialect where a module was
- * present at resolve and gone at read (HQ-CLI-1M) — see {@link ModuleErrorDialect}.
+ * 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-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}.
  */
-export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT";
+export 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 (the
  * @sentry/node import-in-the-middle hook does not change the shapes):
@@ -54,10 +56,20 @@ export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "
  *   - `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.
+ *   - `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" | "cjs-relative" | "esm-enoent" | "unknown";
+export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "cjs-relative" | "esm-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).
@@ -66,6 +78,12 @@ export type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-
  *                 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.
  */
@@ -80,6 +98,9 @@ export type ModuleErrorTarget = {
     kind: "relative";
     specifier: string;
     from: string;
+} | {
+    kind: "exists";
+    path: string;
 } | {
     kind: "unknown";
 };
@@ -91,6 +112,8 @@ 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;
 }
 /**
  * Reduce a bare specifier to its PACKAGE name: `@scope/name/sub` → `@scope/name`,
@@ -109,6 +132,39 @@ export declare function packageNameOf(specifier: string): string;
  * `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;
@@ -133,10 +189,21 @@ export interface InstallTreeFs {
  *                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.
  */
 export declare function installTargetPresent(target: ModuleErrorTarget, fs?: InstallTreeFs): boolean;
+/**
+ * Default ceiling on the CUMULATIVE time the wait may spend observing a FRESH
+ * foreign lock held by a live pid. Equal to the shared update-lock contract's own
+ * staleness window ({@link UPDATE_LOCK_STALE_MS} — "no healthy npm install -g of
+ * this package runs 10 minutes"), so the wait trusts a live cooperating writer for
+ * exactly as long as the contract legitimises holding the lock, and never longer.
+ * Overridable by the seam (env HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS).
+ */
+export declare const DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS: number;
 export interface WaitForInstallTreeSettledArgs {
     target: ModuleErrorTarget;
     /** The running install's package dir (from resolveRunningInstall), or null. */
@@ -150,6 +217,22 @@ export interface WaitForInstallTreeSettledArgs {
     pollMs?: number;
     quietMs?: 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;
@@ -158,20 +241,67 @@ 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;
 }
 /**
  * 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 on TWO independent axes, so a live
+ * cooperating writer (the desktop app, the box's update timer, another `hq`)
+ * cannot make a legitimately-in-progress reinstall look like a torn install:
+ *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
+ *     by `deadlineMs`. That is the budget for the TREE to settle once no writer is
+ *     visible; with no lock ever seen, unlocked time equals total wait time and
+ *     the behaviour is byte-for-byte the pre-lock-aware one (unsettled at exactly
+ *     `deadlineMs`, and `deadlineMs === 0` evaluates readiness exactly 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`), so the caller can never hang.
  */
 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";
 export type InstallTreeTornDiagnostics = {
     dialect: ModuleErrorDialect;
     code: ModuleNotFoundCode;
@@ -183,7 +313,15 @@ export type InstallTreeTornDiagnostics = {
     waitedMs: number;
     sawLock: boolean;
     sawRetired: 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;
+    /** The thrown error's `name` for the eval-throw dialect (HQ-CLI-1T), else "". */
+    errorName: string;
 };
 export interface InstallTreeTornInit {
     /** The original loader error, carried unchanged as `cause`. */
@@ -195,6 +333,12 @@ export interface InstallTreeTornInit {
     waitedMs: number;
     sawLock: boolean;
     sawRetired: boolean;
+    /** 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;
 }
 /**
  * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived
@@ -221,10 +365,20 @@ export declare function installTreeTornCaptureContext(err: InstallTreeTornError)
  * appended by {@link installTreeTornStderrLine}.
  */
 export declare const INSTALL_TREE_TORN_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;
 //# sourceMappingURL=install-tree-torn.d.ts.map