@indigoai-us/hq-cli 5.162.0 → 5.164.0

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

@@ -30,6 +30,7 @@
  * are only READ (their exported symbols), never modified.
  */
 import * as nodeFs from "node:fs";
+import { homedir } from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { CLI_NAME } from "../cli-version.js";
@@ -637,6 +638,125 @@ function packageRootHealthy(packageRoot, fs) {
     const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"));
     return manifest.name === CLI_NAME;
 }
+function isWithinPath(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" ||
+        (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+/** Paths whose presence, metadata, or immediate entries show activity for this import. */
+function installTreeActivityPaths(target, packageRoot) {
+    const root = packageRoot ? path.resolve(packageRoot) : null;
+    const paths = new Set();
+    const directories = new Set();
+    const addPath = (candidate) => {
+        const resolved = path.resolve(candidate);
+        paths.add(resolved);
+        directories.add(path.dirname(resolved));
+        if (!root || !isWithinPath(resolved, root))
+            return;
+        let current = path.dirname(resolved);
+        for (;;) {
+            paths.add(current);
+            directories.add(current);
+            if (current === root)
+                break;
+            const parent = path.dirname(current);
+            if (parent === current || !isWithinPath(parent, root))
+                break;
+            current = parent;
+        }
+    };
+    if (root) {
+        for (const candidate of [
+            root,
+            path.join(root, "package.json"),
+            path.join(root, "dist"),
+            path.join(root, "node_modules"),
+        ]) {
+            addPath(candidate);
+            directories.add(candidate);
+        }
+    }
+    if (target.kind === "path" || target.kind === "exists") {
+        addPath(target.path);
+    }
+    else if (target.kind === "relative") {
+        const base = path.resolve(target.from, target.specifier);
+        const candidates = [
+            base,
+            ...CJS_FILE_EXTENSIONS.map((ext) => base + ext),
+            ...CJS_FILE_EXTENSIONS.map((ext) => path.join(base, `index${ext}`)),
+        ];
+        for (const candidate of candidates)
+            addPath(candidate);
+    }
+    else if (target.kind === "package") {
+        let from = path.resolve(target.from);
+        let ancestorCount = 0;
+        for (;;) {
+            if (root && !isWithinPath(from, root))
+                break;
+            addPath(path.join(from, "node_modules", target.name));
+            if (from === root)
+                break;
+            ancestorCount += 1;
+            if (!root && ancestorCount >= 12)
+                break;
+            const parent = path.dirname(from);
+            if (parent === from)
+                break;
+            from = parent;
+        }
+    }
+    return {
+        paths: [...paths].sort(),
+        directories: [...directories].sort(),
+    };
+}
+/** A local-only snapshot of the missing target and directories an installer may change. */
+function installTreeActivitySignature(target, packageRoot, fs) {
+    const activity = installTreeActivityPaths(target, packageRoot);
+    const snapshots = [];
+    let observed = true;
+    const errorCode = (err) => {
+        if (err !== null && typeof err === "object" && "code" in err && typeof err.code === "string") {
+            return err.code;
+        }
+        return "error";
+    };
+    for (const candidate of activity.paths) {
+        try {
+            if (!fs.existsSync(candidate)) {
+                snapshots.push([candidate, "missing"]);
+                continue;
+            }
+            const stat = fs.statSync(candidate);
+            snapshots.push([
+                candidate,
+                stat.isDirectory() ? "directory" : "file",
+                stat.size ?? null,
+                stat.mtimeMs ?? null,
+            ]);
+        }
+        catch (err) {
+            observed = false;
+            snapshots.push([candidate, `unreadable:${errorCode(err)}`]);
+        }
+    }
+    for (const directory of activity.directories) {
+        try {
+            if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory())
+                continue;
+            snapshots.push([directory, "entries", fs.readdirSync(directory).sort()]);
+        }
+        catch (err) {
+            observed = false;
+            snapshots.push([directory, `entries-unreadable:${errorCode(err)}`]);
+        }
+    }
+    return { value: JSON.stringify(snapshots), observed };
+}
+export const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
 /**
  * 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
@@ -645,14 +765,14 @@ function packageRootHealthy(packageRoot, fs) {
  * `.<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:
+ * 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`. 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).
+ *     by `deadlineMs`. If the target is still missing, no lock or retired sibling
+ *     is present, and the observed tree stays unchanged for `staleProbeMs`, the
+ *     wait returns `staleTree` early. Any observed tree 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
@@ -665,7 +785,8 @@ function packageRootHealthy(packageRoot, fs) {
  * 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.
+ * lockWaitMs`), and the unchanged-tree path normally returns after the much
+ * shorter `staleProbeMs` observation window.
  */
 export async function waitForInstallTreeSettled(args) {
     const now = args.now ?? Date.now;
@@ -676,7 +797,11 @@ export async function waitForInstallTreeSettled(args) {
     const quietMs = args.quietMs ?? 1500;
     const deadlineMs = args.deadlineMs;
     const lockWaitMs = args.lockWaitMs ?? DEFAULT_INSTALL_SETTLE_LOCK_WAIT_MS;
+    const staleProbeMs = Math.max(0, args.staleProbeMs ?? DEFAULT_INSTALL_TREE_STALE_PROBE_MS);
     const start = now();
+    let lastActivitySnapshot = installTreeActivitySignature(args.target, args.packageRoot, fs);
+    let staleObservationStartedAt = lastActivitySnapshot.observed ? start : null;
+    let sawTreeChange = false;
     let readySince = null;
     let sawLock = false;
     let sawRetired = false;
@@ -700,6 +825,32 @@ export async function waitForInstallTreeSettled(args) {
             sawLock = true;
             lockTool = boundedDiagnosticValue(lock.tool, LOCK_TOOL_BYTES);
         }
+        if (!sawTreeChange) {
+            const activitySnapshot = installTreeActivitySignature(args.target, args.packageRoot, fs);
+            if (!activitySnapshot.observed) {
+                staleObservationStartedAt = null;
+            }
+            else if (!lastActivitySnapshot.observed) {
+                staleObservationStartedAt = t;
+            }
+            else if (activitySnapshot.value !== lastActivitySnapshot.value) {
+                sawTreeChange = true;
+                staleObservationStartedAt = null;
+            }
+            lastActivitySnapshot = activitySnapshot;
+        }
+        let retiredPresent = false;
+        let retiredCheckFailed = false;
+        if (args.packageRoot) {
+            try {
+                retiredPresent = retiredSiblingPresent(args.packageRoot, fs);
+                if (retiredPresent)
+                    sawRetired = true;
+            }
+            catch {
+                retiredCheckFailed = true;
+            }
+        }
         let ready = !foreignLockHeld && installTargetPresent(args.target, fs);
         if (ready && args.packageRoot) {
             try {
@@ -709,17 +860,8 @@ export async function waitForInstallTreeSettled(args) {
             catch {
                 ready = false;
             }
-            if (ready) {
-                try {
-                    if (retiredSiblingPresent(args.packageRoot, fs)) {
-                        sawRetired = true;
-                        ready = false;
-                    }
-                }
-                catch {
-                    ready = false;
-                }
-            }
+            if (ready && (retiredPresent || retiredCheckFailed))
+                ready = false;
         }
         if (ready) {
             if (readySince === null)
@@ -731,7 +873,38 @@ export async function waitForInstallTreeSettled(args) {
         const waitedMs = t - start;
         if (ready && (deadlineMs === 0 || t - readySince >= quietMs)) {
             // Settling requires no foreign lock, so it is never held at the end here.
-            return { settled: true, waitedMs, sawLock, sawRetired, lockHeldAtEnd: false, lockedMs, lockTool };
+            return {
+                settled: true,
+                waitedMs,
+                sawLock,
+                sawRetired,
+                lockHeldAtEnd: false,
+                lockedMs,
+                lockTool,
+                sawTreeChange,
+                staleTree: false,
+            };
+        }
+        if (!ready &&
+            !foreignLockHeld &&
+            !retiredPresent &&
+            !retiredCheckFailed &&
+            !sawLock &&
+            !sawRetired &&
+            !sawTreeChange &&
+            staleObservationStartedAt !== null &&
+            t - staleObservationStartedAt >= staleProbeMs) {
+            return {
+                settled: false,
+                waitedMs,
+                sawLock,
+                sawRetired,
+                lockHeldAtEnd: false,
+                lockedMs,
+                lockTool,
+                sawTreeChange,
+                staleTree: true,
+            };
         }
         // Give up when the TREE has had a full unlocked budget with no writer visible,
         // OR a writer is STILL holding the lock and has held it past its own staleness
@@ -742,7 +915,17 @@ export async function waitForInstallTreeSettled(args) {
         // `deadlineMs` 0 makes the unlocked test fire on the first poll (evaluate-once),
         // matching the pre-lock-aware contract; `lockHeldAtEnd` distinguishes the causes.
         if (unlockedMs >= deadlineMs || (foreignLockHeld && lockedMs >= lockWaitMs)) {
-            return { settled: false, waitedMs, sawLock, sawRetired, lockHeldAtEnd: foreignLockHeld, lockedMs, lockTool };
+            return {
+                settled: false,
+                waitedMs,
+                sawLock,
+                sawRetired,
+                lockHeldAtEnd: foreignLockHeld,
+                lockedMs,
+                lockTool,
+                sawTreeChange,
+                staleTree: false,
+            };
         }
         // The first poll at which the wait has reached `deadlineMs` while a lock is
         // still held is exactly where the pre-lock-aware wait gave up — announce the
@@ -808,7 +991,7 @@ export function installRewriteInProgress(args) {
     }
 }
 /** 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";
+const INSTALL_TREE_TORN_MESSAGE = "hq-cli could not load a module from its install tree and automatic recovery did not complete";
 /**
  * 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),
@@ -822,6 +1005,8 @@ export class InstallTreeTornError extends Error {
         super(INSTALL_TREE_TORN_MESSAGE);
         this.name = "InstallTreeTornError";
         this.cause = init.cause;
+        const sawTreeChange = init.sawTreeChange ?? false;
+        const treeState = init.treeState ?? (init.outcome === "stale_tree" ? "stale" : "in_flight");
         this.diagnostics = {
             dialect: init.classified.dialect,
             code: init.classified.code,
@@ -829,10 +1014,12 @@ export class InstallTreeTornError extends Error {
             importer: boundedDiagnosticValue(init.classified.importer, IMPORTER_BYTES),
             packageRoot: boundedDiagnosticValue(init.packageRoot ?? "", PACKAGE_ROOT_BYTES),
             outcome: init.outcome,
+            treeState,
             attempt: init.attempt,
             waitedMs: init.waitedMs,
             sawLock: init.sawLock,
             sawRetired: init.sawRetired,
+            sawTreeChange,
             lockHeldAtEnd: init.lockHeldAtEnd ?? false,
             lockedMs: init.lockedMs ?? 0,
             lockTool: boundedDiagnosticValue(init.lockTool ?? "", LOCK_TOOL_BYTES),
@@ -846,8 +1033,45 @@ 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 } };
+export function installTreeTornCaptureContext(err, homeDirectory = homedir()) {
+    const diagnostics = err.diagnostics;
+    return {
+        contexts: {
+            install_tree_torn: {
+                ...diagnostics,
+                specifier: scrubHomeDirectoryPrefix(diagnostics.specifier, homeDirectory),
+                importer: scrubHomeDirectoryPrefix(diagnostics.importer, homeDirectory),
+                packageRoot: scrubHomeDirectoryPrefix(diagnostics.packageRoot, homeDirectory),
+            },
+        },
+    };
+}
+function looksLikeWindowsPath(value) {
+    return /^[a-zA-Z]:[\\/]/.test(value) || /^\\\\/.test(value);
+}
+/** Replace a home-directory prefix without matching similarly-named sibling folders. */
+export function scrubHomeDirectoryPrefix(value, homeDirectory = homedir()) {
+    if (!value || !homeDirectory)
+        return value;
+    if (looksLikeWindowsPath(value) || looksLikeWindowsPath(homeDirectory)) {
+        const home = path.win32.normalize(homeDirectory).replace(/[\\/]+$/, "");
+        const normalized = path.win32.normalize(value);
+        const foldedHome = home.toLowerCase();
+        const foldedValue = normalized.toLowerCase();
+        if (foldedValue === foldedHome)
+            return "~";
+        const prefix = `${foldedHome}\\`;
+        if (foldedValue.startsWith(prefix))
+            return `~\\${normalized.slice(home.length + 1)}`;
+        return value;
+    }
+    const home = path.posix.normalize(homeDirectory).replace(/\/+$/, "");
+    const normalized = path.posix.normalize(value);
+    if (normalized === home)
+        return "~";
+    if (normalized.startsWith(`${home}/`))
+        return `~/${normalized.slice(home.length + 1)}`;
+    return value;
 }
 /**
  * The fixed, input-free operator remedy. It names the likely writers (so a
@@ -855,10 +1079,15 @@ export function installTreeTornCaptureContext(err) {
  * 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`).";
+export const INSTALL_TREE_TORN_REMEDY = "hq-cli could not finish automatic install-tree recovery. Re-run your command; " +
+    "if it still fails, reinstall with `npm install -g @indigoai-us/hq-cli@latest` " +
+    "(or `pnpm add -g @indigoai-us/hq-cli@latest` / `bun add -g @indigoai-us/hq-cli@latest` " +
+    "when that manager owns your install).";
+/** Fixed repair guidance for an unchanged tree with no active updater signal. */
+export const INSTALL_TREE_STALE_REMEDY = "hq-cli's install tree is incomplete and no active updater was detected. " +
+    "Reinstall with `npm install -g @indigoai-us/hq-cli@latest` " +
+    "(or `pnpm add -g @indigoai-us/hq-cli@latest` / `bun add -g @indigoai-us/hq-cli@latest` " +
+    "when that manager owns your install), then run the command again.";
 /**
  * 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
@@ -877,7 +1106,11 @@ export const INSTALL_TREE_LOCK_HELD_REMEDY = "another hq updater (the desktop ap
  * {@link INSTALL_TREE_TORN_REMEDY} byte-for-byte.
  */
 export function installTreeTornStderrLine(err) {
-    const remedy = err.diagnostics.outcome === "lock-held" ? INSTALL_TREE_LOCK_HELD_REMEDY : INSTALL_TREE_TORN_REMEDY;
+    const remedy = err.diagnostics.outcome === "lock-held"
+        ? INSTALL_TREE_LOCK_HELD_REMEDY
+        : err.diagnostics.outcome === "stale_tree"
+            ? INSTALL_TREE_STALE_REMEDY
+            : INSTALL_TREE_TORN_REMEDY;
     const specifier = err.diagnostics.specifier;
     return specifier ? `${remedy} (missing: ${specifier})` : remedy;
 }

package/dist/utils/plan-gate-error.d.ts

@@ -1,30 +1,44 @@
-export type PlanGateCode = "PLAN_LIMIT_EXCEEDED" | "PLAN_REQUIRED"
-/**
- * US-054: a PERSONAL scope asked for a feature the paid Individual plan
- * includes and the free tier does not. A different plan, a different price
- * and a different remedy from the company codes above, so it is its own
- * code rather than a reuse of `PLAN_REQUIRED` with company copy.
- */
- | "PERSONAL_PLAN_REQUIRED";
+export type PlanGateCode = "PLAN_LIMIT_EXCEEDED" | "PLAN_REQUIRED" | "MEETING_PLAN_REQUIRED"
+/** A PERSONAL scope asked for a feature the paid Individual plan includes. */
+ | "PERSONAL_PLAN_REQUIRED"
+/** External agent enrollment was denied by the company plan. */
+ | "BILLING_REQUIRED";
 export interface PlanGateDetails {
     resource?: string;
-    /** The refused feature, on a `PERSONAL_PLAN_REQUIRED` denial. */
     feature?: string;
     used?: number;
     limit?: number;
     upgradeUrl?: string;
-    /** Best-effort target captured by the shared HTTP client for interactive checkout. */
+    reason?: string;
+    /** Company target from request context or the server's UID-keyed billing URL. */
     companyUid?: string;
 }
+/** One renderer for server-selected upgrade links across CLI plan refusals. */
+export declare function formatUpgradeRefusal(reason: string, upgradeUrl: string | undefined, options?: {
+    urlOnly?: boolean;
+}): string;
+/** Recover a company UID only from the server's UID-keyed billing callback. */
+export declare function companyUidFromPlanUpgradeUrl(value: unknown): string | undefined;
 export declare class PlanGateError extends Error {
     readonly code: PlanGateCode;
     readonly details: PlanGateDetails;
     constructor(code: PlanGateCode, details: PlanGateDetails);
 }
 export declare function isPlanGateError(err: unknown): err is PlanGateError;
-export declare function formatPlanGateError(err: PlanGateError): string;
+/** Plain, stable CLI copy for plan-gated resource creation. */
+export declare function formatPlanGateError(err: PlanGateError, options?: {
+    urlOnly?: boolean;
+}): string;
 export declare function canOfferTeamUpgrade(argv?: readonly string[]): boolean;
-/** Ask once, only on a real interactive terminal. */
+export interface UpgradeLinkOfferDependencies {
+    ask?: (question: string) => Promise<string>;
+    openUrl?: (url: string) => Promise<void>;
+    argv?: readonly string[];
+    interactive?: boolean;
+}
+/** Ask before opening the exact URL returned by the server. */
+export declare function offerUpgradeLink(url: string, deps?: UpgradeLinkOfferDependencies): Promise<boolean>;
+/** Legacy checkout callback retained for callers outside the shared refusal paths. */
 export declare function offerTeamUpgrade(onConfirm: () => Promise<void>, deps?: {
     ask?: (question: string) => Promise<string>;
     argv?: readonly string[];
@@ -33,7 +47,7 @@ export declare function offerTeamUpgrade(onConfirm: () => Promise<void>, deps?:
 /** Decode an already-read JSON envelope from either shared HTTP client. */
 export declare function planGateErrorFromPayload(status: number, body: unknown, companyUid?: string): PlanGateError | null;
 /**
- * Decode only the two deliberate plan-gate envelopes. Malformed, unrelated,
+ * Decode the supported plan-gate envelopes. Malformed, unrelated,
  * or non-402 responses retain their existing command-specific handling.
  */
 export declare function planGateErrorFromResponse(response: Response, companyUid?: string): Promise<{