@indigoai-us/hq-cli 5.290.0 → 5.292.0

package/dist/main.js

@@ -36,7 +36,7 @@ import { browserLoginAbandonedMessage } from "./utils/browser-login-abandoned.js
 import { callbackPortBusyMessage, DEFAULT_CALLBACK_PORT } from "./utils/callback-port-busy.js";
 import { DEFAULT_COGNITO } from "./utils/cognito-session.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
-import { canOfferTeamUpgrade, formatPlanGateError, isPlanGateError, offerTeamUpgrade, offerUpgradeLink, } from "./utils/plan-gate-error.js";
+import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
 import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
@@ -344,6 +344,9 @@ function qmdSpawnFailureCaptureContext(err) {
 }
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export async function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies) {
+    // A typed plan gate, or an hq-cloud vault error carrying a plan-limit
+    // refusal (402 / PLAN_LIMIT_* from a sync, share or skill upload).
+    const planGate = planGateErrorFromVaultError(err);
     // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
     // (`hq … | head`, `source <(hq …)`, a parent that exited). That is normal
     // Unix behavior with no user-facing degradation — exit cleanly (0) and
@@ -416,24 +419,32 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         deps.stderr.write(`hq: ${callbackPortBusyMessage(err, DEFAULT_COGNITO.port ?? DEFAULT_CALLBACK_PORT)}\n`);
         deps.setExitCode(1);
     }
