@indigoai-us/hq-cli 5.304.0 → 5.306.0

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

@@ -700,7 +700,7 @@ function retiredSiblingActivitySignature(packageRoot, fs) {
     for (const sibling of siblings) {
         visit(path.join(parent, sibling), sibling, 0);
     }
-    return { value: JSON.stringify(snapshots), observed };
+    return { value: JSON.stringify(snapshots), observed, present: siblings.length > 0 };
 }
 /** Whether packageRoot's own manifest is healthy (`name === CLI_NAME`). */
 function packageRootHealthy(packageRoot, fs) {
@@ -787,6 +787,8 @@ function installTreeActivitySignature(target, packageRoot, fs) {
     const activity = installTreeActivityPaths(target, packageRoot);
     const snapshots = [];
     let observed = true;
+    let nonRetiredObserved = true;
+    let retiredSiblingPresent = null;
     const errorCode = (err) => {
         if (err !== null && typeof err === "object" && "code" in err && typeof err.code === "string") {
             return err.code;
@@ -809,6 +811,7 @@ function installTreeActivitySignature(target, packageRoot, fs) {
         }
         catch (err) {
             observed = false;
+            nonRetiredObserved = false;
             snapshots.push([candidate, `unreadable:${errorCode(err)}`]);
         }
     }
@@ -820,6 +823,7 @@ function installTreeActivitySignature(target, packageRoot, fs) {
         }
         catch (err) {
             observed = false;
+            nonRetiredObserved = false;
             snapshots.push([directory, `entries-unreadable:${errorCode(err)}`]);
         }
     }
@@ -827,6 +831,7 @@ function installTreeActivitySignature(target, packageRoot, fs) {
         try {
             const retired = retiredSiblingActivitySignature(packageRoot, fs);
             snapshots.push(["retired-siblings", retired.value]);
+            retiredSiblingPresent = retired.present;
             if (!retired.observed)
                 observed = false;
         }
@@ -835,7 +840,16 @@ function installTreeActivitySignature(target, packageRoot, fs) {
             snapshots.push(["retired-siblings-unreadable", errorCode(err)]);
         }
     }
-    return { value: JSON.stringify(snapshots), observed };
+    return { value: JSON.stringify(snapshots), observed, nonRetiredObserved, retiredSiblingPresent };
+}
+function canProbeUnsettledRetiredSibling(snapshot) {
+    // A very large or unreadable retired npm tree can exceed the bounded recursive
+    // activity scan. Its stable partial signature is still useful when the live
+    // install paths are observable and npm's named retired sibling is present.
+    // This only selects the existing stale-tree repair outcome; it never removes
+    // files, and any observed signature change still suppresses stale classification.
+    return snapshot.observed ||
+        (snapshot.nonRetiredObserved && snapshot.retiredSiblingPresent === true);
 }
 export const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
 /**
@@ -850,11 +864,14 @@ export const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
  * 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 observed tree,
- *     including retired sibling names and mtimes, 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.
+ *     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
@@ -882,7 +899,7 @@ export async function waitForInstallTreeSettled(args) {
     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 staleObservationStartedAt = canProbeUnsettledRetiredSibling(lastActivitySnapshot) ? start : null;
     let sawTreeChange = false;
     let readySince = null;
     let sawLock = false;
@@ -909,16 +926,18 @@ export async function waitForInstallTreeSettled(args) {
         }
         if (!sawTreeChange) {
             const activitySnapshot = installTreeActivitySignature(args.target, args.packageRoot, fs);
-            if (!activitySnapshot.observed) {
+            const previousCanProbe = canProbeUnsettledRetiredSibling(lastActivitySnapshot);
+            const currentCanProbe = canProbeUnsettledRetiredSibling(activitySnapshot);
+            if (previousCanProbe && currentCanProbe && activitySnapshot.value !== lastActivitySnapshot.value) {
+                sawTreeChange = true;
                 staleObservationStartedAt = null;
             }
-            else if (!lastActivitySnapshot.observed) {
-                staleObservationStartedAt = t;
-            }
-            else if (activitySnapshot.value !== lastActivitySnapshot.value) {
-                sawTreeChange = true;
+            else if (!currentCanProbe) {
                 staleObservationStartedAt = null;
             }
+            else if (!previousCanProbe) {
+                staleObservationStartedAt = t;
+            }
             lastActivitySnapshot = activitySnapshot;
         }
         let retiredPresent = null;
@@ -985,8 +1004,9 @@ export async function waitForInstallTreeSettled(args) {
                 lockedMs,
                 lockTool,
                 sawTreeChange,
-                staleTree: true,
+                staleTree: lastActivitySnapshot.observed,
                 retiredSiblingPresent: retiredPresent,
+                retiredSiblingUnverified: !lastActivitySnapshot.observed && lastActivitySnapshot.retiredSiblingPresent === true,
             };
         }
         // Give up when the TREE has had a full unlocked budget with no writer visible,
@@ -1176,6 +1196,10 @@ export const INSTALL_TREE_STALE_REMEDY = "hq-cli's install tree is incomplete an
     "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.";
+/** Guidance when a retired package sibling's activity could not be verified. */
+export const INSTALL_TREE_RETIRED_UNVERIFIED_REMEDY = "hq-cli found a retired install sibling but could not verify whether an installer is still using it. Wait for any npm or desktop CLI update to finish, then run the command again. If no install is running, repair 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).";
 /**
  * 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
@@ -1198,7 +1222,9 @@ export function installTreeTornStderrLine(err) {
         ? INSTALL_TREE_LOCK_HELD_REMEDY
         : err.diagnostics.outcome === "stale_tree"
             ? INSTALL_TREE_STALE_REMEDY
-            : INSTALL_TREE_TORN_REMEDY;
+            : err.diagnostics.outcome === "retired_unverified"
+                ? INSTALL_TREE_RETIRED_UNVERIFIED_REMEDY
+                : INSTALL_TREE_TORN_REMEDY;
     const specifier = err.diagnostics.specifier;
     return specifier ? `${remedy} (missing: ${specifier})` : remedy;
 }

package/dist/utils/self-update.d.ts

@@ -137,6 +137,10 @@ export interface SelfUpdateDeps {
     currentVersion?: string;
     fetchLatest?: () => Promise<string | null>;
     resolveInstall?: () => RunningInstall;
+    /** Permission preflight for an npm global prefix (tests inject a read-only result). */
+    canWriteNpmInstall?: (install: RunningInstall) => boolean;
+    /** Home directory used for the durable per-install permission notice marker. */
+    homeDir?: string;
     /** Same-filesystem install rename, injectable for rollback tests. */
     renamePath?: typeof fs.renameSync;
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;

package/dist/utils/self-update.js

@@ -65,7 +65,7 @@ import chalk from "chalk";
 import { Sentry } from "../sentry.js";
 import { isCliTelemetryDisabled } from "./cli-telemetry.js";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, isPrefixWritable, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, canWriteNpmInstall, captureNonWritableNpmPrefixNotice, claimNonWritableNpmPrefixNotice, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, } from "./version-gate.js";
 import { canStageInstall, stagedNpmInstall } from "./staged-install.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
