@indigoai-us/hq-cli 5.94.3 → 5.96.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [5.96.0]
+
+### Changed
+
+- The CLI now updates itself instead of nagging. When a newer version is
+  available, an ordinary command quietly installs it and re-runs on the new
+  version rather than printing "a new version is available" on every
+  invocation; the warning now appears only if the update itself fails, along
+  with the exact command to run by hand. hq-pro's soft "update recommended"
+  signal is handled the same way. Updates are serialized across concurrent
+  `hq` processes with a lock so a busy multi-agent box can't race
+  `npm install -g` into a broken partial install, and the package manager's
+  output is captured so it never corrupts a `--json` command's stdout. (#344)
+
+### Fixed
+
+- `hq rescue` now brings the CLI itself up to the latest version (and re-runs
+  the rescue on it) before touching the HQ core. The rescue logic ships inside
+  the CLI, so an out-of-date CLI was running an out-of-date rescue. Skipped for
+  `--check` dry-runs and behind a new `--no-self-update` flag; best-effort, so
+  any update failure falls back to rescuing on the current version. (#344)
+
+All self-update behavior honors the existing `HQ_NO_UPDATE_CHECK=1` opt-out.
+
 ## [5.94.3]
 
 ### Fixed

package/dist/commands/index-cmd.d.ts

@@ -9,7 +9,7 @@ export type SearchIndexDependencies = {
     resolveQmdVersion: () => string | undefined;
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
     runBackgroundLauncher?: (dependencies: BackgroundDependencies) => BackgroundResult;
-    runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult;
+    runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult | Promise<BackgroundResult>;
     backgroundStatus?: (dependencies: BackgroundDependencies) => BackgroundStatus;
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */

package/dist/commands/index-cmd.js

@@ -73,13 +73,13 @@ export function registerIndexCommand(program, dependencies = defaults) {
         .option('--log <path>', 'Write worker output to this log file')
         .addOption(new Option('--worker').hideHelp())
         .option('--hq-root <path>', 'HQ root to index (defaults to auto-detected root)')
-        .action((options) => {
+        .action(async (options) => {
         const hqRoot = resolveRoot(options.hqRoot);
         const background = makeBackgroundDependencies(hqRoot, dependencies);
         if (options.log)
             background.env = { ...background.env, QMD_REINDEX_LOG: options.log };
         const result = options.worker
-            ? (dependencies.runBackgroundWorker ?? runBackgroundWorker)(background)
+            ? await (dependencies.runBackgroundWorker ?? runBackgroundWorker)(background)
             : (dependencies.runBackgroundLauncher ?? runBackgroundLauncher)(background);
         if (!options.worker && result.state === 'launched')
             console.log(result.pid);

package/dist/commands/rescue.d.ts

@@ -12,6 +12,12 @@
  * installed version (read from core/core.yaml). Staging (`--staging`): targets
  * `indigoai-us/hq-core-staging@main` and lets the script read its on-disk
  * sync stamp for the floor.
+ *
+ * Before touching the HQ root, rescue also self-updates hq-cli itself to npm
+ * latest and re-execs (`selfUpdateAndReexec`) so the bundled rescue script is
+ * current too — see utils/self-update.ts. Skipped for `--check` (a dry-run
+ * must not mutate the global install), `--no-self-update`, and
+ * `HQ_NO_UPDATE_CHECK=1`; always best-effort.
  */
 import { Command } from 'commander';
 export interface RescueTarget {
@@ -29,5 +35,15 @@ export declare function resolveRescueTarget(opts: {
     source?: string;
     ref?: string;
 }, latestTag?: string): RescueTarget;
+/**
+ * Whether this invocation should try the CLI self-update. Pure + exported for
+ * tests. A dry-run (`--check`) must not mutate the global install, and
+ * commander maps `--no-self-update` to `selfUpdate: false`. Env-based opt-outs
+ * (HQ_NO_UPDATE_CHECK, the re-exec guard) live inside selfUpdateAndReexec.
+ */
+export declare function shouldAttemptSelfUpdate(opts: {
+    check?: boolean;
+    selfUpdate?: boolean;
+}): boolean;
 export declare function registerRescueCommand(program: Command): void;
 //# sourceMappingURL=rescue.d.ts.map

package/dist/commands/rescue.js

@@ -5,6 +5,7 @@ import * as yaml from 'js-yaml';
 import chalk from 'chalk';
 import { rescue } from '@indigoai-us/hq-cloud';
 import { findHqRoot } from '../utils/manifest.js';
+import { selfUpdateAndReexec } from '../utils/self-update.js';
 const PROD_SOURCE = 'indigoai-us/hq-core';
 const STAGING_SOURCE = 'indigoai-us/hq-core-staging';
 /**
@@ -18,6 +19,15 @@ export function resolveRescueTarget(opts, latestTag) {
     }
     return { source: opts.source ?? PROD_SOURCE, ref: opts.ref ?? latestTag };
 }
+/**
+ * Whether this invocation should try the CLI self-update. Pure + exported for
+ * tests. A dry-run (`--check`) must not mutate the global install, and
+ * commander maps `--no-self-update` to `selfUpdate: false`. Env-based opt-outs
+ * (HQ_NO_UPDATE_CHECK, the re-exec guard) live inside selfUpdateAndReexec.
+ */
+export function shouldAttemptSelfUpdate(opts) {
+    return opts.selfUpdate !== false && !opts.check;
+}
 /** Resolve a GitHub token: prefer `gh auth token`, fall back to env. */
 function resolveGhToken() {
     try {
@@ -105,9 +115,20 @@ export function registerRescueCommand(program) {
         .option('--check', 'Plan only — classify and report, change nothing on disk (--dry-run)')
         .option('-y, --yes', 'Skip the confirmation prompt')
         .option('--no-backup', 'Skip the pre-op safety snapshot under ~/.hq/backups')
+        .option('--no-self-update', 'Skip updating hq-cli itself to the latest version first')
         .option('--cloud-update', 'Cloud-update mode')
         .action(async (opts) => {
         try {
+            // Bring the CLI itself to latest first: the rescue script is bundled
+            // with this install, so an outdated CLI would run an outdated rescue.
+            // On a successful update the rescue re-runs on the new version and we
+            // exit with its status; on any failure we continue on this version.
+            if (shouldAttemptSelfUpdate(opts)) {
+                const outcome = await selfUpdateAndReexec(process.argv);
+                if (outcome.action === 'reexec') {
+                    process.exit(outcome.reexecStatus ?? 0);
+                }
+            }
             const hqRoot = opts.hqRoot ?? findHqRoot();
             const token = resolveGhToken();
             let { source, ref } = resolveRescueTarget(opts);

package/dist/lib/search-index/background.d.ts

@@ -1,6 +1,6 @@
 import { type QmdProcessResult, type RunQmdOptions } from './index.js';
 export type BackgroundResult = {
-    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed';
+    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed' | 'terminated';
 } | {
     state: 'launched';
     pid: number;
@@ -20,6 +20,9 @@ export type BackgroundDependencies = {
     }) => number;
     /** Test seam for simulating a competing owner replacing the atomic record. */
     afterOwnerPublish?: (ownerFile: string) => void;
+    /** Test seams for signal delivery; production uses the real process. */
+    processEvents?: Pick<NodeJS.Process, 'once'>;
+    exit?: (code: number) => void;
 };
 export type BackgroundStatus = {
     lock: 'held' | 'stale' | 'free';
@@ -33,7 +36,7 @@ export declare function installWorkerCleanup(cleanup: () => void, processEvents?
 /** Start a detached worker; this public entry never owns the qmd pipeline. */
 export declare function runBackgroundLauncher(dependencies: BackgroundDependencies): BackgroundResult;
 /** Run the single-flight cleanup → update → embed pipeline in a worker only. */
-export declare function runBackgroundWorker(dependencies: BackgroundDependencies): BackgroundResult;
+export declare function runBackgroundWorker(dependencies: BackgroundDependencies): Promise<BackgroundResult>;
 /** Report the background lock and latest successful completion for `hq index status`. */
 export declare function backgroundStatus(dependencies: BackgroundDependencies): BackgroundStatus;
 //# sourceMappingURL=background.d.ts.map

package/dist/lib/search-index/background.js

@@ -170,6 +170,10 @@ function acquireClaim(home, observedGeneration, dependencies) {
         const claimant = path.join(claim, `c.${dependencies.pid}.${dependencies.random()}`);
         try {
             fs.mkdirSync(claimant);
+            // Test-only deterministic failure inject (unset in production) — shell
+            // parity with the script's claimant write_owner_record injection.
+            if (dependencies.env.QMD_FORCE_CLAIMANT_WRITE_FAIL)
+                throw new Error('forced claimant write failure');
             fs.writeFileSync(path.join(claimant, 'owner'), `pid=${dependencies.pid}\nts=${dependencies.now()}\n`);
             return { claim, claimant };
         }
@@ -236,6 +240,10 @@ function createAndPublishLock(home, dependencies) {
     const ownerFile = path.join(directory, 'owner');
     const temporary = path.join(directory, `.owner.tmp.${dependencies.pid}.${dependencies.random()}`);
     try {
+        // Test-only deterministic failure inject (unset in production) — shell
+        // parity: the script's write_owner_record honored the same variable.
+        if (dependencies.env.QMD_FORCE_OWNER_WRITE_FAIL)
+            throw new Error('forced owner write failure');
         fs.writeFileSync(temporary, `pid=${dependencies.pid}\nts=${dependencies.now()}\nnonce=${nonce}\n`);
         fs.renameSync(temporary, ownerFile);
         dependencies.afterOwnerPublish?.(ownerFile);
@@ -290,11 +298,52 @@ function releaseLock(home, dependencies) {
 export function installWorkerCleanup(cleanup, processEvents = process, exit = () => undefined) {
     processEvents.once('exit', cleanup);
     // Unlike Bash, Node cannot turn a SIGKILL or an already-defaulted signal into
-    // catchable cleanup. SIGINT/SIGTERM are registered here and the CLI's normal
-    // process exit then runs the same idempotent owner release. Exiting prevents
-    // a synchronous pipeline from continuing after it has released ownership.
+    // catchable cleanup. SIGINT/SIGTERM/SIGHUP are registered here (the shell
+    // worker trapped `INT TERM HUP`; a detached worker's controlling terminal
+    // going away delivers HUP, and the default disposition would kill the
+    // process without releasing the lock) and the CLI's normal process exit then
+    // runs the same idempotent owner release. Exiting prevents a synchronous
+    // pipeline from continuing after it has released ownership.
     processEvents.once('SIGINT', () => { cleanup(); exit(0); });
     processEvents.once('SIGTERM', () => { cleanup(); exit(0); });
+    processEvents.once('SIGHUP', () => { cleanup(); exit(0); });
+}
+function workerLogPath(env) {
+    return env.QMD_REINDEX_LOG
+        ?? env.QMD_HANDOFF_LOG
+        ?? path.join(env.HANDOFF_LOG_DIR ?? '/tmp', 'qmd-handoff.log');
+}
+function appendWorkerLog(logPath, text) {
+    if (!text)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        fs.appendFileSync(logPath, text.endsWith('\n') ? text : `${text}\n`);
+    }
+    catch { /* logging is best-effort, exactly like the shell worker's >>"$LOG" */ }
+}
+/** Keep only the trailing QMD_HANDOFF_LOG_MAX_BYTES of the worker log (shell cap_log parity). */
+function capWorkerLog(logPath, env) {
+    const raw = env.QMD_HANDOFF_LOG_MAX_BYTES ?? '65536';
+    if (!/^\d+$/.test(raw))
+        return;
+    const max = Number(raw);
+    if (max === 0)
+        return;
+    try {
+        if (!fs.existsSync(logPath) || fs.statSync(logPath).size <= max)
+            return;
+        const content = fs.readFileSync(logPath);
+        fs.writeFileSync(logPath, content.subarray(content.length - max));
+    }
+    catch { /* best-effort, matching the shell's cap_log */ }
+}
+function stepOutput(result) {
+    return `${result.stdout ?? ''}${result.stderr ?? ''}`;
+}
+function errorOutput(error) {
+    const e = error;
+    return `${e.stdout ?? ''}${e.stderr ?? ''}` || (e.message ?? '');
 }
 /** Start a detached worker; this public entry never owns the qmd pipeline. */
 export function runBackgroundLauncher(dependencies) {
@@ -309,13 +358,10 @@ export function runBackgroundLauncher(dependencies) {
     catch {
         return { state: 'skipped' };
     }
-    const logPath = dependencies.env.QMD_REINDEX_LOG
-        ?? dependencies.env.QMD_HANDOFF_LOG
-        ?? path.join(dependencies.env.HANDOFF_LOG_DIR ?? '/tmp', 'qmd-handoff.log');
-    return { state: 'launched', pid: dependencies.spawnWorker({ logPath }) };
+    return { state: 'launched', pid: dependencies.spawnWorker({ logPath: workerLogPath(dependencies.env) }) };
 }
 /** Run the single-flight cleanup → update → embed pipeline in a worker only. */
-export function runBackgroundWorker(dependencies) {
+export async function runBackgroundWorker(dependencies) {
     if (isHostedAgent(dependencies.env))
         return { state: 'skipped-agent' };
     const home = dependencies.env.HOME;
@@ -329,14 +375,32 @@ export function runBackgroundWorker(dependencies) {
     }
     if (isRecentCompletion(home, dependencies) || !acquireLock(home, dependencies))
         return { state: 'busy' };
+    // Shell-worker log parity: each step's captured output appends to the
+    // handoff log and the log keeps only its trailing QMD_HANDOFF_LOG_MAX_BYTES.
+    // The cap lives inside the exit cleanup because a signal-path process.exit
+    // never unwinds to a `finally` — the shell capped in its EXIT trap for the
+    // same reason.
+    const logPath = workerLogPath(dependencies.env);
     let released = false;
     const cleanup = () => {
         if (released)
             return;
         released = true;
         releaseLock(home, dependencies);
+        capWorkerLog(logPath, dependencies.env);
+    };
+    installWorkerCleanup(cleanup, dependencies.processEvents ?? process, dependencies.exit ?? ((code) => process.exit(code)));
+    // A signal that lands during a synchronous qmd step cannot interrupt it, and
+    // Node defers the handler until the event loop next turns — which a fully
+    // synchronous pipeline never lets happen, so SIGTERM used to be processed
+    // only AFTER update/embed had already run. Bash traps fire between commands;
+    // yielding one event-loop turn between steps restores that contract. If the
+    // handler ran (production exits; tests inject `exit`), `released` is set and
+    // the pipeline stops before its next step.
+    const signalWindow = async () => {
+        await new Promise((resolve) => setImmediate(resolve));
+        return released;
     };
-    installWorkerCleanup(cleanup, process, (code) => process.exit(code));
     try {
         if (isRecentCompletion(home, dependencies))
             return { state: 'busy' };
@@ -349,21 +413,36 @@ export function runBackgroundWorker(dependencies) {
             // The shell worker has no collection-registration step. Keep this #306
             // integration best-effort so it cannot suppress a later index update.
         }
+        if (await signalWindow())
+            return { state: 'terminated' };
         try {
-            dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot });
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot })));
         }
-        catch { /* cleanup is intentionally best-effort */ }
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error)); // cleanup is intentionally best-effort
+        }
+        if (await signalWindow())
+            return { state: 'terminated' };
         try {
-            dependencies.runQmd(['update'], { cwd: dependencies.hqRoot });
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['update'], { cwd: dependencies.hqRoot })));
         }
-        catch {
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error));
+            appendWorkerLog(logPath, `[qmd-reindex-bg] update-failed ts=${dependencies.now()}`);
             return { state: 'update-failed' };
         }
+        if (await signalWindow())
+            return { state: 'terminated' };
         try {
-            dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot });
+            appendWorkerLog(logPath, stepOutput(dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot })));
+        }
+        catch (error) {
+            appendWorkerLog(logPath, errorOutput(error)); // a completed embed attempt still permits the stamp
         }
-        catch { /* a completed embed attempt still permits the completion stamp */ }
+        if (await signalWindow())
+            return { state: 'terminated' };
         writeCompletion(home, dependencies);
+        appendWorkerLog(logPath, `[qmd-reindex-bg] done ts=${dependencies.now()}`);
         return { state: 'completed' };
     }
     finally {

package/dist/main.js

@@ -67,8 +67,9 @@ import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import { isAuthError } from "./utils/auth-error.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
-import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check.js";
+import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
+import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
@@ -91,7 +92,6 @@ const onPipeError = (err) => {
 process.stdout.on("error", onPipeError);
 process.stderr.on("error", onPipeError);
 initSentry();
-maybeWarnNewVersion();
 const program = new Command();
 program
     .name("hq")
@@ -239,19 +239,46 @@ program.hook("preAction", async () => {
     await emitCliSessionStarted();
 });
 export async function runCli() {
+    // Set when a self-update re-exec'd this command on a newer CLI: the child
+    // already did the work, so this process only has to carry its exit status
+    // out (after the finally block's telemetry, hence not process.exit here).
+    let reexecStatus = null;
     try {
         Sentry.addBreadcrumb({
             category: "command",
             message: sanitizeArgv(process.argv.slice(2)).join(" "),
             level: "info",
         });
-        // Hard version gate: ask hq-pro whether this CLI is below the floor and
-        // auto-update if so (exits the process on update). Skipped for inspection
-        // flags (`--version`, `--help`) so users debugging a broken install can
-        // still introspect what they have. Silent on any failure — never blocks
-        // the CLI on a flaky network or hq-pro hiccup. See `utils/version-gate.ts`.
+        // Version handling, both halves. Skipped for inspection flags
+        // (`--version`, `--help`) so users debugging a broken install can still
+        // introspect what they have, and silent on any failure — neither half may
+        // block the CLI on a flaky network or an hq-pro hiccup.
+        //
+        // 1. Hard gate: hq-pro says this version is below the enforced floor →
+        //    update and exit (the user reruns). See `utils/version-gate.ts`.
+        // 2. Soft: we're merely behind npm `latest` → update in place and re-run
+        //    this exact command on the new version, so the user never sees the
+        //    old "a new version is available" nag. Two independent signals feed
+        //    it (hq-pro's `updateRecommended` and the cached npm latest from
+        //    `version-check.ts`); whichever fires first re-execs, and the child
+        //    carries a guard env so it can never update again.
         if (!shouldSkipGate(process.argv)) {
-            await enforceVersionGate();
+            const gate = await enforceVersionGate(async (decision) => {
+                const outcome = await autoUpdateAndReexec(process.argv, decision.latestVersion);
+                if (outcome.action === "reexec")
+                    reexecStatus = outcome.reexecStatus ?? 0;
+                return outcome.action === "reexec";
+            });
+            if (gate === "reexec")
+                return;
+            const cachedLatest = staleAgainstCachedLatest();
+            if (cachedLatest) {
+                const outcome = await autoUpdateAndReexec(process.argv, cachedLatest);
+                if (outcome.action === "reexec") {
+                    reexecStatus = outcome.reexecStatus ?? 0;
+                    return;
+                }
+            }
         }
         await program.parseAsync();
     }
@@ -269,6 +296,10 @@ export async function runCli() {
         // command has completed, so a bounded best-effort wait is the terminal
         // lifecycle boundary for this invocation.
         await settleWithin([refreshVersionCache(), Sentry.flush(2000)], RELEASE_HEALTH_SETTLE_TIMEOUT_MS);
+        // Last, so it wins over anything the (skipped) command path would have
+        // set: the re-exec'd child's status IS this invocation's result.
+        if (reexecStatus !== null)
+            process.exitCode = reexecStatus;
     }
 }
 const defaultTopLevelErrorDependencies = {

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

@@ -0,0 +1,111 @@
+/**
+ * CLI self-update: replace the running hq-cli global install with npm `latest`
+ * and re-exec the user's command so it runs on the fresh version.
+ *
+ * Two entry points, one mechanism:
+ *
+ *   - `autoUpdateAndReexec` — the default startup path. Previously the CLI just
+ *     printed "⚠ A new version is available" on every single command; now it
+ *     performs the update and re-runs the command, and only warns when the
+ *     update itself fails. Installs quietly (the package manager's stdout is
+ *     captured, never forwarded) because `--json` consumers parse ours.
+ *
+ *   - `selfUpdateAndReexec` — `hq rescue`. The rescue script ships inside this
+ *     install's `@indigoai-us/hq-cloud` dependency, so a stale CLI runs a stale
+ *     rescue; rescue therefore updates unconditionally-if-stale rather than
+ *     waiting for the cached npm signal, and shows the install output because
+ *     the user is watching a long recovery operation.
+ *
+ * Relationship to the other two update surfaces:
+ *   - `version-gate.ts` hard-updates when hq-pro reports the version is below
+ *     the enforced `minVersion` (and now delegates its softer
+ *     "updateRecommended" case here instead of nagging).
+ *   - `version-check.ts` maintains the cached npm `latest` that the startup
+ *     path reads, so the common case costs a small file read, not a fetch.
+ *
+ * Best-effort by design: registry unreachable, npm/pnpm missing, install
+ * failure, or `hq` not on PATH for the re-exec all degrade to running the
+ * command on the current version. Self-updating must never make a command less
+ * available than it was before.
+ *
+ * Opt-outs: `HQ_NO_UPDATE_CHECK=1` (the shared knob that also silences
+ * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
+ */
+import { type RunningInstall, type UpdateResult } from "./version-gate.js";
+/**
+ * Set on the re-exec'd child so it can never self-update (and re-exec) again.
+ * One update + one re-exec per user invocation, ever.
+ */
+export declare const REEXEC_GUARD_ENV = "HQ_RESCUE_SELF_UPDATED";
+export type SelfUpdateAction = 
+/** Opted out, guard set, lock held elsewhere, or latest unknown — nothing attempted. */
+"skipped"
+/** Already at (or ahead of) npm latest. */
+ | "current"
+/** An update was attempted and failed; continue on the current version. */
+ | "update-failed"
+/** Updated, but the re-exec couldn't start; continue on the current (in-memory) version. */
+ | "updated-no-reexec"
+/** Updated and the command re-ran on the new version; exit with `reexecStatus`. */
+ | "reexec";
+export interface SelfUpdateOutcome {
+    action: SelfUpdateAction;
+    /** Exit status of the re-exec'd `hq …` (action === "reexec"). */
+    reexecStatus?: number;
+    latest?: string;
+}
+/**
+ * The manager-aware install argv for this layout — same routing as the hard
+ * gate: a pnpm-managed install must be updated by pnpm (npm would drop a copy
+ * the pnpm shim never reads), and an npm install goes through the resolved
+ * prefix so the copy that is actually running is the one replaced.
+ */
+export declare function buildSelfUpdatePlan(install: RunningInstall): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Install without letting the package manager write to OUR stdout. The startup
+ * path runs ahead of every command, including `--json` ones whose stdout is
+ * parsed by scripts and by HQ itself, and `npm install -g` prints its summary
+ * to stdout. Progress is summarised on stderr by the caller instead; captured
+ * stderr is kept only to explain a failure.
+ */
+export declare function runUpdateQuiet(cmd: string, args: string[]): UpdateResult;
+/**
+ * Serialize self-updates across concurrent `hq` processes. Without this, a
+ * machine running several HQ agents can fire many `npm install -g` at the same
+ * global prefix at once, and the losers fail with ENOTEMPTY mid-rename — the
+ * exact partial-install state `cleanStalePartialInstall` exists to repair.
+ * A caller that cannot take the lock simply skips its update: another process
+ * is already installing the very version it wanted.
+ *
+ * `mkdir` is the atomic primitive (same approach as version-check's refresh
+ * lock); a lock left behind by a killed process goes stale and is reclaimed.
+ */
+export declare function acquireUpdateLock(now?: number): (() => void) | null;
+/** Injectable surface so the flow is unit-testable without network or spawns. */
+export interface SelfUpdateDeps {
+    env?: NodeJS.ProcessEnv;
+    currentVersion?: string;
+    fetchLatest?: () => Promise<string | null>;
+    resolveInstall?: () => RunningInstall;
+    runner?: (cmd: string, args: string[]) => UpdateResult;
+    reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
+    acquireLock?: () => (() => void) | null;
+}
+/**
+ * Startup path: the running CLI is behind npm `latest`, so update in place and
+ * re-run the user's command on the new version. `latest` is normally the cached
+ * value from `version-check.ts` (no fetch on the hot path); pass null to let
+ * this resolve it from the registry.
+ */
+export declare function autoUpdateAndReexec(argv: readonly string[], latest: string | null, deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
+/**
+ * Rescue path: update to npm latest and re-exec the rescue on the new version.
+ * `argv` is the full process argv (`process.argv`); the re-exec re-runs
+ * `argv.slice(2)` verbatim so flags like `--staging` / `--yes` / `--hq-root`
+ * are preserved.
+ */
+export declare function selfUpdateAndReexec(argv: readonly string[], deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
+//# sourceMappingURL=self-update.d.ts.map

package/dist/utils/self-update.js

@@ -0,0 +1,247 @@
+/**
+ * CLI self-update: replace the running hq-cli global install with npm `latest`
+ * and re-exec the user's command so it runs on the fresh version.
+ *
+ * Two entry points, one mechanism:
+ *
+ *   - `autoUpdateAndReexec` — the default startup path. Previously the CLI just
+ *     printed "⚠ A new version is available" on every single command; now it
+ *     performs the update and re-runs the command, and only warns when the
+ *     update itself fails. Installs quietly (the package manager's stdout is
+ *     captured, never forwarded) because `--json` consumers parse ours.
+ *
+ *   - `selfUpdateAndReexec` — `hq rescue`. The rescue script ships inside this
+ *     install's `@indigoai-us/hq-cloud` dependency, so a stale CLI runs a stale
+ *     rescue; rescue therefore updates unconditionally-if-stale rather than
+ *     waiting for the cached npm signal, and shows the install output because
+ *     the user is watching a long recovery operation.
+ *
+ * Relationship to the other two update surfaces:
+ *   - `version-gate.ts` hard-updates when hq-pro reports the version is below
+ *     the enforced `minVersion` (and now delegates its softer
+ *     "updateRecommended" case here instead of nagging).
+ *   - `version-check.ts` maintains the cached npm `latest` that the startup
+ *     path reads, so the common case costs a small file read, not a fetch.
+ *
+ * Best-effort by design: registry unreachable, npm/pnpm missing, install
+ * failure, or `hq` not on PATH for the re-exec all degrade to running the
+ * command on the current version. Self-updating must never make a command less
+ * available than it was before.
+ *
+ * Opt-outs: `HQ_NO_UPDATE_CHECK=1` (the shared knob that also silences
+ * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import semver from "semver";
+import chalk from "chalk";
+import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
+import { buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+/**
+ * Set on the re-exec'd child so it can never self-update (and re-exec) again.
+ * One update + one re-exec per user invocation, ever.
+ */
+export const REEXEC_GUARD_ENV = "HQ_RESCUE_SELF_UPDATED";
+const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(CLI_NAME)}/latest`;
+const FETCH_TIMEOUT_MS = 3_000;
+/** A held update lock older than this is treated as abandoned (crashed owner). */
+const UPDATE_LOCK_STALE_MS = 10 * 60 * 1000;
+/** Tail of captured package-manager stderr kept for the failure warning. */
+const DETAIL_MAX_CHARS = 400;
+/** npm `latest` for this package, or null on any failure (offline, 5xx, bad body). */
+async function fetchLatestVersion() {
+    try {
+        const res = await fetch(REGISTRY_URL, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === "string" ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The manager-aware install argv for this layout — same routing as the hard
+ * gate: a pnpm-managed install must be updated by pnpm (npm would drop a copy
+ * the pnpm shim never reads), and an npm install goes through the resolved
+ * prefix so the copy that is actually running is the one replaced.
+ */
+export function buildSelfUpdatePlan(install) {
+    if (install.manager === "pnpm")
+        return { cmd: "pnpm", args: buildPnpmInstallArgv() };
+    if (install.prefix)
+        return { cmd: "npm", args: buildPrefixedInstallArgv(install.prefix) };
+    return { cmd: "npm", args: ["install", "-g", `${CLI_NAME}@latest`] };
+}
+/**
+ * Install without letting the package manager write to OUR stdout. The startup
+ * path runs ahead of every command, including `--json` ones whose stdout is
+ * parsed by scripts and by HQ itself, and `npm install -g` prints its summary
+ * to stdout. Progress is summarised on stderr by the caller instead; captured
+ * stderr is kept only to explain a failure.
+ */
+export function runUpdateQuiet(cmd, args) {
+    try {
+        const plan = buildSpawnPlan(cmd, args);
+        const result = spawnSync(plan.cmd, plan.args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: plan.shell,
+            encoding: "utf-8",
+        });
+        if (result.error) {
+            const code = result.error.code;
+            return { ok: false, code, detail: result.error.message };
+        }
+        if (result.status !== 0) {
+            const stderr = (result.stderr ?? "").trim();
+            const tail = stderr ? stderr.slice(-DETAIL_MAX_CHARS) : "";
+            return {
+                ok: false,
+                detail: tail || `exit ${result.status ?? "signal"}`,
+            };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: err?.code,
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function lockDir() {
+    return path.join(os.homedir(), ".hq", "self-update.lock");
+}
+/**
+ * Serialize self-updates across concurrent `hq` processes. Without this, a
+ * machine running several HQ agents can fire many `npm install -g` at the same
+ * global prefix at once, and the losers fail with ENOTEMPTY mid-rename — the
+ * exact partial-install state `cleanStalePartialInstall` exists to repair.
+ * A caller that cannot take the lock simply skips its update: another process
+ * is already installing the very version it wanted.
+ *
+ * `mkdir` is the atomic primitive (same approach as version-check's refresh
+ * lock); a lock left behind by a killed process goes stale and is reclaimed.
+ */
+export function acquireUpdateLock(now = Date.now()) {
+    const dir = lockDir();
+    const release = () => {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort lock cleanup
+        }
+    };
+    try {
+        fs.mkdirSync(path.dirname(dir), { recursive: true });
+        fs.mkdirSync(dir);
+        return release;
+    }
+    catch {
+        try {
+            const stat = fs.statSync(dir);
+            if (now - stat.mtimeMs > UPDATE_LOCK_STALE_MS) {
+                fs.rmSync(dir, { recursive: true, force: true });
+                fs.mkdirSync(dir);
+                return release;
+            }
+        }
+        catch {
+            // lock vanished or is unreadable — treat as held and skip
+        }
+        return null;
+    }
+}
+/**
+ * Re-run `hq <argv…>` from PATH so the freshly-installed version handles the
+ * command. Returns the child's exit status, or null when the child could not be
+ * started at all (e.g. `hq` not on PATH in a minimal-PATH parent).
+ */
+function reexecHq(argv, env) {
+    const plan = buildSpawnPlan("hq", argv);
+    const result = spawnSync(plan.cmd, plan.args, {
+        stdio: "inherit",
+        shell: plan.shell,
+        env,
+    });
+    if (result.error)
+        return null;
+    // A signal-killed child has status null; surface it as a failure exit rather
+    // than pretending the command completed.
+    return result.status ?? 1;
+}
+async function updateAndReexec(argv, flavor, known, deps) {
+    const env = deps.env ?? process.env;
+    if (env[REEXEC_GUARD_ENV] === "1" || env.HQ_NO_UPDATE_CHECK === "1") {
+        return { action: "skipped" };
+    }
+    const latest = known ?? (await (deps.fetchLatest ?? fetchLatestVersion)());
+    if (!latest)
+        return { action: "skipped" };
+    const current = semver.valid(deps.currentVersion ?? CLI_VERSION);
+    const latestValid = semver.valid(latest);
+    if (!current || !latestValid)
+        return { action: "skipped" };
+    if (!semver.gt(latestValid, current))
+        return { action: "current", latest };
+    const releaseLock = flavor.lock ? (deps.acquireLock ?? acquireUpdateLock)() : () => { };
+    if (!releaseLock)
+        return { action: "skipped", latest };
+    let result;
+    const install = (deps.resolveInstall ?? resolveRunningInstall)();
+    const plan = buildSelfUpdatePlan(install);
+    try {
+        console.error(chalk.dim(`Updating hq-cli ${current} → ${latest}…`));
+        const defaultRunner = flavor.verbose ? runUpdateCommand : runUpdateQuiet;
+        result = (deps.runner ?? defaultRunner)(plan.cmd, plan.args);
+    }
+    finally {
+        releaseLock();
+    }
+    if (!result.ok) {
+        // The one case that still warrants the old yellow banner: we could not get
+        // the user onto the new version, so they need to know it exists and how to
+        // install it by hand.
+        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(" ")}`));
+        console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
+        return { action: "update-failed", latest };
+    }
+    const childEnv = { ...env, [REEXEC_GUARD_ENV]: "1" };
+    const status = (deps.reexec ?? reexecHq)([...argv.slice(2)], childEnv);
+    if (status === null) {
+        console.error(chalk.yellow(`⚠ Updated hq-cli to ${latest}, but couldn't re-launch \`hq\` from PATH; ` +
+            `continuing the ${flavor.noun} on ${current}.`));
+        return { action: "updated-no-reexec", latest };
+    }
+    console.error(chalk.dim(`✓ hq-cli updated to ${latest}.`));
+    return { action: "reexec", reexecStatus: status, latest };
+}
+/**
+ * Startup path: the running CLI is behind npm `latest`, so update in place and
+ * re-run the user's command on the new version. `latest` is normally the cached
+ * value from `version-check.ts` (no fetch on the hot path); pass null to let
+ * this resolve it from the registry.
+ */
+export async function autoUpdateAndReexec(argv, latest, deps = {}) {
+    return updateAndReexec(argv, { noun: "command", verbose: false, lock: true }, latest, deps);
+}
+/**
+ * Rescue path: update to npm latest and re-exec the rescue on the new version.
+ * `argv` is the full process argv (`process.argv`); the re-exec re-runs
+ * `argv.slice(2)` verbatim so flags like `--staging` / `--yes` / `--hq-root`
+ * are preserved.
+ */
+export async function selfUpdateAndReexec(argv, deps = {}) {
+    return updateAndReexec(argv, { noun: "rescue", verbose: true, lock: true }, null, deps);
+}
+//# sourceMappingURL=self-update.js.map

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

@@ -1,5 +1,15 @@
 declare function isKnownNoninteractiveStatusProbe(argv?: readonly string[]): boolean;
-export declare function maybeWarnNewVersion(): void;
+/**
+ * The cached npm `latest` when it is newer than the running version, else null.
+ *
+ * This replaced `maybeWarnNewVersion`, which printed a yellow "a new version is
+ * available" banner on EVERY command. The signal is the same (a fresh cache
+ * entry written by `refreshVersionCache` on a previous run, so the hot path
+ * stays a single file read); what changed is what the CLI does with it — see
+ * `utils/self-update.ts`, which installs the new version and re-runs the
+ * command, and warns only if that fails.
+ */
+export declare function staleAgainstCachedLatest(now?: number): string | null;
 export declare function refreshVersionCache(): Promise<void>;
 export declare const __test__: {
     CACHE_TTL_MS: number;

package/dist/utils/version-check.js

@@ -2,7 +2,6 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import semver from "semver";
-import chalk from "chalk";
 import { CLI_VERSION } from "../cli-version.js";
 const PACKAGE_NAME = "@indigoai-us/hq-cli";
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
@@ -96,22 +95,31 @@ function acquireRefreshLock(now = Date.now()) {
         return null;
     }
 }
-export function maybeWarnNewVersion() {
+/**
+ * The cached npm `latest` when it is newer than the running version, else null.
+ *
+ * This replaced `maybeWarnNewVersion`, which printed a yellow "a new version is
+ * available" banner on EVERY command. The signal is the same (a fresh cache
+ * entry written by `refreshVersionCache` on a previous run, so the hot path
+ * stays a single file read); what changed is what the CLI does with it — see
+ * `utils/self-update.ts`, which installs the new version and re-runs the
+ * command, and warns only if that fails.
+ */
+export function staleAgainstCachedLatest(now = Date.now()) {
     if (isOptedOut())
-        return;
+        return null;
     const entry = readCache();
     if (!entry)
-        return;
-    if (Date.now() - entry.fetchedAt > CACHE_TTL_MS)
-        return;
+        return null;
+    if (now - entry.fetchedAt > CACHE_TTL_MS)
+        return null;
     const current = semver.valid(CLI_VERSION);
     const latest = semver.valid(entry.latest);
     if (!current || !latest)
-        return;
+        return null;
     if (!semver.gt(latest, current))
-        return;
-    const msg = chalk.yellow(`⚠ A new version of hq is available: ${entry.latest} (current: ${CLI_VERSION}). It's recommended to update.`);
-    console.error(msg);
+        return null;
+    return entry.latest;
 }
 export async function refreshVersionCache() {
     if (isOptedOut())

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

@@ -29,7 +29,7 @@
  */
 /** Which package manager owns the running global install. */
 export type InstallManager = "npm" | "pnpm";
-interface VersionCheckResponse {
+export interface VersionCheckResponse {
     clientId: string;
     currentVersion: string;
     minVersion: string;
@@ -140,7 +140,7 @@ export declare function cleanStalePartialInstall(prefix: string, fs?: StaleInsta
  * forcing a re-invocation would run twice on the same process and feel
  * janky; instead we print a clear "rerun your command" message and exit.
  */
-type UpdateResult = {
+export type UpdateResult = {
     ok: boolean;
     detail?: string;
     code?: string;
@@ -166,7 +166,7 @@ export declare function buildSpawnPlan(cmd: string, args: readonly string[], pla
     args: string[];
     shell: boolean;
 };
-declare function runUpdateCommand(cmd: string, args: string[]): UpdateResult;
+export declare function runUpdateCommand(cmd: string, args: string[]): UpdateResult;
 declare function performUpdateCommand(cmd: string, args: string[], runner?: UpdateRunner): UpdateResult;
 declare function performUpdate(command: string, runner?: UpdateRunner): UpdateResult;
 /**
@@ -176,6 +176,11 @@ declare function performUpdate(command: string, runner?: UpdateRunner): UpdateRe
  * This path fires for EVERY version below latest (the hard gate only fires
  * below `minVersion`), so it is the far more frequently seen of the two and
  * must be manager-aware for the same reason the gate is.
+ *
+ * It is now only the FALLBACK: `enforceVersionGate` prefers the
+ * `onUpdateRecommended` handler that main.ts wires to the self-updater, which
+ * installs the new version and re-runs the command instead of nagging. This
+ * remains for callers that pass no handler.
  */
 declare function nudgeUpdateRecommended(decision: VersionCheckResponse, install?: RunningInstall): void;
 /**
@@ -203,8 +208,15 @@ declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: {
  * `--version` / `-v` callers MUST skip the gate (the user is debugging a
  * broken install and shouldn't be force-upgraded mid-investigation). Caller
  * is responsible for checking argv before invoking us — see index.ts.
+ *
+ * `onUpdateRecommended` takes over the soft (below-latest, above-minimum)
+ * case. main.ts passes the self-updater there so the CLI updates and re-runs
+ * the command rather than printing a banner on every invocation; if that
+ * handler reports it re-exec'd, the gate returns `"reexec"` and the caller
+ * must exit rather than running the command a second time.
  */
-export declare function enforceVersionGate(): Promise<void>;
+export type VersionGateOutcome = "continue" | "reexec";
+export declare function enforceVersionGate(onUpdateRecommended?: (decision: VersionCheckResponse, install: RunningInstall) => Promise<boolean>): Promise<VersionGateOutcome>;
 /**
  * Cheap argv pre-check: skip the gate for `--version` / `-V` so users
  * inspecting a broken install can still see what they have without being

package/dist/utils/version-gate.js

@@ -306,7 +306,7 @@ export function buildSpawnPlan(cmd, args, platform = process.platform) {
         return { cmd, args: [...args], shell: false };
     return { cmd, args: args.map(quoteForWindowsShell), shell: true };
 }
-function runUpdateCommand(cmd, args) {
+export function runUpdateCommand(cmd, args) {
     try {
         const plan = buildSpawnPlan(cmd, args);
         const result = spawnSync(plan.cmd, plan.args, {
@@ -368,6 +368,11 @@ function manualUpdateCommand(install, decision) {
  * This path fires for EVERY version below latest (the hard gate only fires
  * below `minVersion`), so it is the far more frequently seen of the two and
  * must be manager-aware for the same reason the gate is.
+ *
+ * It is now only the FALLBACK: `enforceVersionGate` prefers the
+ * `onUpdateRecommended` handler that main.ts wires to the self-updater, which
+ * installs the new version and re-runs the command instead of nagging. This
+ * remains for callers that pass no handler.
  */
 function nudgeUpdateRecommended(decision, install = resolveRunningInstall()) {
     const msg = chalk.yellow(`⚠ A new version of hq-cli is available: ${decision.latestVersion} (current: ${decision.currentVersion}).`);
@@ -500,24 +505,14 @@ function enforceUpdateRequired(decision, deps = {}) {
     console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
     process.exit(0);
 }
-/**
- * Public entry point. Call before commander parses argv. Blocks the CLI on
- * network IO for up to FETCH_TIMEOUT_MS — acceptable because the alternative
- * (a fire-and-forget background check) gives the user no chance to bail out
- * of a known-bad version before it does damage.
- *
- * `--version` / `-v` callers MUST skip the gate (the user is debugging a
- * broken install and shouldn't be force-upgraded mid-investigation). Caller
- * is responsible for checking argv before invoking us — see index.ts.
- */
-export async function enforceVersionGate() {
+export async function enforceVersionGate(onUpdateRecommended) {
     if (isOptedOut())
-        return;
+        return "continue";
     const decision = await fetchVersionDecision();
     if (!decision)
-        return; // best-effort: silent on any failure
+        return "continue"; // best-effort: silent on any failure
     if (!decision.updateRequired && !decision.updateRecommended)
-        return;
+        return "continue";
     // Resolved once, here, so the up-to-date case never pays for the walk and
     // neither downstream path repeats it.
     const install = resolveRunningInstall();
@@ -525,8 +520,16 @@ export async function enforceVersionGate() {
         enforceUpdateRequired(decision, { resolveInstall: () => install }); // exits process
     }
     if (decision.updateRecommended) {
+        if (onUpdateRecommended) {
+            // The handler owns its own failure messaging (it warns only when the
+            // update it attempted did not land), so there is no nudge fallback here.
+            if (await onUpdateRecommended(decision, install))
+                return "reexec";
+            return "continue";
+        }
         nudgeUpdateRecommended(decision, install);
     }
+    return "continue";
 }
 /**
  * Cheap argv pre-check: skip the gate for `--version` / `-V` so users

package/package.json

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