-    else if (isPlanGateError(err)) {
+    else if (planGate) {
         // Plan denials are expected product limits, never a CLI crash. The
         // server URL is always shown. Company refusals that the Workforce
         // checkout satisfies retain the direct Stripe checkout action.
+        //
+        // A plan-limit refusal (a Starter hard stop) always prints its reason,
+        // usage and fix options, even non-interactively: the user can fix it
+        // without upgrading, and an agent or script reading stderr needs the
+        // reason to act on it. Feature refusals keep the URL-only
+        // non-interactive form, because upgrading is their only fix.
         const interactive = deps.interactive ?? canOfferTeamUpgrade(deps.argv);
-        const message = formatPlanGateError(err, { urlOnly: !interactive });
+        const message = formatPlanGateError(planGate, {
+            urlOnly: !interactive && planGate.code !== "PLAN_LIMIT_EXCEEDED",
+        });
         deps.stderr.write(interactive ? `hq: ${message}\n` : `${message}\n`);
-        const promptExposure = isCliLimitResourceKind(err.details.resource ?? "")
-            ? queueCliLimitNoticeExposure(err.details.resource, "refusal", err.details.companyUid)
+        const promptExposure = isCliLimitResourceKind(planGate.details.resource ?? "")
+            ? queueCliLimitNoticeExposure(planGate.details.resource, "refusal", planGate.details.companyUid)
             : null;
         deps.setExitCode(1);
-        if (interactive && err.details.upgradeUrl) {
-            const companyUid = err.details.companyUid;
+        if (interactive && planGate.details.upgradeUrl) {
+            const companyUid = planGate.details.companyUid;
             const isCompanyWorkforceCheckout = typeof companyUid === "string" &&
                 /^cmp_[A-Za-z0-9_-]+$/.test(companyUid) &&
-                (err.code === "PLAN_REQUIRED" ||
-                    err.code === "MEETING_PLAN_REQUIRED" ||
-                    err.code === "BILLING_REQUIRED");
+                (planGate.code === "PLAN_REQUIRED" ||
+                    planGate.code === "MEETING_PLAN_REQUIRED" ||
+                    planGate.code === "BILLING_REQUIRED");
             if (isCompanyWorkforceCheckout && companyUid) {
                 try {
                     const upgraded = await offerTeamUpgrade(async () => {
@@ -450,7 +461,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
                     const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
                     deps.stderr.write(`hq: ${message}\n`);
                     try {
-                        const opened = await offerUpgradeLink(err.details.upgradeUrl, {
+                        const opened = await offerUpgradeLink(planGate.details.upgradeUrl, {
                             interactive: true,
                             argv: deps.argv,
                             ask: deps.ask,
@@ -467,7 +478,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             }
             else {
                 try {
-                    const opened = await offerUpgradeLink(err.details.upgradeUrl, {
+                    const opened = await offerUpgradeLink(planGate.details.upgradeUrl, {
                         interactive: true,
                         argv: deps.argv,
                         ask: deps.ask,

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

@@ -1,8 +1,15 @@
+import { type PlanLimitFreeMonth } from "../lib/billing/free-month.js";
 export type PlanGateCode = "PLAN_LIMIT_EXCEEDED" | "PLAN_REQUIRED" | "MEETING_PLAN_REQUIRED"
 /** A PERSONAL scope asked for a feature the paid Individual plan includes. */
  | "PERSONAL_PLAN_REQUIRED"
 /** External agent enrollment was denied by the company plan. */
  | "BILLING_REQUIRED";
+/** One over-limit dimension, as hq-pro's hard-stop 402 body names it. */
+export interface PlanGateResourceUsage {
+    resource: string;
+    used: number;
+    limit: number;
+}
 export interface PlanGateDetails {
     resource?: string;
     feature?: string;
@@ -12,6 +19,14 @@ export interface PlanGateDetails {
     reason?: string;
     /** Company target from request context or the server's UID-keyed billing URL. */
     companyUid?: string;
+    /** Hard-stop 402: the create action the server refused, e.g. `secrets.create`. */
+    blocked?: string;
+    /** Hard-stop 402: every over-limit dimension, in server order. */
+    resources?: PlanGateResourceUsage[];
+    /** Hard-stop 402: how far back each over resource must come, keyed by resource. */
+    fixOptions?: Record<string, number>;
+    /** Hard-stop 402: the free-month offer, present only when it stands. */
+    freeMonth?: PlanLimitFreeMonth;
 }
 /** One renderer for server-selected upgrade links across CLI plan refusals. */
 export declare function formatUpgradeRefusal(reason: string, upgradeUrl: string | undefined, options?: {
@@ -46,6 +61,15 @@ export declare function offerTeamUpgrade(onConfirm: () => Promise<void>, deps?:
 }): Promise<boolean>;
 /** Decode an already-read JSON envelope from either shared HTTP client. */
 export declare function planGateErrorFromPayload(status: number, body: unknown, companyUid?: string): PlanGateError | null;
+/**
+ * Recognise a plan-limit refusal carried by an `@indigoai-us/hq-cloud`
+ * `VaultClientError` (sync, share, skill upload). Duck-typed so hq-cli keeps
+ * working across hq-cloud releases: the error exposes `statusCode`, `code`,
+ * `upgradeUrl` and the raw response `body`. The raw body is decoded first so
+ * the server's message, fix options and free month survive; a bare code (a
+ * personal presign row has no body) still becomes a refusal with its link.
+ */
+export declare function planGateErrorFromVaultError(err: unknown): PlanGateError | null;
 /**
  * Decode the supported plan-gate envelopes. Malformed, unrelated,
  * or non-402 responses retain their existing command-specific handling.

package/dist/utils/plan-gate-error.js

@@ -3,17 +3,93 @@
  * fields on a typed error lets the CLI boundary render one safe, consistent
  * message instead of every command parsing and printing a server response.
  */
-import { renderPersonalPlanFeatureNotice } from "../lib/plan-limit-nag.js";
+import { PLAN_LIMIT_DIMENSION_LABELS, renderPersonalPlanFeatureNotice, } from "../lib/plan-limit-nag.js";
 import { withCliLimitEntrySurface } from "../lib/billing/plan-limit-upgrade-url.js";
+import { parseFreeMonth, } from "../lib/billing/free-month.js";
+const GIB = 1024 ** 3;
+const MIB = 1024 ** 2;
+const KIB = 1024;
+function formatStorageBytes(bytes) {
+    const round = (value) => String(Math.round(value * 10) / 10);
+    if (bytes >= GIB)
+        return `${round(bytes / GIB)} GB`;
+    if (bytes >= MIB)
+        return `${round(bytes / MIB)} MB`;
+    if (bytes >= KIB)
+        return `${round(bytes / KIB)} KB`;
+    return `${bytes} bytes`;
+}
+function formatResourceAmount(resource, amount) {
+    return resource === "storageBytes" ? formatStorageBytes(amount) : String(amount);
+}
+function resourceLabel(resource) {
+    const label = PLAN_LIMIT_DIMENSION_LABELS[resource] ?? resource;
+    return label.charAt(0).toUpperCase() + label.slice(1);
+}
+/** The trim-back action for one resource, phrased as what the user does. */
+function resourceFixAction(resource) {
+    switch (resource) {
+        case "users":
+            return "Remove members";
+        case "secrets":
+            return "Delete secrets";
+        case "integrations":
+            return "Disconnect integrations";
+        case "storageBytes":
+            return "Delete files";
+        case "agents":
+            return "Deprovision agents";
+        case "deployments":
+            return "Remove deployments";
+        default:
+            return `Reduce ${PLAN_LIMIT_DIMENSION_LABELS[resource] ?? resource}`;
+    }
+}
+/**
+ * Render a plan-limit refusal: the server's sentence, where each over
+ * resource stands, then every way out the server offered. Only the fix options
+ * the server actually sent are listed, so the CLI never suggests trimming a
+ * dimension nobody measured.
+ */
+function planLimitRefusalText(head, details) {
+    const lines = [head];
+    for (const row of details.resources ?? []) {
+        lines.push(`  ${resourceLabel(row.resource)}: ` +
+            `${formatResourceAmount(row.resource, row.used)} of ` +
+            `${formatResourceAmount(row.resource, row.limit)} used.`);
+    }
+    const fixes = [];
+    const freeMonthUrl = safeUpgradeUrl(details.freeMonth?.url);
+    if (details.freeMonth?.eligible && freeMonthUrl) {
+        fixes.push(`Start your free month — add a card, first month free: ${freeMonthUrl}`);
+    }
+    for (const [resource, target] of Object.entries(details.fixOptions ?? {})) {
+        fixes.push(`${resourceFixAction(resource)} to make room (your plan allows ` +
+            `${formatResourceAmount(resource, target)}).`);
+    }
+    if (fixes.length > 0) {
+        fixes.push("Upgrade your plan.");
+        lines.push("  Ways to sort it:");
+        fixes.forEach((fix, index) => lines.push(`    ${index + 1}. ${fix}`));
+    }
+    return lines.join("\n");
+}
 function planGateReason(code, details) {
+    if (code === "PLAN_LIMIT_EXCEEDED") {
+        const head = details.reason?.trim()
+            ? details.reason.trim()
+            : typeof details.resource === "string" &&
+                typeof details.used === "number" &&
+                typeof details.limit === "number"
+                ? `Starter plan limit reached: ${details.resource} ${details.used}/${details.limit} used.`
+                : details.resources?.length || details.fixOptions || details.freeMonth
+                    ? "Your plan limit has been reached."
+                    : undefined;
+        if (head)
+            return planLimitRefusalText(head, details);
+    }
     if (details.reason?.trim())
         return details.reason.trim();
-    if (code === "PLAN_LIMIT_EXCEEDED" &&
-        typeof details.resource === "string" &&
-        typeof details.used === "number" &&
-        typeof details.limit === "number") {
-        return `Starter plan limit reached: ${details.resource} ${details.used}/${details.limit} used.`;
-    }
     if (code === "PERSONAL_PLAN_REQUIRED") {
         return renderPersonalPlanFeatureNotice(details.feature ?? "this feature", null);
     }
@@ -171,6 +247,17 @@ export function planGateErrorFromPayload(status, body, companyUid) {
     const code = payload.code;
     const upgradeUrl = safeUpgradeUrl(payload.upgradeUrl);
     const targetCompanyUid = companyUid ?? companyUidFromPlanUpgradeUrl(upgradeUrl);
+    // Starter hard stops. The canonical body is `{ error: "plan_limit_reached",
+    // code: "PLAN_LIMIT_EXCEEDED", blocked, resources, message, fixOptions,
+    // freeMonth?, upgradeUrl }`; older servers send the body without `code`, the
+    // membership gate's legacy `{ code: "PLAN_LIMIT_EXCEEDED", resource, used,
+    // limit }`, or a personal presign row `{ code: "PLAN_LIMIT_REACHED" }`. All
+    // of them are the same refusal to the user, so they share one code.
+    if (payload.error === PLAN_LIMIT_REACHED_ERROR ||
+        code === "PLAN_LIMIT_EXCEEDED" ||
+        code === "PLAN_LIMIT_REACHED") {
+        return planLimitRefusalFromPayload(payload, upgradeUrl, targetCompanyUid);
+    }
     const planLimit = payload.planLimit !== null &&
         typeof payload.planLimit === "object" &&
         !Array.isArray(payload.planLimit)
@@ -184,8 +271,7 @@ export function planGateErrorFromPayload(status, body, companyUid) {
             return null;
         }
     }
-    else if (code !== "PLAN_LIMIT_EXCEEDED" &&
-        code !== "PLAN_REQUIRED" &&
+    else if (code !== "PLAN_REQUIRED" &&
         code !== "MEETING_PLAN_REQUIRED") {
         return null;
     }
@@ -204,6 +290,130 @@ export function planGateErrorFromPayload(status, body, companyUid) {
         ...(targetCompanyUid ? { companyUid: targetCompanyUid } : {}),
     });
 }
+/** Wire value of `error` on hq-pro's hard-stop 402 body. Never shown to users. */
+const PLAN_LIMIT_REACHED_ERROR = "plan_limit_reached";
+function finiteNonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
+function parseResources(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const rows = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const row = raw;
+        const used = finiteNonNegative(row.used);
+        const limit = finiteNonNegative(row.limit);
+        if (typeof row.resource !== "string" || used === undefined || limit === undefined) {
+            continue;
+        }
+        rows.push({ resource: row.resource, used, limit });
+    }
+    return rows.length > 0 ? rows : undefined;
+}
+function parseFixOptions(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const fix = {};
+    for (const [resource, target] of Object.entries(value)) {
+        const amount = finiteNonNegative(target);
+        if (amount !== undefined)
+            fix[resource] = amount;
+    }
+    return Object.keys(fix).length > 0 ? fix : undefined;
+}
+function planLimitRefusalFromPayload(payload, upgradeUrl, companyUid) {
+    // `message` is the customer sentence. A legacy `error` string is prose only
+    // when it is not a machine token (`plan_limit_reached`, or the code itself).
+    const reason = typeof payload.message === "string" && payload.message.trim()
+        ? payload.message
+        : typeof payload.error === "string" &&
+            payload.error.trim() &&
+            payload.error !== PLAN_LIMIT_REACHED_ERROR &&
+            payload.error !== payload.code
+            ? payload.error
+            : undefined;
+    const resources = parseResources(payload.resources);
+    const fixOptions = parseFixOptions(payload.fixOptions);
+    const parsedFreeMonth = parseFreeMonth(payload.freeMonth);
+    const freeMonthUrl = safeUpgradeUrl(parsedFreeMonth?.url);
+    const freeMonth = parsedFreeMonth
+        ? {
+            eligible: true,
+            ...(parsedFreeMonth.trialDays !== undefined
+                ? { trialDays: parsedFreeMonth.trialDays }
+                : {}),
+            ...(freeMonthUrl ? { url: freeMonthUrl } : {}),
+        }
+        : undefined;
+    const used = finiteNonNegative(payload.used);
+    const limit = finiteNonNegative(payload.limit);
+    return new PlanGateError("PLAN_LIMIT_EXCEEDED", {
+        ...(typeof payload.resource === "string" ? { resource: payload.resource } : {}),
+        ...(used !== undefined ? { used } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(typeof payload.blocked === "string" ? { blocked: payload.blocked } : {}),
+        ...(resources ? { resources } : {}),
+        ...(fixOptions ? { fixOptions } : {}),
+        ...(freeMonth ? { freeMonth } : {}),
+        ...(upgradeUrl ? { upgradeUrl } : {}),
+        ...(reason ? { reason } : {}),
+        ...(companyUid ? { companyUid } : {}),
+    });
+}
+/** Wire codes that mark a vault/sync error as a plan-limit refusal. */
+const PLAN_LIMIT_ERROR_CODES = new Set([
+    "PLAN_LIMIT_EXCEEDED",
+    "PLAN_LIMIT_REACHED",
+    PLAN_LIMIT_REACHED_ERROR,
+]);
+/**
+ * Recognise a plan-limit refusal carried by an `@indigoai-us/hq-cloud`
+ * `VaultClientError` (sync, share, skill upload). Duck-typed so hq-cli keeps
+ * working across hq-cloud releases: the error exposes `statusCode`, `code`,
+ * `upgradeUrl` and the raw response `body`. The raw body is decoded first so
+ * the server's message, fix options and free month survive; a bare code (a
+ * personal presign row has no body) still becomes a refusal with its link.
+ */
+export function planGateErrorFromVaultError(err) {
+    if (isPlanGateError(err))
+        return err;
+    if (!err || typeof err !== "object")
+        return null;
+    const candidate = err;
+    const code = typeof candidate.code === "string" ? candidate.code : undefined;
+    const isPlanLimitCode = code !== undefined && PLAN_LIMIT_ERROR_CODES.has(code);
+    if (candidate.statusCode !== 402 && !isPlanLimitCode)
+        return null;
+    if (typeof candidate.body === "string" && candidate.body.trim()) {
+        try {
+            const decoded = planGateErrorFromPayload(402, JSON.parse(candidate.body));
+            if (decoded) {
+                if (!decoded.details.upgradeUrl) {
+                    const upgradeUrl = safeUpgradeUrl(candidate.upgradeUrl);
+                    if (upgradeUrl) {
+                        return new PlanGateError(decoded.code, { ...decoded.details, upgradeUrl });
+                    }
+                }
+                return decoded;
+            }
+        }
+        catch {
+            // Not JSON: fall through to the structured fields on the error itself.
+        }
+    }
+    if (!isPlanLimitCode)
+        return null;
+    return planLimitRefusalFromPayload({
+        code,
+        ...(typeof candidate.message === "string"
+            ? { error: candidate.message }
+            : {}),
+    }, safeUpgradeUrl(candidate.upgradeUrl), undefined);
+}
 /**
  * Decode the supported plan-gate envelopes. Malformed, unrelated,
  * or non-402 responses retain their existing command-specific handling.

package/dist/utils/scaffold-sibling-references.js

@@ -42,7 +42,7 @@ function shellLocationAliases(contents) {
         const scriptRoot = SCRIPT_ROOT_TOKENS.exec(value);
         if (scriptRoot) {
             const suffix = value.slice(scriptRoot.index + scriptRoot[0].length)
-                .match(/^\/([^"'`\s;|&)]+)/)?.[1] ?? ".";
+                .match(/^\/([^"'`\s;|&)}]+)/)?.[1] ?? ".";
             aliases.set(name, { kind: "asset", baseDirectory: path.posix.normalize(suffix) });
             continue;
         }
@@ -116,15 +116,15 @@ export function scanScaffoldSiblingReferences(scaffoldRoot) {
             (/\b(?:source|exec|bash|sh|node)\b/.test(line) || /^\s*\.\s+/.test(line)));
         for (const line of commandLines) {
             SCRIPT_ROOT_TOKENS.lastIndex = 0;
-            for (const match of line.matchAll(/(?:\$\{SCRIPT_DIR\}|\$SCRIPT_DIR)\/([^"'`\s;|&)]+)/g)) {
+            for (const match of line.matchAll(/(?:\$\{SCRIPT_DIR\}|\$SCRIPT_DIR)\/([^"'`\s;|&)}]+)/g)) {
                 recordRelative(sourceFile, match[1]);
             }
-            const dirnamePath = new RegExp(String.raw `\$\(\s*dirname\s+["']?${BASH_SOURCE_TOKEN}["']?\s*\)(\/[^"'\x60\s;|&)]+)`, "g");
+            const dirnamePath = new RegExp(String.raw `\$\(\s*dirname\s+["']?${BASH_SOURCE_TOKEN}["']?\s*\)(\/[^"'\x60\s;|&)}]+)`, "g");
             for (const match of line.matchAll(dirnamePath))
                 recordRelative(sourceFile, match[1]);
             for (const [alias, location] of aliases) {
                 const escapedAlias = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-                const aliasPath = new RegExp(String.raw `(?:\$\{${escapedAlias}\}|\$${escapedAlias})\/([^"'\x60\s;|&)]+)`, "g");
+                const aliasPath = new RegExp(String.raw `(?:\$\{${escapedAlias}\}|\$${escapedAlias})\/([^"'\x60\s;|&)}]+)`, "g");
                 for (const match of line.matchAll(aliasPath)) {
                     if (location.kind === "hq-root") {
                         const reference = match[0];

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

@@ -161,6 +161,12 @@ export interface SelfUpdateDeps {
     interactive?: boolean;
     /** Best-effort daemon kick after the CLI install converges (tests). */
     restartDaemon?: () => RestartDaemonResult | void;
+    /**
+     * Whether `cli.staged-self-update` is on: build the new version beside the
+     * running package and swap it in, instead of moving the running package
+     * aside for the whole install. Read only when an npm global install is due.
+     */
+    stagedSelfUpdate?: () => Promise<boolean>;
 }
 /**
  * Startup path: the running CLI is behind npm `latest`, so update in place and

package/dist/utils/self-update.js

@@ -64,6 +64,7 @@ import semver from "semver";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, checkUpdateConvergence, derivePnpmHome, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, isPrefixWritable, 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";
 import { restartDaemonServiceIfInstalled } from "../lib/mesh/live/daemon/install.js";
@@ -414,12 +415,15 @@ 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 };
     const renamePath = deps.renamePath ?? fs.renameSync;
-    const installSnapshot = snapshotInstall(install, renamePath);
-    if (!installSnapshot) {
+    // The staged install keeps the running package in place until the swap and
+    // restores it itself, so it takes no snapshot.
+    const installSnapshot = staged ? null : snapshotInstall(install, renamePath);
+    if (!staged && !installSnapshot) {
         console.error(chalk.dim("  No backup could be made for this hq-cli install; proceeding without rollback protection."));
     }
     let result;
@@ -440,10 +444,15 @@ async function updateAndReexec(argv, flavor, known, deps) {
         // Forward env only when PNPM_HOME had to be injected, so the common path
         // spawns with the inherited environment and keeps the two-argument runner
         // call it has always made.
-        result =
-            updateEnv === undefined
-                ? runner(plan.cmd, plan.args)
-                : runner(plan.cmd, plan.args, updateEnv);
+        if (staged) {
+            result = stagedNpmInstall(install, latestValid, { run: runner, env, rename: renamePath });
+        }
+        else if (updateEnv === undefined) {
+            result = runner(plan.cmd, plan.args);
+        }
+        else {
+            result = runner(plan.cmd, plan.args, updateEnv);
+        }
         if (!result.ok && installSnapshot) {
             restoredAfterFailure = restoreInstall(installSnapshot, renamePath);
             if (restoredAfterFailure)
@@ -537,6 +546,19 @@ async function updateAndReexec(argv, flavor, known, deps) {
     console.error(chalk.dim(`✓ hq-cli updated to ${latest}.`));
     return { action: "reexec", reexecStatus: status, latest };
 }
+async function readStagedSelfUpdateFlag(deps, env) {
+    try {
+        if (deps.stagedSelfUpdate)
+            return await deps.stagedSelfUpdate();
+        // Loaded here so the startup path pays for the flag client only when an
+        // update is actually due.
+        const { readDaemonFlag, STAGED_SELF_UPDATE_FLAG } = await import("../lib/daemon/flag.js");
+        return await readDaemonFlag(STAGED_SELF_UPDATE_FLAG, { env });
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * 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

package/dist/utils/staged-install.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Staged npm self-update: install the new hq-cli beside the running package,
+ * check that it starts, then swap it in with two renames.
+ *
+ * The in-place update moves the live package aside for the whole
+ * `npm install -g`, so anything that starts `hq` during the install finds no
+ * CLI on disk ("hq: command not found", MODULE_NOT_FOUND; outposts primary and
+ * 2, 5.290.0 -> 5.291.0). Here the live package stays in place until the new
+ * one is complete and has answered `--version`.
+ *
+ * Only a plain npm global layout is staged: `<prefix>/lib/node_modules/<pkg>`
+ * as a real directory, with bin links in `<prefix>/bin`. pnpm, Bun, Windows
+ * and linked checkouts keep the in-place update.
+ */
+import * as fs from "node:fs";
+import { type RunningInstall, type UpdateResult } from "./version-gate.js";
+/** Set for the staging install; hq-cli's own postinstall skips itself on it. */
+export declare const STAGED_INSTALL_ENV = "HQ_STAGED_INSTALL";
+export interface StagedInstallDeps {
+    /** Runs the package manager. Defaults to {@link runUpdateCommand}. */
+    run?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
+    env?: NodeJS.ProcessEnv;
+    /** The version the staged package's `hq --version` reports, or null. */
+    probeVersion?: (packageRoot: string) => string | null;
+    /** The package's postinstall, run from the live path after the swap. */
+    runPostinstall?: (packageRoot: string) => void;
+    rename?: typeof fs.renameSync;
+    /** Removes the staging and backup directories. */
+    remove?: (target: string) => void;
+    platform?: NodeJS.Platform;
+}
+export declare function canStageInstall(install: RunningInstall, platform?: NodeJS.Platform): boolean;
+export declare function stagedNpmInstall(install: RunningInstall, version: string, deps?: StagedInstallDeps): UpdateResult;
+//# sourceMappingURL=staged-install.d.ts.map