@@ -659,10 +659,30 @@ async function updateAndReexec(argv, flavor, known, deps) {
         console.error(chalk.dim(`hq-cli ${latest} is available, but this copy is a local dependency (${install.packageRoot}) — update the project that owns it.`));
         return { action: "skipped", latest };
     }
-    const staged = canStageInstall(install) && (await readStagedSelfUpdateFlag(deps, env));
     const releaseLock = flavor.lock ? (deps.acquireLock ?? acquireUpdateLock)() : () => { };
     if (!releaseLock)
         return { action: "skipped", latest };
+    if (install.manager === "npm" &&
+        install.prefix &&
+        install.packageRoot &&
+        !(deps.canWriteNpmInstall ?? ((resolved) => canWriteNpmInstall(resolved.prefix, resolved.packageRoot)))(install)) {
+        const claimed = flavor.noun === "daemon update"
+            ? false
+            : claimNonWritableNpmPrefixNotice(install, current, deps.homeDir);
+        if (flavor.noun === "rescue" || claimed) {
+            console.error(chalk.yellow(`  ${nonWritablePrefixNote(install.prefix)}`));
+        }
+        await captureNonWritableNpmPrefixNotice({
+            fromVersion: current,
+            targetVersion: latestValid,
+            install,
+            env,
+            homeDir: deps.homeDir,
+        });
+        releaseLock();
+        return { action: "update-failed", latest };
+    }
+    const staged = canStageInstall(install) && (await readStagedSelfUpdateFlag(deps, env));
     const renamePath = deps.renamePath ?? fs.renameSync;
     // The in-place update moves the package aside, and the installer's
     // supervisor ships inside it, so run the installer through a copy.
