@indigoai-us/hq-cli 5.342.3 → 5.342.4

package/CHANGELOG.md

@@ -2,7 +2,12 @@
 
 ## [Unreleased]
 
+## [5.342.4] — 2026-10-04
+
 ## [5.342.3] — 2026-10-04
+
+- Release package-use leases after daemon, bot, and mesh-daemon modules load; `hq mcp serve` starts its resident preload only after the first reply is written, so resident CLI processes do not block Desktop updates or slow MCP start-up.
+
 - `hq secrets env` now waits briefly for the company flag snapshot refresh before its synchronous exit, allowing the fast-path gate to use a persisted snapshot on later invocations.
 
 ## [5.342.2] — 2026-10-04

package/dist/commands/bot.js

@@ -26,6 +26,8 @@ import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hol
  * list (online flag), and rm. Secrets are never printed.
  */
 import { promoteLocalBot } from "../lib/bot/promote.js";
+import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload } from "../utils/package-use-lease.js";
+import { preloadResidentPackageModules, reportResidentPackagePreloadFailure } from "../utils/resident-package-preload.js";
 import { CLI_UPDATE_DISABLE_ENV, createCliUpdateWatcher, handOffToUpdatedCli } from "../lib/bot/cli-update.js";
 import { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
 import { addBotToCompanies, describeCompanyFailures, removeBotFromCompanies } from "./bot-companies.js";
@@ -854,6 +856,7 @@ export async function runBotWorkers(opts) {
 }
 // ── run (resident) ───────────────────────────────────────────────────────────
 async function runBotResident(nameArg) {
+    await releasePackageUseLeaseAfterResidentPreload(() => preloadResidentPackageModules("bot"), reportResidentPackagePreloadFailure, releaseCurrentPackageUseLease);
     const name = validateBotName(nameArg);
     const dir = botDir(name);
     const config = readBotConfig(dir);

package/dist/commands/daemon.d.ts

@@ -18,6 +18,9 @@ import { type LegacyUnit } from "../lib/daemon/legacy.js";
 import type { HostApp } from "../lib/daemon/supervisor.js";
 import { type SyncModeVaultClient } from "./sync-mode.js";
 import type { RunCommand } from "../lib/service-manager/launchd.js";
+type DaemonRunnerModule = typeof import("../lib/daemon/run.js");
+/** Load the daemon runtime without releasing its lease: it reads package files while resident. */
+export declare function loadDaemonRunner(_release?: () => void, load?: () => Promise<DaemonRunnerModule>): Promise<DaemonRunnerModule["runDaemon"]>;
 export interface DaemonCommandDeps {
     env: NodeJS.ProcessEnv;
     home: string;
@@ -62,4 +65,5 @@ export declare function resolveDaemonHqRoot(flag: string | undefined, where: {
     home: string;
 }): string | undefined;
 export declare function registerDaemonCommand(program: Command, over?: Partial<DaemonCommandDeps>): Command;
+export {};
 //# sourceMappingURL=daemon.d.ts.map

package/dist/commands/daemon.js

@@ -35,6 +35,11 @@ import { requireAnywhereRuntime } from "./anywhere-runtime-flag.js";
 import { hqdRequest, hqdSocketPath, HqdClientError } from "../lib/daemon/protocol.js";
 import { parseStdinMachineCredentials } from "../lib/daemon/machine-login.js";
 import { resolveDefaultHqRoot } from "../utils/cognito-session.js";
+/** Load the daemon runtime without releasing its lease: it reads package files while resident. */
+export async function loadDaemonRunner(_release = () => undefined, load = () => import("../lib/daemon/run.js")) {
+    const { runDaemon } = await load();
+    return runDaemon;
+}
 class DaemonCommandError extends Error {
 }
 /**
@@ -778,7 +783,7 @@ export function registerDaemonCommand(program, over = {}) {
         .option("--host <app>", "Run as a child of this app (only \"desktop\"), which has handed sync over to the daemon")
         .action(wrap(async (d, opts) => {
         const host = parseDaemonHost(opts.host);
-        const { runDaemon } = await import("../lib/daemon/run.js");
+        const runDaemon = await loadDaemonRunner();
         // Services inherit this environment, so they see the same folder.
         const env = opts.daemonDir ? { ...d.env, HQ_DAEMON_DIR: opts.daemonDir } : d.env;
         process.exitCode = await runDaemon({

package/dist/commands/mcp-serve.d.ts

@@ -20,9 +20,21 @@ export interface McpServeOptions {
     cwd?: string;
     /** Per-call hqd budget. Default 120s; policy checks and hq-mcp tools can be slow. */
     timeoutMs?: number;
+    /** Test seam for the resident module preload; production uses the default loader. */
+    preloadResidentModules?: (residentPath: "mcp", modules: readonly string[]) => Promise<void>;
+    /** Test seam for releasing the process package lease after resident preload. */
+    releasePackageUseLease?: () => void;
 }
 /** HQ root for prompts: HQ_ROOT, else the ~/.hq/root pointer written by `hq install --global`. */
 export declare function readHqRoot(env: NodeJS.ProcessEnv, home: string): string | null;
+type McpToolsModule = typeof import("../lib/mcp/tools.js");
+type McpPromptsModule = typeof import("../lib/mcp/prompts.js");
+/** Load request handlers required to answer MCP requests. */
+export declare function loadMcpPackageHandlers(loadTools?: () => Promise<McpToolsModule>, loadPrompts?: () => Promise<McpPromptsModule>): Promise<{
+    tools: McpToolsModule;
+    prompts: McpPromptsModule;
+}>;
 /** Run the server until input ends. Resolves when stdin closes. */
 export declare function runMcpServe(opts?: McpServeOptions): Promise<void>;
+export {};
 //# sourceMappingURL=mcp-serve.d.ts.map

package/dist/commands/mcp-serve.js

@@ -18,6 +18,8 @@ import { CLI_VERSION } from "../cli-version.js";
 import { HQ_ANYWHERE_RUNTIME_FLAG } from "../lib/anywhere-runtime-flag-key.js";
 import { anywhereRuntimeEnabledFromSnapshot } from "../lib/anywhere-runtime-fast-flag.js";
 import { createLineSplitter, HqdClientError, hqdRequest, hqdSocketPath } from "../lib/daemon/protocol.js";
+import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload } from "../utils/package-use-lease.js";
+import { preloadResidentPackageModules, reportResidentPackagePreloadFailure, RESIDENT_PACKAGE_MODULES } from "../utils/resident-package-preload.js";
 export const MCP_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 const UNREACHABLE_CODES = new Set(["ENOENT", "ECONNREFUSED", "ECONNRESET", "EPIPE", "ETIMEDOUT", "ESOCKET", "EACCES"]);
 /** HQ root for prompts: HQ_ROOT, else the ~/.hq/root pointer written by `hq install --global`. */
@@ -39,8 +41,12 @@ function toolError(code, message) {
     const error = { code, message };
     return { content: [{ type: "text", text: JSON.stringify({ error }, null, 2) }], structuredContent: { error }, isError: true };
 }
+/** Load request handlers required to answer MCP requests. */
+export async function loadMcpPackageHandlers(loadTools = () => import("../lib/mcp/tools.js"), loadPrompts = () => import("../lib/mcp/prompts.js")) {
+    return Promise.all([loadTools(), loadPrompts()]).then(([tools, prompts]) => ({ tools, prompts }));
+}
 /** Run the server until input ends. Resolves when stdin closes. */
-export function runMcpServe(opts = {}) {
+export async function runMcpServe(opts = {}) {
     const input = opts.input ?? process.stdin;
     const output = opts.output ?? process.stdout;
     const env = opts.env ?? process.env;
@@ -51,15 +57,33 @@ export function runMcpServe(opts = {}) {
     if (!anywhereRuntimeEnabledFromSnapshot(env)) {
         process.stderr.write(`HQ Anywhere is not enabled. Enable the ${HQ_ANYWHERE_RUNTIME_FLAG} flag to use hq mcp serve.\n`);
         process.exitCode = 1;
-        return Promise.resolve();
+        return;
     }
-    const send = (msg) => output.write(`${JSON.stringify({ jsonrpc: "2.0", ...msg })}\n`);
+    const { tools, prompts } = await loadMcpPackageHandlers();
+    const preload = (residentPath, modules) => opts.preloadResidentModules
+        ? opts.preloadResidentModules(residentPath, modules)
+        : preloadResidentPackageModules(residentPath);
+    let residentPreloadStarted = false;
+    const startResidentPreload = () => {
+        if (residentPreloadStarted)
+            return;
+        residentPreloadStarted = true;
+        void releasePackageUseLeaseAfterResidentPreload(() => preload("mcp", RESIDENT_PACKAGE_MODULES.mcp), reportResidentPackagePreloadFailure, opts.releasePackageUseLease ?? releaseCurrentPackageUseLease).catch(() => {
+            process.exitCode = process.exitCode ?? 1;
+            process.emitWarning("hq-cli resident package preload completion failed (class=Error, module=unknown)");
+        });
+    };
+    const send = (msg) => {
+        const response = `${JSON.stringify({ jsonrpc: "2.0", ...msg })}\n`;
+        if (residentPreloadStarted)
+            return output.write(response);
+        return output.write(response, startResidentPreload);
+    };
     const reply = (id, result) => send({ id, result });
     const replyError = (id, code, message) => send({ id, error: { code, message } });
     const callTool = async (params) => {
-        const { MCP_TOOLS } = await import("../lib/mcp/tools.js");
         const name = params.name;
-        if (typeof name !== "string" || !MCP_TOOLS.some((t) => t.name === name)) {
+        if (typeof name !== "string" || !tools.MCP_TOOLS.some((t) => t.name === name)) {
             return toolError("unknown_tool", `unknown tool ${String(name)}`);
         }
         const args = params.arguments && typeof params.arguments === "object" ? params.arguments : {};
@@ -95,22 +119,21 @@ export function runMcpServe(opts = {}) {
                 reply(id, {});
                 return;
             case "tools/list":
-                reply(id, { tools: (await import("../lib/mcp/tools.js")).MCP_TOOLS });
+                reply(id, { tools: tools.MCP_TOOLS });
                 return;
             case "tools/call":
                 reply(id, await callTool(params));
                 return;
             case "prompts/list":
-                reply(id, { prompts: (await import("../lib/mcp/prompts.js")).MCP_PROMPTS });
+                reply(id, { prompts: prompts.MCP_PROMPTS });
                 return;
             case "prompts/get": {
-                const { getPrompt, PromptNotFoundError } = await import("../lib/mcp/prompts.js");
                 const args = params.arguments && typeof params.arguments === "object" ? params.arguments : {};
                 try {
-                    reply(id, getPrompt(String(params.name), args, readHqRoot(env, home)));
+                    reply(id, prompts.getPrompt(String(params.name), args, readHqRoot(env, home)));
                 }
                 catch (err) {
-                    if (!(err instanceof PromptNotFoundError))
+                    if (!(err instanceof prompts.PromptNotFoundError))
                         throw err;
                     replyError(id, -32602, err.message);
                 }

package/dist/main.js

@@ -53,6 +53,7 @@ import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 import { kickFlagRegistryReadiness } 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";
 import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTreeTornError, } from "./utils/install-tree-torn.js";
 import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
@@ -261,6 +262,7 @@ export async function runCli() {
             reexecStatus = registration.reexecStatus;
             return;
         }
+        await releasePackageUseLeaseAfterCommandLoad(process.argv);
         await program.parseAsync();
         maybeShowFirstSyncNextStep();
     }

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

@@ -16,6 +16,12 @@ export declare function packageUseUpdateRequestPath(prefix: string, stateDirecto
 declare function waitForUpdateRequest(requestPath: string, timeoutMs: number): void;
 export declare function acquirePackageUseLease(prefix: string, hqVersion: string, stateDirectory?: string): PackageUseLease;
 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;
+/** The lease remains held through command execution and is released on process exit. */
+export declare function releasePackageUseLeaseAfterCommandLoad(_argv?: readonly string[], _release?: () => void): void;
+/** Release only after a command-specific preload succeeds; failures are reported and keep the lease. */
+export declare function releasePackageUseLeaseAfterResidentPreload(preload: () => Promise<void>, reportFailure: (error: unknown) => void, release?: () => void): Promise<void>;
 /** True only when a valid update request belongs to a live updater process. */
 export declare function packageUseUpdatePending(prefix: string, stateDirectory?: string): boolean;
 /** True while the desktop updater owns the per-prefix update request. */

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

@@ -12,6 +12,7 @@ export class PackageUseUpdatePendingError extends Error {
         this.name = "PackageUseUpdatePendingError";
     }
 }
+let currentPackageUseLease = null;
 function errorLabel(error) {
     if (error && typeof error === "object") {
         const value = error;
@@ -195,7 +196,29 @@ export function acquireCurrentPackageUseLease() {
         if (nodeModules > 0 && parts[nodeModules - 1] !== "lib")
             return null;
     }
-    return acquirePackageUseLease(prefix, pkg.version);
+    const lease = acquirePackageUseLease(prefix, pkg.version);
+    currentPackageUseLease = lease;
+    return lease;
+}
+/** Release this process's package-use lease after a long-running command has loaded its package modules. */
+export function releaseCurrentPackageUseLease() {
+    currentPackageUseLease?.release();
+    currentPackageUseLease = null;
+}
+/** The lease remains held through command execution and is released on process exit. */
+export function releasePackageUseLeaseAfterCommandLoad(_argv = process.argv, _release = releaseCurrentPackageUseLease) {
+    // The package-use lease's process-exit listener owns its normal release.
+}
+/** Release only after a command-specific preload succeeds; failures are reported and keep the lease. */
+export async function releasePackageUseLeaseAfterResidentPreload(preload, reportFailure, release = releaseCurrentPackageUseLease) {
+    try {
+        await preload();
+    }
+    catch (error) {
+        reportFailure(error);
+        return;
+    }
+    release();
 }
 /** True only when a valid update request belongs to a live updater process. */
 export function packageUseUpdatePending(prefix, stateDirectory) {

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

@@ -0,0 +1,13 @@
+export type ResidentPackagePath = "bot" | "mcp";
+/** 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 {
+    readonly moduleSpecifier: string;
+    readonly errorClass: string;
+    constructor(moduleSpecifier: string, errorClass: string);
+}
+/** Report only bounded runtime metadata; never include an exception message or path. */
+export declare function reportResidentPackagePreloadFailure(error: unknown): void;
+/** Resolve every lazy package module before a resident command releases its lease. */
+export declare function preloadResidentPackageModules(residentPath: ResidentPackagePath, load?: () => Promise<unknown>): Promise<void>;
+//# sourceMappingURL=resident-package-preload.d.ts.map

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

@@ -0,0 +1,78 @@
+/** Package imports reachable lazily from each resident command's runtime graph. */
+export const RESIDENT_PACKAGE_MODULES = {
+    bot: ["../lib/flag-registry.js", "../commands/access.js", "../sentry.js", "open"],
+    mcp: [
+        "../lib/mcp/tools.js",
+        "../lib/mcp/prompts.js",
+        "../utils/cognito-session.js",
+        "../lib/daemon/mcp-oauth.js",
+        "../commands/access.js",
+        "../lib/flag-registry.js",
+        "@modelcontextprotocol/sdk/client/index.js",
+        "@modelcontextprotocol/sdk/client/streamableHttp.js",
+        "../sentry.js",
+        "open",
+        "./staged-npm-install.js",
+    ],
+};
+const LOADERS = {
+    bot: [
+        () => import("../lib/flag-registry.js"),
+        () => import("../commands/access.js"),
+        () => import("../sentry.js"),
+        () => import("open"),
+    ],
+    mcp: [
+        () => import("../lib/mcp/tools.js"),
+        () => import("../lib/mcp/prompts.js"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/daemon/mcp-oauth.js"),
+        () => import("../commands/access.js"),
+        () => import("../lib/flag-registry.js"),
+        () => import("@modelcontextprotocol/sdk/client/index.js"),
+        () => import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+        () => import("../sentry.js"),
+        () => import("open"),
+        () => import("./staged-npm-install.js"),
+    ],
+};
+export class ResidentPackagePreloadError extends Error {
+    moduleSpecifier;
+    errorClass;
+    constructor(moduleSpecifier, errorClass) {
+        super("Resident package module preload failed");
+        this.moduleSpecifier = moduleSpecifier;
+        this.errorClass = errorClass;
+        this.name = "ResidentPackagePreloadError";
+    }
+}
+function boundedErrorClass(error) {
+    const value = error && typeof error === "object"
+        ? error
+        : {};
+    const label = typeof value.code === "string" ? value.code : typeof value.name === "string" ? value.name : "Error";
+    return /^[A-Za-z][A-Za-z0-9_]{0,39}$/.test(label) ? label : "Error";
+}
+/** Report only bounded runtime metadata; never include an exception message or path. */
+export function reportResidentPackagePreloadFailure(error) {
+    const failure = error instanceof ResidentPackagePreloadError
+        ? error
+        : new ResidentPackagePreloadError("unknown", boundedErrorClass(error));
+    process.stderr.write(`hq-cli resident package preload failed (class=${failure.errorClass}, module=${failure.moduleSpecifier})\n`);
+}
+/** Resolve every lazy package module before a resident command releases its lease. */
+export async function preloadResidentPackageModules(residentPath, load) {
+    if (load) {
+        await load();
+        return;
+    }
+    await Promise.all(LOADERS[residentPath].map(async (loader, index) => {
+        try {
+            await loader();
+        }
+        catch (error) {
+            throw new ResidentPackagePreloadError(RESIDENT_PACKAGE_MODULES[residentPath][index] ?? "unknown", boundedErrorClass(error));
+        }
+    }));
+}
+//# sourceMappingURL=resident-package-preload.js.map

package/package.json

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