@indigoai-us/hq-cli 5.303.0 → 5.305.0

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/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;

package/dist/utils/version-gate.js

@@ -28,14 +28,17 @@
  * to silence both check + gate).
  */
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
-import { accessSync, closeSync, constants as fsConstants, copyFileSync, existsSync, mkdtempSync, openSync, readdirSync, realpathSync, readFileSync, rmSync, } from "node:fs";
+import { accessSync, closeSync, constants as fsConstants, copyFileSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, realpathSync, readFileSync, rmSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import semver from "semver";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
+import { Sentry } from "../sentry.js";
+import { isCliTelemetryDisabled } from "./cli-telemetry.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
 import { acquireUpdateLock, } from "./update-lock.js";
 const CLIENT_ID = "hq-cli";
@@ -385,9 +388,9 @@ export function resolveRunningPrefix() {
     return resolveRunningInstall().prefix;
 }
 /**
- * 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
@@ -416,17 +419,119 @@ export function isPrefixWritable(prefix, access = (target, mode) => accessSync(t
     return false;
 }
 /**
- * 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 function nonWritablePrefixNote(prefix) {
-    return (`The npm global prefix ${prefix} is not writable by the current user, so this update cannot ` +
-        `take effect here. On an agent box this is expected: the CLI is a root-owned global install and ` +
-        `updates land as root — via the box's hq-cli-update timer, or \`sudo npm install -g ${CLI_NAME}@latest\` — ` +
-        `not from the unprivileged runtime.`);
+export function canWriteNpmInstall(prefix, packageRoot, access = (target, mode) => accessSync(target, mode)) {
+    let nodeModulesRoot = path.join(prefix, process.platform === "win32" ? "node_modules" : "lib/node_modules");
+    let cursor = path.resolve(packageRoot);
+    while (true) {
+        if (path.basename(cursor).toLowerCase() === "node_modules") {
+            nodeModulesRoot = cursor;
+            break;
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    const mode = fsConstants.W_OK | fsConstants.X_OK;
+    // npm needs write access to the directories it replaces or links into. The
+    // prefix root itself need not be writable when those directories already
+    // exist; when one is missing, the nearest-existing-ancestor check below
+    // still verifies permission to create it.
+    const targets = [path.join(prefix, "bin"), nodeModulesRoot, path.dirname(packageRoot)];
+    return targets.every((target) => {
+        let candidate = path.resolve(target);
+        while (true) {
+            try {
+                access(candidate, mode);
+                return true;
+            }
+            catch (error) {
+                if (error?.code !== "ENOENT") {
+                    return false;
+                }
+                const parent = path.dirname(candidate);
+                if (parent === candidate)
+                    return false;
+                candidate = parent;
+            }
+        }
+    });
+}
+const nonWritablePrefixNotices = new Set();
+/** Claim the one local warning/report for this installed version and prefix. */
+export function claimNonWritableNpmPrefixNotice(install, fromVersion, homeDir = os.homedir(), kind = "user") {
+    const installIdentity = path.resolve(install.packageRoot ?? install.prefix ?? `${install.manager}:unknown-install`);
+    const identity = createHash("sha256")
+        .update(`${installIdentity}\0${fromVersion}`)
+        .digest("hex");
+    const localKey = path.join(homeDir, ".hq", "self-update", "prefix-not-writable", `${kind}-${identity}`);
+    if (nonWritablePrefixNotices.has(localKey))
+        return false;
+    try {
+        mkdirSync(path.dirname(localKey), { recursive: true, mode: 0o700 });
+        const descriptor = openSync(localKey, "wx", 0o600);
+        closeSync(descriptor);
+        nonWritablePrefixNotices.add(localKey);
+        return true;
+    }
+    catch (error) {
+        if (error?.code === "EEXIST") {
+            nonWritablePrefixNotices.add(localKey);
+            return false;
+        }
+        // Preserve the warning/report for this process if the home directory is
+        // unavailable. The marker is normally durable across CLI invocations.
+        console.error(chalk.dim("hq: could not persist the self-update permission notice rate limit."));
+        nonWritablePrefixNotices.add(localKey);
+        return true;
+    }
+}
+/** Emit one path-free warning event for a handled non-writable npm prefix. */
+export function captureNonWritableNpmPrefixNotice(input) {
+    if (isCliTelemetryDisabled(input.env ?? process.env))
+        return Promise.resolve();
+    const claimed = claimNonWritableNpmPrefixNotice(input.install, input.fromVersion, input.homeDir, "report");
+    if (!claimed)
+        return Promise.resolve();
+    Sentry.captureMessage("Self-update deferred: npm prefix is not writable", {
+        level: "warning",
+        fingerprint: ["self-update", "npm-prefix-not-writable"],
+        tags: {
+            from_version: input.fromVersion,
+            target_version: input.targetVersion,
+            install_flavor: "npm",
+            error_class: "prefix_not_writable",
+            error_reason: "permission_denied",
+        },
+    });
+    return Sentry.flush(2_000).then((flushed) => {
+        if (!flushed) {
+            console.error(chalk.dim("hq: the self-update permission notice could not be sent to Sentry yet."));
+        }
+    });
+}
+/** One-line repair guidance for a global npm install the current user cannot write. */
+export function nonWritablePrefixNote(prefix, platform = process.platform) {
+    const prefixArg = `'${prefix.replace(/'/g, "'\\''")}'`;
+    if (platform === "win32") {
+        const windowsPrefixArg = `"${prefix.replace(/"/g, '""')}"`;
+        return (`The npm global prefix ${prefix} is not writable by the current user, so hq-cli was not updated. ` +
+            `Open PowerShell as Administrator and run \`npm install -g --prefix ${windowsPrefixArg} ${CLI_NAME}@latest\`, ` +
+            `or set a user-owned prefix with \`npm config set prefix "$env:APPDATA\\npm"\` and run ` +
+            `\`npm install -g ${CLI_NAME}@latest\` from that PowerShell session.`);
+    }
+    return (`The npm global prefix ${prefix} is not writable by the current user, so hq-cli was not updated. ` +
+        `Run \`sudo npm install -g --prefix ${prefixArg} ${CLI_NAME}@latest\` to update this install, ` +
+        `or switch to a user-owned prefix with \`npm config set prefix ~/.npm-global\`, then run ` +
+        `\`npm install -g ${CLI_NAME}@latest\` after adding ~/.npm-global/bin to PATH.`);
 }
 /**
  * Derive `PNPM_HOME` from a pnpm-managed install's own path. pnpm resolves its
@@ -1236,19 +1341,29 @@ function enforceUpdateRequired(decision, deps = {}) {
         console.error(chalk.dim("  Another hq updater is already installing (update lock held); continuing on the current version."));
         return;
     }
-    let exitCode;
+    let attempt;
     try {
-        exitCode = attemptRequiredUpdate(decision, deps, install);
+        attempt = attemptRequiredUpdate(decision, deps, install);
     }
-    finally {
-        // `process.exit` skips `finally` blocks, so the exit itself lives OUTSIDE
-        // the lock scope; this `finally` releases on the normal path and on any
-        // unexpected throw from the install attempt.
+    catch (error) {
         lock.release();
+        throw error;
     }
-    if (exitCode === "continue")
+    if (attempt instanceof Promise) {
+        return attempt.then((exitCode) => {
+            lock.release();
+            if (exitCode !== "continue")
+                process.exit(exitCode);
+        }, (error) => {
+            lock.release();
+            throw error;
+        });
+    }
+    // `process.exit` skips `finally`, so release explicitly before exiting.
+    lock.release();
+    if (attempt === "continue")
         return;
-    process.exit(exitCode);
+    process.exit(attempt);
 }
 /**
  * The install attempt itself (npm/pnpm/bun routing, stale-partial cleanup,
@@ -1290,6 +1405,7 @@ function attemptRequiredUpdate(decision, deps, install) {
     // npm/bun and when PNPM_HOME is already set.
     const updateEnv = pnpmUpdateEnv(install);
     let result;
+    let noticeFlush = null;
     if (isManagedOutsideNpm) {
         console.error(chalk.dim(`  Detected a ${install.manager}-managed global install; updating with ${install.manager}`));
         console.error(chalk.dim(`  Running: ${primaryCmd} ${primaryArgs.join(" ")}`));
@@ -1360,12 +1476,22 @@ function attemptRequiredUpdate(decision, deps, install) {
     }
     if (!result.ok) {
         console.error(chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`));
-        // A root-owned global prefix the running user cannot write is the agent-box
-        // case: even the `sudo -n` retry above cannot help without passwordless
-        // sudo, so name the wall plainly rather than leaving `exit 75` to read as a
-        // generic failure. Only for npm-prefix installs (pnpm/Bun route elsewhere).
-        if (!isManagedOutsideNpm && prefix && !isPrefixWritable(prefix)) {
+        // If the npm prefix is still unwritable after the unprivileged and sudo
+        // attempts, explain the permission wall plainly instead of leaving exit 75
+        // as a generic failure. Only applies to npm-managed installs.
+        const npmPrefixNotWritable = !isManagedOutsideNpm &&
+            prefix &&
+            install.packageRoot &&
+            !(deps.canWriteNpmInstall ?? ((resolved) => canWriteNpmInstall(resolved.prefix, resolved.packageRoot)))(install);
+        if (npmPrefixNotWritable) {
             console.error(chalk.yellow(`  ${nonWritablePrefixNote(prefix)}`));
+            noticeFlush = captureNonWritableNpmPrefixNotice({
+                fromVersion: CLI_VERSION,
+                targetVersion: decision.latestVersion,
+                install,
+                env: process.env,
+                homeDir: deps.homeDir,
+            });
         }
         // The package manager itself is missing from this environment — the usual
         // cause is a minimal-PATH parent (launchd, cron, a bare systemd unit) that
@@ -1391,7 +1517,7 @@ function attemptRequiredUpdate(decision, deps, install) {
             console.error(chalk.dim("  Continuing on the current hq-cli version."));
             return "continue";
         }
-        return 75;
+        return noticeFlush ? noticeFlush.then(() => 75) : 75;
     }
     // Read-your-writes: a "successful" install into the npm prefix does not
     // prove the user's PATH resolves it. Verify BEFORE announcing, so a ghost
@@ -1427,7 +1553,9 @@ export async function enforceVersionGate(onUpdateRecommended, options = {}) {
             : undefined;
         // Exits the process, EXCEPT when another updater holds the shared update
         // lock — then it returns and the CLI continues on the current version.
-        enforceUpdateRequired(decision, { resolveInstall: () => install, installNpmPackageStaged });
+        const requiredUpdate = enforceUpdateRequired(decision, { resolveInstall: () => install, installNpmPackageStaged });
+        if (requiredUpdate)
+            await requiredUpdate;
         return "continue";
     }
     if (decision.updateRecommended) {
@@ -1468,6 +1596,8 @@ export const __test__ = {
     buildPnpmInstallArgv,
     buildPrefixedInstallArgv,
     buildSpawnPlan,
+    canWriteNpmInstall,
+    claimNonWritableNpmPrefixNotice,
     cleanStalePartialInstall,
     derivePnpmHome,
     enforceUpdateRequired,

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

@@ -13,6 +13,7 @@ export interface VersionReportDeps {
     hqRoot?: string;
     readHq?: (hqRoot: string) => string | null;
     fetchLatest?: () => Promise<string | null>;
+    printUpdateNudge?: (stderr: Pick<NodeJS.WriteStream, "write">) => Promise<void>;
 }
 export declare function normalizeHqCoreTag(tag: string): string | null;
 export declare function fetchLatestHqCoreRelease(fetchImpl?: typeof fetch, timeoutMs?: number): Promise<string | null>;
@@ -22,5 +23,5 @@ export declare function versionReportJson(report: VersionReport): string;
 export { isVersionRequest, wantsJson } from "../version-request.js";
 export declare function runVersionCommand(argv?: readonly string[], deps?: VersionReportDeps, stdout?: {
     write(chunk: string): unknown;
-}): Promise<void>;
+}, stderr?: Pick<NodeJS.WriteStream, "write">): Promise<void>;
 //# sourceMappingURL=version-report.d.ts.map

package/dist/utils/version-report.js

@@ -91,8 +91,15 @@ export function versionReportJson(report) {
     }, null, 2)}\n`;
 }
 export { isVersionRequest, wantsJson } from "../version-request.js";
-export async function runVersionCommand(argv = process.argv, deps = {}, stdout = process.stdout) {
+export async function runVersionCommand(argv = process.argv, deps = {}, stdout = process.stdout, stderr = process.stderr) {
     const report = await collectVersionReport(deps);
     stdout.write(wantsJson(argv) ? versionReportJson(report) : formatVersionReport(report));
+    if (!wantsJson(argv)) {
+        const printUpdateNudge = deps.printUpdateNudge ?? (async (target) => {
+            const { printCachedVersionNudge } = await import("./version-check.js");
+            await printCachedVersionNudge(target);
+        });
+        await printUpdateNudge(stderr);
+    }
 }
 //# sourceMappingURL=version-report.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.303.0",
+  "version": "5.305.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/dist/lib/work-context/index.d.ts

@@ -1,26 +0,0 @@
-/**
- * Work Context reconciliation package (consumable by hq-cli).
- * Contract (US-001) + reconcile / outbox / device default (US-007A)
- * + organize / project resolution (US-007B)
- * + cross-company correct / migrate (US-017B).
- */
-export * from "./contract.js";
-export * from "./errors.js";
-export * from "./paths.js";
-export * from "./atomic.js";
-export * from "./config.js";
-export * from "./state.js";
-export * from "./outbox.js";
-export * from "./company.js";
-export { companyBindingChanged, isNonCloudCompanySlug, presenceLeaveFromState, reboundSessionProjection, } from "./company-rebind.js";
-export * from "./project.js";
-export { decisionFromCandidates, digestOrganizePayload, formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, stableDecisionId, stableOrganizeOperationId, submitOrganizeDecision, } from "./organize.js";
-export type { CandidatesResponse, FetchCandidatesFn, OrganizeCandidate, OrganizeListResult, OrganizeReceipt, OrganizeSubmitDecision, OrganizeSubmitResult, PostOrganizeFn, } from "./organize.js";
-export { digestMigratePayload, formatMigrateConfirmation, stableMigrateOperationId, submitSessionMigration, } from "./migrate.js";
-export type { MigrateDestination, MigrateReceipt, MigrateSubmitResult, PostMigrateFn, } from "./migrate.js";
-export { deriveRemoteOwnerSlug, deriveRepoIdentityKey, findWorkTreeRoot, matchCompanySlugForRepo, normalizeRemoteOwnerName, } from "./repo-remote.js";
-export { matchMembershipAnswer, promptRepoCompany, } from "./repo-prompt.js";
-export type { RepoPromptCompany, RepoPromptDeps, RepoPromptOutcome, RepoPromptSkipReason, } from "./repo-prompt.js";
-export { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "./reconcile.js";
-export type { ReconcileDeps, ReconcileObservation, ReconcileOutcome, } from "./reconcile.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/lib/work-context/index.js

@@ -1,22 +0,0 @@
-/**
- * Work Context reconciliation package (consumable by hq-cli).
- * Contract (US-001) + reconcile / outbox / device default (US-007A)
- * + organize / project resolution (US-007B)
- * + cross-company correct / migrate (US-017B).
- */
-export * from "./contract.js";
-export * from "./errors.js";
-export * from "./paths.js";
-export * from "./atomic.js";
-export * from "./config.js";
-export * from "./state.js";
-export * from "./outbox.js";
-export * from "./company.js";
-export { companyBindingChanged, isNonCloudCompanySlug, presenceLeaveFromState, reboundSessionProjection, } from "./company-rebind.js";
-export * from "./project.js";
-export { decisionFromCandidates, digestOrganizePayload, formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, stableDecisionId, stableOrganizeOperationId, submitOrganizeDecision, } from "./organize.js";
-export { digestMigratePayload, formatMigrateConfirmation, stableMigrateOperationId, submitSessionMigration, } from "./migrate.js";
-export { deriveRemoteOwnerSlug, deriveRepoIdentityKey, findWorkTreeRoot, matchCompanySlugForRepo, normalizeRemoteOwnerName, } from "./repo-remote.js";
-export { matchMembershipAnswer, promptRepoCompany, } from "./repo-prompt.js";
-export { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "./reconcile.js";
-//# sourceMappingURL=index.js.map