@indigoai-us/hq-cli 5.342.10 → 5.342.12

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [5.342.12] — 2026-10-04
+
+- Record every lane worker resume with its launch time and trigger, and classify watcher, monitor-event, and pending-work wakes separately from keep-alive timer accuracy.
+
+- Hand off the package-use lease through a non-JSON marker after a re-executed CLI publishes its matching lease, and forward parent-only stop signals to the child.
+
+## [5.342.11] — 2026-10-04
+- Release the CLI package-use lease before interactive login waits after resident modules preload.
+- Show the cached version update nudge after interactive commands when a newer cached release remains and its feature flag is enabled; avoid waiting for registry readiness when there is no nudge to show or repeating guidance after the updater already reported its result.
+
 ## [5.342.10] — 2026-10-04
 - Attach bounded status, gateway error-class, and integrations subcommand tags to captured gateway faults.
 

package/dist/command-catalog.generated.d.ts

@@ -11147,7 +11147,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "keep-alive-audit";
-        readonly description: "Audit lead lane keep-alive timing. A later envelope proves another turn ran and may reclassify an expired stop as restarted_untimed when no launch record remains; late_restarts_after_window counts known launches after the grace window.";
+        readonly description: "Audit lead lane keep-alive timing. Durable worker-resume events retain launch time and trigger after bounded lane history rolls over; late_restarts_after_window counts known launches after the grace window.";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;

package/dist/command-catalog.generated.js

@@ -13537,7 +13537,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "keep-alive-audit",
-                "description": "Audit lead lane keep-alive timing. A later envelope proves another turn ran and may reclassify an expired stop as restarted_untimed when no launch record remains; late_restarts_after_window counts known launches after the grace window.",
+                "description": "Audit lead lane keep-alive timing. Durable worker-resume events retain launch time and trigger after bounded lane history rolls over; late_restarts_after_window counts known launches after the grace window.",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,

package/dist/commands/auth.js

@@ -14,6 +14,8 @@
  * session is kept valid by `hq auth refresh` / `hq-auth-refresh` and consumed
  * by the deploy + sync skills.
  */
+import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload } from "../utils/package-use-lease.js";
+import { preloadResidentPackageModules, reportResidentPackagePreloadFailure } from "../utils/resident-package-preload.js";
 import * as fs from "node:fs";
 import { open, realpath } from "node:fs/promises";
 import path from "node:path";
@@ -231,6 +233,7 @@ export function registerAuthCommands(program) {
                 }
             }
             const selection = resolveLoginProviderSelection(options.provider, process.env, rememberedProvider);
