@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

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

@@ -29,19 +29,11 @@
  * ../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 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):
+ * 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
@@ -50,51 +42,16 @@ type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT"
  *                    '<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.
  */
-type ModuleErrorDialect = "esm-path" | "esm-package" | "cjs-path" | "cjs-package" | "cjs-relative" | "esm-enoent" | "cjs-enoent" | "resolve-enoent" | "eval-throw" | "unknown";
+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.
- *   - `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.
+ *   - `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";
@@ -103,13 +60,6 @@ export type ModuleErrorTarget = {
     kind: "package";
     name: string;
     from: string;
-} | {
-    kind: "relative";
-    specifier: string;
-    from: string;
-} | {
-    kind: "exists";
-    path: string;
 } | {
     kind: "unknown";
 };
@@ -121,10 +71,7 @@ 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
@@ -135,60 +82,17 @@ 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`,
- * `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.
+ * 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 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[];
@@ -203,13 +107,6 @@ 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.
  */
@@ -226,25 +123,7 @@ 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;
@@ -253,88 +132,20 @@ 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
- * 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.
+ * `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>;
-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" | "lock-held" | "stale_tree" | "retired_unverified";
-type InstallTreeState = "in_flight" | "stale";
+export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed";
 export type InstallTreeTornDiagnostics = {
     dialect: ModuleErrorDialect;
     code: ModuleNotFoundCode;
@@ -342,27 +153,11 @@ 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`. */
@@ -374,20 +169,6 @@ 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
@@ -402,13 +183,11 @@ 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, homeDirectory?: string): {
+export declare function installTreeTornCaptureContext(err: InstallTreeTornError): {
     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,
@@ -416,25 +195,10 @@ export declare function scrubHomeDirectoryPrefix(value: string, homeDirectory?:
  * 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
- * 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.
+ * fixed remedy plus the bounded, hq-derived missing specifier — the only
+ * interpolated value, never argv.
  */
 export declare function installTreeTornStderrLine(err: InstallTreeTornError): string;
-export {};
 //# sourceMappingURL=install-tree-torn.d.ts.map