@@ -732,12 +752,27 @@ async function updateAndReexec(argv, flavor, known, deps) {
         console.error(chalk.yellow(`⚠ hq-cli ${latest} is available but the update failed` +
             `${result.detail ? `: ${result.detail}` : ""}`));
         console.error(chalk.dim(`  Try manually: ${plan.cmd} ${plan.args.join(" ")}`));
-        // A root-owned npm prefix the running user cannot write is the agent-box
-        // case (the CLI is a /usr global install and the runtime is unprivileged),
-        // and the startup path has no sudo fallback — say so plainly so a failed
-        // update on a box reads as the permission wall it is, not a transient error.
-        if (install.manager === "npm" && install.prefix && !isPrefixWritable(install.prefix)) {
-            console.error(chalk.yellow(`  ${nonWritablePrefixNote(install.prefix)}`));
+        // A permission wall discovered after npm fails is handled as an expected
+        // install-state warning. The preflight normally catches it before spawn;
+        // this check covers ACL changes and other races after the preflight.
+        const npmPrefixNotWritable = install.manager === "npm" &&
+            install.prefix &&
+            install.packageRoot &&
+            !(deps.canWriteNpmInstall ?? ((resolved) => canWriteNpmInstall(resolved.prefix, resolved.packageRoot)))(install);
+        if (npmPrefixNotWritable) {
+            const prefixNoticeClaimed = flavor.noun === "daemon update"
+                ? false
+                : claimNonWritableNpmPrefixNotice(install, current, deps.homeDir);
+            if (flavor.noun === "rescue" || prefixNoticeClaimed) {
+                console.error(chalk.yellow(`  ${nonWritablePrefixNote(install.prefix)}`));
+            }
+            await captureNonWritableNpmPrefixNotice({
+                fromVersion: current,
+                targetVersion: latestValid,
+                install,
+                env,
+                homeDir: deps.homeDir,
+            });
         }
         // A manager-level failure often means the install layout itself is broken
         // (e.g. a hand-rolled pnpm store nested inside the app's bin dir). The
@@ -748,7 +783,9 @@ async function updateAndReexec(argv, flavor, known, deps) {
             console.error(chalk.dim(`  Or repair the install: hq rescue`));
         }
         console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
-        await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result, env, flavor.noun === "rescue");
+        if (!npmPrefixNotWritable) {
+            await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result, env, flavor.noun === "rescue");
+        }
         return { action: "update-failed", latest };
     }
     if (installSnapshot)

package/dist/utils/sentry-fingerprint.js