+            await releasePackageUseLeaseAfterResidentPreload(() => preloadResidentPackageModules("auth-login"), reportResidentPackagePreloadFailure, releaseCurrentPackageUseLease);
             const tokens = await browserLogin(selection.config);
             try {
                 storeLastLoginProvider(providerFromIdToken(tokens.idToken) ?? selection.providerToRemember);

package/dist/commands/lanes-keep-alive-audit.js

@@ -2,7 +2,7 @@ import { buildKeepAliveAudit, formatKeepAliveAuditText } from "../lib/lanes/keep
 export function registerLaneKeepAliveAuditCommand(parent, deps) {
     parent
         .command("keep-alive-audit")
-        .description("Audit lead lane keep-alive timing. A later envelope proves another turn ran and may reclassify an expired stop as restarted_untimed when no launch record remains; late_restarts_after_window counts known launches after the grace window.")
+        .description("Audit lead lane keep-alive timing. Durable worker-resume events retain launch time and trigger after bounded lane history rolls over; late_restarts_after_window counts known launches after the grace window.")
         .option("--since <iso>", "Include stopped turns at or after this ISO date-time")
         .option("--lane <id>", "Audit one exact lane id")
         .option("--json", "Print the report as JSON")

package/dist/commands/login.js

@@ -1,6 +1,8 @@
 /**
  * hq login — opens browser for Cognito auth.
  */
+import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload } from "../utils/package-use-lease.js";
+import { preloadResidentPackageModules, reportResidentPackagePreloadFailure } from "../utils/resident-package-preload.js";
 import chalk from 'chalk';
 import { browserLogin, loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
 import { cognitoConfigForLoginProvider } from '../utils/login-provider.js';
@@ -30,6 +32,15 @@ export function registerLoginCommand(program) {
         .option('--provider <provider>', 'OAuth provider to use: google, microsoft, or picker')
         .action(async (options) => {
         let accessToken;
+        let packageUseLeaseReleased = false;
+        const releaseForInteractiveWait = async () => {
+            if (packageUseLeaseReleased)
+                return;
+            await releasePackageUseLeaseAfterResidentPreload(async () => {
+                await preloadResidentPackageModules("login");
+                packageUseLeaseReleased = true;
+            }, reportResidentPackagePreloadFailure, releaseCurrentPackageUseLease);
+        };
         try {
             const existing = loadCachedTokens();
             if (existing && !isExpiring(existing, 120)) {
@@ -38,6 +49,7 @@ export function registerLoginCommand(program) {
                 accessToken = existing.accessToken;
             }
             else {
+                await releaseForInteractiveWait();
                 console.log('Opening browser for authentication...');
                 const tokens = await browserLogin(cognitoConfigForLoginProvider(options.provider));
                 const who = peekIdToken(tokens.idToken).email ?? 'HQ';
@@ -63,6 +75,7 @@ export function registerLoginCommand(program) {
                     .join("\n");
                 const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
                 try {
+                    await releaseForInteractiveWait();
                     const answer = await rl.question(`Choose this device's default company:\n${choices}\nSelection: `);
                     const selected = activation.memberships[Number.parseInt(answer, 10) - 1];
                     if (selected) {

package/dist/lib/flag-registry.js

@@ -47,6 +47,7 @@ let refreshCompletion = Promise.resolve();
 let completeRefresh = null;
 let refreshWorker = null;
 let refreshCompanyUid;
+let refreshHasCompanyContext = false;
 let refreshPendingSnapshot = null;
 let refreshSentry;
 /** Wait briefly for the current company refresh to persist or report completion. */
@@ -144,13 +145,12 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
     completeRefresh = null;
     refreshWorker = null;
     refreshCompanyUid = companyUid;
+    refreshHasCompanyContext = Boolean(companyUid || company.companySlug);
     refreshPendingSnapshot = null;
     refreshSentry = sentry;
-    if (companyUid || company.companySlug) {
-        refreshCompletion = new Promise((resolve) => {
-            completeRefresh = resolve;
-        });
-    }
+    refreshCompletion = new Promise((resolve) => {
+        completeRefresh = resolve;
+    });
     const finishRefresh = () => {
         completeRefresh?.();
         completeRefresh = null;
@@ -220,6 +220,10 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
                     refreshPendingSnapshot = null;
                     finishRefresh();
                 }
+                else if (!refreshHasCompanyContext) {
+                    refreshPendingSnapshot = null;
+                    finishRefresh();
+                }
             }
             else {
                 finishRefresh();
@@ -316,6 +320,7 @@ export function _resetFlagRegistryForTests() {
     completeRefresh = null;
     refreshWorker = null;
     refreshCompanyUid = undefined;
+    refreshHasCompanyContext = false;
     refreshPendingSnapshot = null;
     refreshSentry = undefined;
 }

package/dist/lib/lanes/keep-alive-audit.d.ts

@@ -1,8 +1,9 @@
-type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "keep_alive_off" | "waiting";
+type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "work_triggered" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "keep_alive_off" | "waiting";
 interface KeepAliveAuditRestart {
     at: string | null;
     trigger: string;
     caller: string | null;
+    workerEvent?: boolean;
 }
 interface KeepAliveAuditRow {
     lane: string;

package/dist/lib/lanes/keep-alive-audit.js

@@ -55,6 +55,7 @@ const VERDICTS = [
     "late",
     "early_wake",
     "message_wake",
+    "work_triggered",
     "self_wake",
     "early_by_keep_alive",
     "restarted_untimed",
@@ -68,6 +69,50 @@ function parseTime(value) {
     const parsed = Date.parse(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
+function readLaneWorkerResumeEvents(hqRoot, laneId) {
+    const root = fs.realpathSync(hqRoot);
+    const eventsPath = path.join(laneRunDir(root, laneId), "watcher", "events.jsonl");
+    if (!withinRoot(root, eventsPath)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher event path escapes the HQ root for ${laneId}`, { lane_id: laneId });
+    }
+    let text;
+    try {
+        const stat = fs.lstatSync(eventsPath);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane watcher events must be a regular file: ${eventsPath}`, { lane_id: laneId, path: eventsPath });
+        }
+        const realPath = fs.realpathSync(eventsPath);
+        if (!withinRoot(root, realPath)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher event file escapes the HQ root for ${laneId}`, { lane_id: laneId, path: eventsPath });
+        }
+        text = fs.readFileSync(realPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const events = [];
+    for (const [index, line] of text.split(/\r?\n/).entries()) {
+        if (!line.trim())
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(value) || value.event !== "lane_worker_resumed")
+            continue;
+        const at = parseTime(value.resumed_at);
+        if (at === undefined || typeof value.reason !== "string" || !value.reason.trim()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane worker resume event has invalid timing or reason: ${eventsPath}:${index + 1}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
+        }
+        events.push({ at, reason: value.reason, caller: typeof value.caller === "string" ? value.caller : null });
+    }
+    return events.sort((a, b) => a.at - b.at);
+}
 function iso(ms) {
     return new Date(ms).toISOString();
 }
@@ -176,9 +221,7 @@ function readKeepAliveResumeEvents(hqRoot, laneId) {
         if (nextEligibleAt === undefined) {
             throw new LanesError("keep_alive_audit_event_invalid", `Keep-alive resume event has invalid timing fields: ${eventsPath}:${index + 1}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
         }
-        const reason = value.reason === "pending_work" || value.reason === "next_check_at_due" || value.reason === "backoff"
-            ? value.reason
-            : undefined;
+        const reason = typeof value.reason === "string" ? value.reason : undefined;
         events.push({ at, nextEligibleAt, ...(reason === undefined ? {} : { reason }) });
     }
     return events.sort((a, b) => a.at - b.at);
@@ -286,7 +329,18 @@ function laneWasKeepAliveOffAtStop(lane, stoppedAt) {
     const optedInAt = parseTime(lane.keep_alive_opted_in_at);
     return optedInAt === undefined || optedInAt > stoppedAt;
 }
-function firstRestartAfter(lane, stop, nextEnvelopeMs) {
+function firstRestartAfter(lane, stop, nextEnvelopeMs, workerResumeEvents) {
+    const recordedWorkerResume = workerResumeEvents
+        .filter((event) => event.at > stop.mtimeMs && (nextEnvelopeMs === undefined || event.at < nextEnvelopeMs))
+        .sort((a, b) => a.at - b.at)[0];
+    if (recordedWorkerResume !== undefined) {
+        return {
+            at: iso(recordedWorkerResume.at),
+            trigger: recordedWorkerResume.reason,
+            caller: recordedWorkerResume.caller,
+            workerEvent: true,
+        };
+    }
     const restart = (lane.resume_history ?? [])
         .map((entry) => ({ entry, at: parseTime(entry.at) }))
         .filter(({ entry, at }) => at !== undefined && at > stop.mtimeMs && (nextEnvelopeMs === undefined || at < nextEnvelopeMs) && typeof entry.trigger === "string")
@@ -329,6 +383,14 @@ function classifyVerdict(input) {
     if (restart?.trigger === "unknown" && laneWasKeepAliveOffAtStop(lane, input.stoppedAt))
         return "keep_alive_off";
     if (restart) {
+        if (restart.trigger === "pending_work" || restart.trigger === "watcher" || restart.trigger === "monitor_event")
+            return "work_triggered";
+        const workEvidenceEnd = input.nextEnvelopeAt ?? Number.POSITIVE_INFINITY;
+        const triggeredWork = restart.workerEvent !== true && input.resumeEvents
+            .filter((event) => event.at > input.stoppedAt && event.at < workEvidenceEnd && event.at <= (restart.at === null ? Number.POSITIVE_INFINITY : Date.parse(restart.at)))
+            .some((event) => event.reason === "pending_work" || event.reason === "watcher" || event.reason === "monitor_event");
+        if (triggeredWork)
+            return "work_triggered";
         if (restart.at === null)
             return "restarted_untimed";
         const restartAt = Date.parse(restart.at);
@@ -336,12 +398,14 @@ function classifyVerdict(input) {
             return "self_wake";
         if (restart.trigger === "message" || restart.trigger === "answered_questions")
             return "message_wake";
-        if (restart.trigger === "keep_alive") {
+        if (restart.trigger === "keep_alive" || restart.trigger === "next_check_at_due" || restart.trigger === "backoff") {
             const event = input.resumeEvents
                 .filter((candidate) => candidate.at > input.stoppedAt && candidate.at <= restartAt + 2 * 60_000)
                 .sort((left, right) => Math.abs(left.at - restartAt) - Math.abs(right.at - restartAt))[0];
             if (event?.reason === "pending_work")
-                return "message_wake";
+                return "work_triggered";
+            if (event?.reason === "watcher" || event?.reason === "monitor_event")
+                return "work_triggered";
             if (event?.reason === undefined &&
                 (hasDeliveredDropboxEvidence(input.hqRoot, lane.lane_id, input.stoppedAt, restartAt) ||
                     hasMessageResumeEvidence(lane, input.stoppedAt, restartAt) ||
@@ -384,6 +448,7 @@ export function buildKeepAliveAudit(input) {
         try {
             const { allMtimes, stops } = readStopEnvelopes(input.hqRoot, lane.lane_id);
             const keepAliveResumeEvents = readKeepAliveResumeEvents(input.hqRoot, lane.lane_id);
+            const laneWorkerResumeEvents = readLaneWorkerResumeEvents(input.hqRoot, lane.lane_id);
             const doneClassifications = readDoneClassifications(input.hqRoot, lane.lane_id);
             for (const stop of stops) {
                 if (stop.mtimeMs < sinceMs || stop.mtimeMs > nowMs)
@@ -391,7 +456,7 @@ export function buildKeepAliveAudit(input) {
                 if (!doneClassifications.some((at) => at >= stop.mtimeMs && at - stop.mtimeMs <= 10 * 60_000))
                     continue;
                 const nextEnvelopeMs = allMtimes.find((mtime) => mtime > stop.mtimeMs);
-                const restart = firstRestartAfter(lane, stop, nextEnvelopeMs);
+                const restart = firstRestartAfter(lane, stop, nextEnvelopeMs, laneWorkerResumeEvents);
                 const due = dueTime(stop, keepAliveResumeEvents);
                 rows.push({
                     lane: lane.lane_id,
@@ -402,7 +467,7 @@ export function buildKeepAliveAudit(input) {
                     due_at: iso(due.at),
                     due_reason: due.reason,
                     restart,
-                    verdict: classifyVerdict({ dueAt: due.at, stoppedAt: stop.mtimeMs, nextCheckAt: stop.nextCheckAt, restart, lane, nowMs, resumeEvents: keepAliveResumeEvents, hqRoot: input.hqRoot }),
+                    verdict: classifyVerdict({ dueAt: due.at, stoppedAt: stop.mtimeMs, nextCheckAt: stop.nextCheckAt, restart, lane, nowMs, resumeEvents: keepAliveResumeEvents, ...(nextEnvelopeMs === undefined ? {} : { nextEnvelopeAt: nextEnvelopeMs }), hqRoot: input.hqRoot }),
                 });
             }
         }

package/dist/lib/lanes/spawn.js

@@ -56,6 +56,70 @@ const PROVIDER_COMMAND = {
     codex: "codex",
     grok: "grok",
 };
+function keepAliveResumeReason(runDir, pendingResume) {
+    if (pendingResume?.keep_alive !== true || typeof pendingResume.at !== "string")
+        return undefined;
+    const eventsPath = path.join(runDir, "watcher", "events.jsonl");
+    let content;
+    try {
+        content = fs.readFileSync(eventsPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "keep_alive";
+        throw err;
+    }
+    for (const line of content.split(/\r?\n/).reverse()) {
+        if (!line.trim())
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            const event = value;
+            if (event.event === "keep_alive_resume" && event.at === pendingResume.at && typeof event.reason === "string") {
+                return event.reason;
+            }
+        }
+    }
+    return "keep_alive";
+}
+function appendLaneWorkerResumeEvent(input) {
+    const eventsPath = path.join(laneRunDir(input.hqRoot, input.laneId), "watcher", "events.jsonl");
+    fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
+    let separator = "";
+    try {
+        const fd = fs.openSync(eventsPath, "r");
+        try {
+            const size = fs.fstatSync(fd).size;
+            if (size > 0) {
+                const lastByte = Buffer.alloc(1);
+                fs.readSync(fd, lastByte, 0, 1, size - 1);
+                if (lastByte[0] !== 0x0a)
+                    separator = "\n";
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    fs.appendFileSync(eventsPath, `${separator}${JSON.stringify({
+        event: "lane_worker_resumed",
+        lane_id: input.laneId,
+        resumed_at: input.resumedAt,
+        reason: input.reason,
+        ...(input.caller === undefined ? {} : { caller: input.caller }),
+        ...(input.turnId === undefined ? {} : { turn_id: input.turnId }),
+    })}\n`, "utf8");
+}
 export function providerCommandOnPath(command, pathEnv) {
     // Test and embedded callers can intentionally omit PATH and delegate lookup
     // to their spawn implementation. A present PATH is authoritative.
@@ -2081,6 +2145,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             trigger.kind === "resume" || trigger.kind === "message"
             ? "user"
             : undefined);
+    const resumeReason = keepAliveResumeReason(runDir, pendingResume) ?? resumeHistoryTrigger;
     let statusGateHeartbeat;
     try {
         statusGateHeartbeat = managerStatusGateHeartbeat(hqRoot, existing, laneTurnId, nowIso);
@@ -2356,6 +2421,14 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 ...(resumeHistoryCaller ? { caller: resumeHistoryCaller } : {}),
             }),
         }));
+        appendLaneWorkerResumeEvent({
+            hqRoot,
+            laneId: lane.lane_id,
+            resumedAt: nowIso,
+            reason: resumeReason,
+            ...(resumeHistoryCaller === undefined ? {} : { caller: resumeHistoryCaller }),
+            turnId: laneTurnId,
+        });
     }
     return laneLaunchResult(readLane(hqRoot, lane.lane_id));
 }
@@ -2670,6 +2743,12 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
             ...(callerLaneId ? { caller: callerLaneId } : {}),
         }),
     }));
+    appendLaneWorkerResumeEvent({
+        hqRoot,
+        laneId: lane.lane_id,
+        resumedAt: startedAt,
+        reason: "envelope_repair",
+    });
     return workerPid;
 }
 export { PROVIDER_HOME_ENV, PROVIDER_COMMAND };

package/dist/main.js

@@ -41,16 +41,17 @@ import { DEFAULT_COGNITO, isMachineIdentity, loadMachineCachedTokens, } from "./
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
-import { printVersionAndNudge, refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
-import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
+import { printCachedVersionNudge, printVersionAndNudge, refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
+import { enforceVersionGate, isLocalDependencyInstall, resolveRunningInstall, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
 import { emitCliFirstSyncNextStepOutcome, emitCliLimitNoticeEngagement, emitCliLimitNoticeExposure, emitCliInviteNudgeEvent, emitCliSessionStarted, emitPlanLimitInviteTeammateExposure, isCliLimitResourceKind, queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, takeFirstSyncStepOutcomes, takeCliLimitNoticeEngagements, takeCliLimitNoticeExposures, takeCliInviteNudgeEvents, takePlanLimitInviteTeammateExposures, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
+import { isVersionRequest } from "./version-request.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
-import { kickFlagRegistryReadiness } from "./lib/flag-registry.js";
+import { kickFlagRegistryReadiness, waitForFlagRegistryRefresh, } from "./lib/flag-registry.js";
 import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
 import { registerCommandsWithRecovery } from "./startup-registration.js";
 import { releasePackageUseLeaseAfterCommandLoad } from "./utils/package-use-lease.js";
@@ -185,6 +186,8 @@ export async function runCli() {
     // out (after the finally block's telemetry, hence not process.exit here).
     let reexecStatus = null;
     let versionNudgeHandled = false;
+    let versionUpdateHandled = false;
+    let commandParsed = false;
     try {
         runGlobalNetworkLifecycle(process.argv, () => Sentry.addBreadcrumb({
             category: "command",
@@ -209,6 +212,9 @@ export async function runCli() {
                 return "continue";
             const gate = (await foregroundNetworkBudget.waitFor(VERSION_GATE_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => enforceVersionGate(async (decision) => {
                 const outcome = await autoUpdateAndReexec(process.argv, decision.latestVersion);
+                if (outcome.action === "update-failed" || outcome.action === "updated-no-reexec") {
+                    versionUpdateHandled = true;
+                }
                 if (outcome.action === "reexec")
                     reexecStatus = outcome.reexecStatus ?? 0;
                 return outcome.action === "reexec";
@@ -218,6 +224,9 @@ export async function runCli() {
             const cachedLatest = staleAgainstCachedLatest();
             if (cachedLatest) {
                 const outcome = await autoUpdateAndReexec(process.argv, cachedLatest);
+                if (outcome.action === "update-failed" || outcome.action === "updated-no-reexec") {
+                    versionUpdateHandled = true;
+                }
                 if (outcome.action === "reexec") {
                     reexecStatus = outcome.reexecStatus ?? 0;
                     return "reexec";
@@ -264,6 +273,7 @@ export async function runCli() {
         }
         await releasePackageUseLeaseAfterCommandLoad(process.argv);
         await program.parseAsync();
+        commandParsed = true;
         maybeShowFirstSyncNextStep();
     }
     catch (err) {
@@ -287,10 +297,26 @@ export async function runCli() {
             const inviteTeammateExposureFlushes = takePlanLimitInviteTeammateExposures().map((companyUid) => emitPlanLimitInviteTeammateExposure(companyUid, releaseHealthTimeoutMs));
             const limitNoticeExposureFlushes = takeCliLimitNoticeExposures().map((exposure) => emitCliLimitNoticeExposure(exposure, releaseHealthTimeoutMs));
             const limitNoticeEngagementFlushes = takeCliLimitNoticeEngagements().map((engagement) => emitCliLimitNoticeEngagement(engagement, releaseHealthTimeoutMs));
+            const commandArgs = process.argv.slice(2);
+            const canShowCachedVersionNudge = commandParsed &&
+                !versionNudgeHandled &&
+                !versionUpdateHandled &&
+                process.stdout.isTTY === true &&
+                !commandArgs.includes("--json") &&
+                !isVersionRequest(process.argv) &&
+                !shouldSkipGate(process.argv) &&
+                !isLocalDependencyInstall(resolveRunningInstall());
+            const cachedVersionNudge = canShowCachedVersionNudge && staleAgainstCachedLatest() !== null
+                ? (async () => {
+                    await waitForFlagRegistryRefresh(releaseHealthTimeoutMs);
+                    await printCachedVersionNudge(process.stderr);
+                })()
+                : undefined;
             await settleWithin([
                 ...(versionNudgeHandled
                     ? []
                     : [refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs })]),
+                ...(cachedVersionNudge ? [cachedVersionNudge] : []),
                 Sentry.flush(releaseHealthTimeoutMs),
                 ...firstSyncOutcomeFlushes,
                 ...inviteNudgeOutcomeFlushes,

package/dist/utils/package-use-lease.d.ts

@@ -1,3 +1,4 @@
+export declare const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
 export declare class PackageUseUpdatePendingError extends Error {
     constructor(message: string);
 }
@@ -10,11 +11,24 @@ export interface PackageUseLeaseRecord {
     start_time_ms: number;
     hq_version: string;
 }
+export interface PackageUseLeaseHandoff {
+    readonly envValue: string;
+    waitForChild(pid: number, childAlive: () => boolean): Promise<boolean>;
+    cleanup(): void;
+}
 export declare function npmPrefix(root: string, platform?: NodeJS.Platform): string | null;
 export declare function packageUseLeaseDirectory(prefix: string, stateDirectory?: string): string;
 export declare function packageUseUpdateRequestPath(prefix: string, stateDirectory?: string): string;
 declare function waitForUpdateRequest(requestPath: string, timeoutMs: number): void;
 export declare function acquirePackageUseLease(prefix: string, hqVersion: string, stateDirectory?: string): PackageUseLease;
+/**
+ * Create a bounded, per-reexec rendezvous in the current lease directory.
+ * The child confirms readiness only after publishing its own atomic lease.
+ */
+export declare function createPackageUseLeaseHandoff(lease: PackageUseLease, timeoutMs?: number): PackageUseLeaseHandoff;
+export declare function createCurrentPackageUseLeaseHandoff(timeoutMs?: number): PackageUseLeaseHandoff | null;
+/** Publish this process's lease identity to a parent waiting in the same prefix. */
+export declare function publishPackageUseLeaseHandoff(lease: PackageUseLease, env?: NodeJS.ProcessEnv): boolean;
 export declare function acquireCurrentPackageUseLease(): PackageUseLease | null;
 /** Release this process's package-use lease after a long-running command has loaded its package modules. */
 export declare function releaseCurrentPackageUseLease(): void;
@@ -30,6 +44,7 @@ export declare function currentPackageUseUpdatePending(): boolean;
 export declare function currentPackageUseUpdateRequested(): boolean;
 export declare const __test__: {
     waitForUpdateRequest: typeof waitForUpdateRequest;
+    setCurrentPackageUseLease(lease: PackageUseLease | null): void;
 };
 export {};
 //# sourceMappingURL=package-use-lease.d.ts.map

package/dist/utils/package-use-lease.js

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -6,6 +6,8 @@ import { fileURLToPath } from "node:url";
 import { performance } from "node:perf_hooks";
 const CLI_NAME = "@indigoai-us/hq-cli";
 const UPDATE_REQUEST = "update.pending.json";
+export const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
+const HANDOFF_TIMEOUT_MS = 2_000;
 export class PackageUseUpdatePendingError extends Error {
     constructor(message) {
         super(message);
@@ -172,6 +174,93 @@ export function acquirePackageUseLease(prefix, hqVersion, stateDirectory) {
     }
     throw new PackageUseUpdatePendingError("An HQ CLI update is waiting for the package lease; retry when it finishes");
 }
+/**
+ * Create a bounded, per-reexec rendezvous in the current lease directory.
+ * The child confirms readiness only after publishing its own atomic lease.
+ */
+export function createPackageUseLeaseHandoff(lease, timeoutMs = HANDOFF_TIMEOUT_MS) {
+    const directory = path.dirname(lease.leasePath);
+    const markerPath = path.join(directory, `.reexec-${process.pid}-${randomBytes(12).toString("hex")}.handoff`);
+    let cleaned = false;
+    const cleanup = () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        process.removeListener("exit", cleanup);
+        try {
+            rmSync(markerPath, { force: true });
+            rmSync(`${markerPath}.tmp`, { force: true });
+        }
+        catch (error) {
+            process.stderr.write(`hq-cli package-use lease handoff cleanup failed (${errorLabel(error)})\n`);
+        }
+    };
+    process.once("exit", cleanup);
+    return {
+        envValue: markerPath,
+        async waitForChild(pid, childAlive) {
+            const deadline = Date.now() + timeoutMs;
+            while (childAlive() && Date.now() <= deadline) {
+                try {
+                    const marker = JSON.parse(readFileSync(markerPath, "utf8"));
+                    if (marker.pid === pid && Number.isSafeInteger(marker.start_time_ms) && typeof marker.lease_name === "string") {
+                        const leasePath = path.join(directory, marker.lease_name);
+                        if (path.basename(leasePath) === marker.lease_name) {
+                            const record = JSON.parse(readFileSync(leasePath, "utf8"));
+                            if (record.pid === pid && record.start_time_ms === marker.start_time_ms)
+                                return true;
+                        }
+                    }
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) {
+                        process.stderr.write(`hq-cli package-use lease handoff check failed (${errorLabel(error)})\n`);
+                    }
+                }
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+            return false;
+        },
+        cleanup,
+    };
+}
+export function createCurrentPackageUseLeaseHandoff(timeoutMs = HANDOFF_TIMEOUT_MS) {
+    return currentPackageUseLease ? createPackageUseLeaseHandoff(currentPackageUseLease, timeoutMs) : null;
+}
+/** Publish this process's lease identity to a parent waiting in the same prefix. */
+export function publishPackageUseLeaseHandoff(lease, env = process.env) {
+    const markerPath = env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+    if (!markerPath)
+        return false;
+    const directory = path.dirname(lease.leasePath);
+    if (path.dirname(path.resolve(markerPath)) !== path.resolve(directory)) {
+        delete env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+        return false;
+    }
+    const match = /^(\d+)-(\d+)\.json$/.exec(path.basename(lease.leasePath));
+    if (!match || Number(match[1]) !== process.pid) {
+        delete env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+        return false;
+    }
+    const record = {
+        pid: process.pid,
+        start_time_ms: Number(match[2]),
+        lease_name: path.basename(lease.leasePath),
+    };
+    const tempPath = `${markerPath}.tmp`;
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
+        renameSync(tempPath, markerPath);
+        delete env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+        return true;
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        delete env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+        process.stderr.write(`hq-cli package-use lease handoff publish failed (${errorLabel(error)})\n`);
+        return false;
+    }
+}
 function exists(file) {
     try {
         readFileSync(file);
@@ -198,6 +287,7 @@ export function acquireCurrentPackageUseLease() {
     }
     const lease = acquirePackageUseLease(prefix, pkg.version);
     currentPackageUseLease = lease;
+    publishPackageUseLeaseHandoff(lease);
     return lease;
 }
 /** Release this process's package-use lease after a long-running command has loaded its package modules. */
@@ -260,5 +350,8 @@ export function currentPackageUseUpdateRequested() {
 }
 export const __test__ = {
     waitForUpdateRequest,
+    setCurrentPackageUseLease(lease) {
+        currentPackageUseLease = lease;
+    },
 };
 //# sourceMappingURL=package-use-lease.js.map

package/dist/utils/resident-package-preload.d.ts

@@ -1,4 +1,4 @@
-export type ResidentPackagePath = "bot" | "mcp" | "daemon" | "childWrapper" | "coreJobRun";
+export type ResidentPackagePath = "auth-login" | "bot" | "childWrapper" | "coreJobRun" | "login" | "mcp" | "daemon";
 /** Package imports reachable lazily from each resident command's runtime graph. */
 export declare const RESIDENT_PACKAGE_MODULES: Record<ResidentPackagePath, readonly string[]>;
 export declare class ResidentPackagePreloadError extends Error {

package/dist/utils/resident-package-preload.js

@@ -1,5 +1,23 @@
 /** Package imports reachable lazily from each resident command's runtime graph. */
 export const RESIDENT_PACKAGE_MODULES = {
+    login: [
+        "../lib/mesh/api.js",
+        "../lib/work-context/config.js",
+        "../lib/work-context/default-company.js",
+        "../lib/work-context/paths.js",
+        "../lib/plan-limit-nag.js",
+        "../utils/plan-gate-error.js",
+        "../sentry.js",
+        "open",
+    ],
+    "auth-login": [
+        "../lib/auth-login-provider-state.js",
+        "../lib/daemon/mcp-oauth.js",
+        "../lib/plan-limit-nag.js",
+        "../utils/plan-gate-error.js",
+        "../sentry.js",
+        "open",
+    ],
     bot: [
         "../lib/flag-registry.js",
         "../commands/access.js",
@@ -24,6 +42,30 @@ export const RESIDENT_PACKAGE_MODULES = {
     ],
 };
 const LOADERS = {
+    login: [
+        () => import("../lib/mesh/api.js"),
+        () => import("../lib/work-context/config.js"),
+        () => import("../lib/work-context/default-company.js"),
+        () => import("../lib/work-context/paths.js"),
+        () => import("../lib/plan-limit-nag.js"),
+        () => import("../utils/plan-gate-error.js"),
+        async () => {
+            const { preloadSentrySdk } = await import("../sentry.js");
+            preloadSentrySdk();
+        },
+        () => import("open"),
+    ],
+    "auth-login": [
+        () => import("../lib/auth-login-provider-state.js"),
+        () => import("../lib/daemon/mcp-oauth.js"),
+        () => import("../lib/plan-limit-nag.js"),
+        () => import("../utils/plan-gate-error.js"),
+        async () => {
+            const { preloadSentrySdk } = await import("../sentry.js");
+            preloadSentrySdk();
+        },
+        () => import("open"),
+    ],
     bot: [
         () => import("../lib/flag-registry.js"),
         () => import("../commands/access.js"),

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

@@ -56,6 +56,7 @@
  * 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 { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import { type RunningInstall, type UpdateResult } from "./version-gate.js";
 import { type RestartDaemonResult } from "../lib/mesh/live/daemon/install.js";
@@ -145,6 +146,10 @@ export interface SelfUpdateDeps {
     renamePath?: typeof fs.renameSync;
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
+    /** Async process-spawn seam for lease handoff tests. */
+    spawnReexec?: typeof spawn;
+    /** stdin TTY probe for re-exec signal forwarding tests. */
+    stdinIsTTY?: () => boolean;
     acquireLock?: () => (() => void) | null;
     /**
      * Read-your-writes convergence check run after a "successful" install:

package/dist/utils/self-update.js

@@ -56,7 +56,7 @@
  * 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 { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -70,6 +70,7 @@ 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";
+import { createCurrentPackageUseLeaseHandoff, PACKAGE_USE_LEASE_HANDOFF_ENV, releaseCurrentPackageUseLease, } from "./package-use-lease.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.
@@ -596,18 +597,101 @@ export function acquireUpdateLock(now = Date.now()) {
  * 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) {
+async function reexecHq(argv, env, spawnProcess = spawn, stdinIsTTY = () => process.stdin.isTTY === true) {
     const plan = buildSpawnPlan("hq", argv);
-    const result = spawnSync(plan.cmd, plan.args, {
-        stdio: "inherit",
-        shell: plan.shell,
-        env,
-    });
-    if (result.error)
+    const handoff = createCurrentPackageUseLeaseHandoff();
+    const childEnv = handoff
+        ? { ...env, [PACKAGE_USE_LEASE_HANDOFF_ENV]: handoff.envValue }
+        : env;
+    let childForSignals;
+    let childSpawned = false;
+    let childClosed = false;
+    let spawnedChild;
+    const pendingSignals = [];
+    const reexecSignals = process.platform === "win32"
+        ? ["SIGINT", "SIGTERM"]
+        : ["SIGINT", "SIGTERM", "SIGHUP"];
+    const forwardSignal = (signal) => {
+        if (signal === "SIGINT" && stdinIsTTY())
+            return;
+        if (childClosed)
+            return;
+        if (!childForSignals || !childSpawned) {
+            pendingSignals.push(signal);
+            return;
+        }
+        if (childForSignals.exitCode === null && childForSignals.signalCode === null) {
+            childForSignals.kill(signal);
+        }
+    };
+    const signalHandlers = new Map(reexecSignals.map((signal) => [signal, () => forwardSignal(signal)]));
+    for (const [signal, handler] of signalHandlers)
+        process.on(signal, handler);
+    const removeSignalHandlers = () => {
+        for (const [signal, handler] of signalHandlers)
+            process.removeListener(signal, handler);
+    };
+    // spawnSync left default parent signal handling in place, so a parent-only
+    // SIGTERM or SIGHUP could terminate it. Forward stop signals to the async
+    // child while keeping this process waiting for the child's exit status.
+    try {
+        spawnedChild = spawnProcess(plan.cmd, plan.args, {
+            stdio: "inherit",
+            shell: plan.shell,
+            env: childEnv,
+        });
+        childForSignals = spawnedChild;
+    }
+    catch (error) {
+        removeSignalHandlers();
+        handoff?.cleanup();
+        process.stderr.write(`hq-cli re-exec spawn failed (${reexecErrorClass(error)})\n`);
         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;
+    }
+    return new Promise((resolve) => {
+        let alive = true;
+        let spawnFailed = false;
+        spawnedChild.once("error", (error) => {
+            spawnFailed = true;
+            process.stderr.write(`hq-cli re-exec spawn failed (${reexecErrorClass(error)})\n`);
+        });
+        spawnedChild.once("spawn", () => {
+            childSpawned = true;
+            for (const signal of pendingSignals.splice(0)) {
+                if (spawnedChild.exitCode === null && spawnedChild.signalCode === null)
+                    spawnedChild.kill(signal);
+            }
+            if (!handoff || spawnedChild.pid === undefined)
+                return;
+            void handoff.waitForChild(spawnedChild.pid, () => alive).then((matched) => {
+                if (matched && alive) {
+                    releaseCurrentPackageUseLease();
+                    handoff.cleanup();
+                }
+            }).catch((error) => {
+                process.stderr.write(`hq-cli package-use lease handoff wait failed (${error instanceof Error ? error.name : "unknown"})\n`);
+            });
+        });
+        spawnedChild.once("close", (code, _signal) => {
+            alive = false;
+            childClosed = true;
+            pendingSignals.length = 0;
+            removeSignalHandlers();
+            handoff?.cleanup();
+            // The former spawnSync path returned null on spawn failure and 1 for a signal.
+            resolve(spawnFailed ? null : code ?? 1);
+        });
+    });
+}
+function reexecErrorClass(error) {
+    if (error && typeof error === "object") {
+        const code = error.code;
+        if (typeof code === "string" && /^[A-Z0-9_]{1,32}$/.test(code))
+            return code;
+        if (error instanceof Error)
+            return error.name;
+    }
+    return "unknown";
 }
 async function updateAndReexec(argv, flavor, known, deps) {
     const env = deps.env ?? process.env;
@@ -829,7 +913,11 @@ async function updateAndReexec(argv, flavor, known, deps) {
         return { action: "updated", latest };
     }
     const childEnv = { ...env, [REEXEC_GUARD_ENV]: "1" };
-    const status = (deps.reexec ?? reexecHq)([...argv.slice(2)], childEnv);
+    const status = deps.spawnReexec
+        ? await reexecHq([...argv.slice(2)], childEnv, deps.spawnReexec, deps.stdinIsTTY)
+        : deps.reexec
+            ? deps.reexec([...argv.slice(2)], childEnv)
+            : await reexecHq([...argv.slice(2)], childEnv, spawn, deps.stdinIsTTY);
     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}.`));

package/dist/utils/version-gate.js

@@ -37,6 +37,7 @@ import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import semver from "semver";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
+import { isVersionRequest } from "../version-request.js";
 import { Sentry } from "../sentry.js";
 import { isCliTelemetryDisabled } from "./cli-telemetry.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
@@ -315,11 +316,6 @@ export function isLocalDependencyPackageDir(pkgDir, platform = process.platform)
     // `<dir>/lib/node_modules` while the `.bin` shim keeps resolving
     // `<dir>/node_modules`.
     //
-    // Windows is the exception and must keep the old behaviour: its global
-    // layout is `<prefix>\node_modules` with no `lib` segment, so the same test
-    // would misread a genuine global install as local.
-    if (platform === "win32")
-        return false;
     const segments = pkgDir
         .replace(/\\/g, "/")
         .replace(/\/+$/, "")
@@ -328,6 +324,23 @@ export function isLocalDependencyPackageDir(pkgDir, platform = process.platform)
     const nodeModulesIndex = segments.lastIndexOf("node_modules");
     if (nodeModulesIndex <= 0)
         return false;
+    if (platform === "win32") {
+        const prefix = segments.slice(0, nodeModulesIndex).join("/");
+        const normalize = (value) => value.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+        const configuredPrefix = process.env.npm_config_prefix ?? process.env.NPM_CONFIG_PREFIX;
+        if (configuredPrefix && normalize(configuredPrefix) === normalize(prefix))
+            return false;
+        const appData = process.env.APPDATA;
+        const defaultPrefix = appData
+            ? path.join(appData, "npm")
+            : path.join(os.homedir(), "AppData", "Roaming", "npm");
+        if (normalize(defaultPrefix) === normalize(prefix))
+            return false;
+        const pathEntries = (process.env.PATH ?? "").split(";");
+        if (pathEntries.some((entry) => normalize(entry) === normalize(prefix)))
+            return false;
+        return true;
+    }
     return segments[nodeModulesIndex - 1] !== "lib";
 }
 export function isLocalDependencyInstall(install, platform = process.platform) {
@@ -1588,12 +1601,11 @@ export async function enforceVersionGate(onUpdateRecommended, options = {}) {
  * force-upgraded.
  */
 export function shouldSkipGate(argv) {
-    return argv.some((a) => a === "--version" ||
+    return isVersionRequest(argv) || argv.some((a) => a === "--version" ||
         a === "-V" ||
         a === "-v" ||
         a === "--help" ||
-        a === "-h" ||
-        a === "version");
+        a === "-h");
 }
 export const __test__ = {
     CLIENT_ID,

package/package.json

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