@@ -189,6 +189,7 @@ const KNOWN_INSTALL_TREE_OUTCOMES = new Set([
     "reexec-failed",
     "lock-held",
     "stale_tree",
+    "retired_unverified",
 ]);
 function installTreeRecoveryOutcomeTag(value) {
     return typeof value === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(value)

package/dist/utils/version-check.d.ts

@@ -1,3 +1,4 @@
+export declare const CLI_VERSION_NUDGE_FLAG = "cli.version-update-nudge";
 declare function isKnownNoninteractiveStatusProbe(argv?: readonly string[]): boolean;
 /**
  * The cached npm `latest` when it is newer than the running version, else null.
@@ -21,6 +22,12 @@ export interface RefreshVersionCacheOptions {
     timeoutMs?: number;
 }
 export declare function refreshVersionCache(options?: RefreshVersionCacheOptions): Promise<void>;
+/** Write the optional update guidance from the existing npm version cache.
+ * This helper never performs a network request; a missing or stale cache means
+ * there is no nudge to show.
+ */
+export declare function printCachedVersionNudge(stderr?: Pick<NodeJS.WriteStream, "write">): Promise<void>;
+export declare function printVersionAndNudge(stdout?: Pick<NodeJS.WriteStream, "write">, stderr?: Pick<NodeJS.WriteStream, "write">): Promise<void>;
 export declare const __test__: {
     CACHE_TTL_MS: number;
     isKnownNoninteractiveStatusProbe: typeof isKnownNoninteractiveStatusProbe;

package/dist/utils/version-check.js

@@ -9,6 +9,7 @@ const CACHE_TTL_MS = 60 * 60 * 1000; // 1h — catch fresh releases within the h
 const CACHE_TTL_JITTER_MS = 5 * 60 * 1000; // up to 5m early, to spread a fleet's refreshes off a single instant
 const FETCH_TIMEOUT_MS = 3_000;
 const REFRESH_LOCK_STALE_MS = 10 * 60 * 1000;
+export const CLI_VERSION_NUDGE_FLAG = "cli.version-update-nudge";
 /**
  * How long to stop auto-retrying an `ineffectiveLatest` target. Long enough to
  * break the per-invocation loop on a busy agent box, short enough that a box
@@ -67,7 +68,7 @@ function isKnownNoninteractiveStatusProbe(argv = process.argv) {
     const json = args.includes("--json") || !process.stdout.isTTY;
     if (!json)
         return false;
-    if (positional[0] === "mcp" && positional[1] === "status")
+    if (positional[0] === "mcp" && (positional[1] === "status" || positional[1] === "list"))
         return true;
     if (positional[0] === "packs" && (positional[1] === "list" || positional[1] === "ls"))
         return true;
@@ -199,6 +200,34 @@ export async function refreshVersionCache(options = {}) {
         releaseLock();
     }
 }
+/** Write the optional update guidance from the existing npm version cache.
+ * This helper never performs a network request; a missing or stale cache means
+ * there is no nudge to show.
+ */
+export async function printCachedVersionNudge(stderr = process.stderr) {
+    if (isOptedOut())
+        return;
+    let resolveProcessFlagGate;
+    try {
+        ({ resolveProcessFlagGate } = await import("../lib/flag-registry.js"));
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown";
+        stderr.write(`hq: Update nudge unavailable (${errorClass}).\n`);
+        return;
+    }
+    const enabled = resolveProcessFlagGate(CLI_VERSION_NUDGE_FLAG, { fallback: false }, () => false);
+    if (!enabled)
+        return;
+    const latest = staleAgainstCachedLatest();
+    if (latest) {
+        stderr.write(`Update available: ${latest}. Update with npm install -g @indigoai-us/hq-cli@latest, pnpm add -g @indigoai-us/hq-cli@latest, or bun add -g @indigoai-us/hq-cli@latest.\n`);
+    }
+}
+export async function printVersionAndNudge(stdout = process.stdout, stderr = process.stderr) {
+    stdout.write(`${CLI_VERSION}\n`);
+    await printCachedVersionNudge(stderr);
+}
 export const __test__ = {
     CACHE_TTL_MS,
     isKnownNoninteractiveStatusProbe,

package/dist/utils/version-gate.d.ts

@@ -151,9 +151,9 @@ export declare function resolveRunningManager(): InstallManager;
 /** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
 export declare function resolveRunningPrefix(): string | null;
 /**
- * Whether the current process can write the npm global `prefix` — i.e. whether
- * an `npm install -g --prefix <prefix>` could actually replace the installed
- * CLI, or would fail with EACCES.
+ * Whether the current process can write the npm global install targets — i.e.
+ * whether an `npm install -g --prefix <prefix>` could actually replace the
+ * installed CLI, or would fail with EACCES.
  *
  * The path npm rewrites is the prefix's `bin` dir (`<prefix>/bin/hq` on unix
  * globals — the `rename /usr/bin/hq` EACCES the agent boxes hit), so that is
@@ -167,13 +167,27 @@ export declare function resolveRunningPrefix(): string | null;
  */
 export declare function isPrefixWritable(prefix: string, access?: (target: string, mode: number) => void): boolean;
 /**
- * One-line operator explanation for a failed global update whose prefix the
- * running user cannot write. This is the agent-box case: the CLI is a
- * root-owned `/usr` global install and the runtime is unprivileged, so the
- * update genuinely cannot converge from here and re-trying it silently would
- * loop. Says so plainly and points at the paths that CAN update it.
+ * Check the directories an npm global update must mutate before spawning npm.
+ * Npm replaces the package under node_modules and writes executable links
+ * under prefix/bin. The package's parent must be writable because npm renames
+ * the old package there.
+ *
+ * When one of those directories has not been created yet, check its nearest
+ * existing ancestor: npm can create a child only if that ancestor is writable.
  */
-export declare function nonWritablePrefixNote(prefix: string): string;
+export declare function canWriteNpmInstall(prefix: string, packageRoot: string, access?: (target: string, mode: number) => void): boolean;
+/** Claim the one local warning/report for this installed version and prefix. */
+export declare function claimNonWritableNpmPrefixNotice(install: Pick<RunningInstall, "manager" | "prefix" | "packageRoot">, fromVersion: string, homeDir?: string, kind?: "user" | "report"): boolean;
+/** Emit one path-free warning event for a handled non-writable npm prefix. */
+export declare function captureNonWritableNpmPrefixNotice(input: {
+    fromVersion: string;
+    targetVersion: string;
+    install: Pick<RunningInstall, "manager" | "prefix" | "packageRoot">;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+}): Promise<void>;
+/** One-line repair guidance for a global npm install the current user cannot write. */
+export declare function nonWritablePrefixNote(prefix: string, platform?: NodeJS.Platform): string;
 /**
  * Derive `PNPM_HOME` from a pnpm-managed install's own path. pnpm resolves its
  * global bin directory from `PNPM_HOME` (or an explicit `global-bin-dir`), and
@@ -411,6 +425,8 @@ export declare function checkUpdateConvergence(targetVersion: string, deps?: {
 interface EnforceUpdateDeps {
     performUpdateString?: (command: string) => UpdateResult;
     resolveInstall?: () => RunningInstall;
+    canWriteNpmInstall?: (install: RunningInstall) => boolean;
+    homeDir?: string;
     runner?: UpdateRunner;
     platform?: NodeJS.Platform;
     cleanStale?: (prefix: string) => string[];
@@ -442,7 +458,7 @@ interface EnforceUpdateDeps {
  * A timed-out updater is the exception: it has been forcibly reaped, so the
  * gate returns and lets the user's command run on the current version.
  */
-declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): void;
+declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): void | Promise<void>;
 /**
  * Public entry point. Call before commander parses argv. Blocks the CLI on
  * network IO for up to FETCH_TIMEOUT_MS — acceptable because the alternative
@@ -484,6 +500,8 @@ export declare const __test__: {
     buildPnpmInstallArgv: typeof buildPnpmInstallArgv;
     buildPrefixedInstallArgv: typeof buildPrefixedInstallArgv;
     buildSpawnPlan: typeof buildSpawnPlan;
+    canWriteNpmInstall: typeof canWriteNpmInstall;
+    claimNonWritableNpmPrefixNotice: typeof claimNonWritableNpmPrefixNotice;
     cleanStalePartialInstall: typeof cleanStalePartialInstall;
     derivePnpmHome: typeof derivePnpmHome;
     enforceUpdateRequired: typeof enforceUpdateRequired;