@indigoai-us/hq-cli 5.108.7 → 5.108.9

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.108.9] — 2026-09-05
+
+## [5.108.8] — 2026-09-05
+
 ## [5.108.7] — 2026-09-05
 
 ### Fixed

package/dist/lazy-commands.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Hot-command manifest for the entrypoint's lazy registration.
+ *
+ * main.ts used to import the entire ~60-module command graph at module scope,
+ * so every invocation paid for every command. That is fine for a human typing
+ * one command and ruinous for the calls automation makes in a loop: the
+ * hq-sentry agent fleet on an outpost runs `hq secrets` about 39 times a minute
+ * (each worker resolves credentials before every external command it executes),
+ * and each of those processes spent ~0.75 CPU-seconds importing commands it
+ * never ran — around half a core, continuously. Measured on Outpost 2
+ * (i-09424eff61920a4ac) 2026-09-05; see register-all.ts for the numbers.
+ *
+ * A command listed here registers ITSELF and nothing else. Anything not listed
+ * — `--help`, a bare `hq`, an unknown command, every other command — falls back
+ * to `registerAllCommands`, the complete unchanged graph. That fallback is what
+ * makes this safe to extend one command at a time: an entry is a performance
+ * opt-in, never a behaviour change, and a command that is absent here is simply
+ * as fast as it was before.
+ *
+ * This mirrors commands/scaffold-fast.ts, which does the same thing for the
+ * relocated `hq core …` scripts, and carries the same anti-drift discipline: a
+ * parity test registers each entry BOTH ways and asserts the resulting command
+ * shape is identical, so a manifest entry cannot silently diverge from the real
+ * registration.
+ *
+ * TO ADD A COMMAND: it must register exactly one top-level command, be
+ * registered onto `program` (not onto a subcommand group), and have no other
+ * module contributing subcommands to it. The parity test enforces the shape;
+ * these three conditions are what make the entry correct in the first place.
+ */
+import type { Command } from "commander";
+export type LazyCommand = {
+    /** The top-level token this matches — `hq <name> …`. */
+    name: string;
+    /** Registers this one command onto `program`, importing only its module. */
+    register: (program: Command) => Promise<void>;
+};
+/**
+ * The hot paths, in descending order of how often automation calls them.
+ *
+ * `secrets` and `run` are the two commands HQ's own tooling puts on the inner
+ * loop: every fleet worker shells through one of them before each external
+ * command, which is exactly the shape that makes eager import expensive.
+ */
+export declare const LAZY_COMMANDS: readonly LazyCommand[];
+/**
+ * Resolve `process.argv` to a manifest entry, or null to use the full graph.
+ *
+ * argv is `[node, hq, <name>, ...rest]`. `hq` declares no program-level options
+ * before the command name, so argv[2] is the command token when there is one;
+ * `--help`, `--version`, and a bare `hq` all fail the lookup and take the
+ * fallback, which is the intended behaviour — help must list every command.
+ */
+export declare function findLazyCommand(argv: readonly string[]): LazyCommand | null;
+//# sourceMappingURL=lazy-commands.d.ts.map

package/dist/lazy-commands.js

@@ -0,0 +1,68 @@
+/**
+ * Hot-command manifest for the entrypoint's lazy registration.
+ *
+ * main.ts used to import the entire ~60-module command graph at module scope,
+ * so every invocation paid for every command. That is fine for a human typing
+ * one command and ruinous for the calls automation makes in a loop: the
+ * hq-sentry agent fleet on an outpost runs `hq secrets` about 39 times a minute
+ * (each worker resolves credentials before every external command it executes),
+ * and each of those processes spent ~0.75 CPU-seconds importing commands it
+ * never ran — around half a core, continuously. Measured on Outpost 2
+ * (i-09424eff61920a4ac) 2026-09-05; see register-all.ts for the numbers.
+ *
+ * A command listed here registers ITSELF and nothing else. Anything not listed
+ * — `--help`, a bare `hq`, an unknown command, every other command — falls back
+ * to `registerAllCommands`, the complete unchanged graph. That fallback is what
+ * makes this safe to extend one command at a time: an entry is a performance
+ * opt-in, never a behaviour change, and a command that is absent here is simply
+ * as fast as it was before.
+ *
+ * This mirrors commands/scaffold-fast.ts, which does the same thing for the
+ * relocated `hq core …` scripts, and carries the same anti-drift discipline: a
+ * parity test registers each entry BOTH ways and asserts the resulting command
+ * shape is identical, so a manifest entry cannot silently diverge from the real
+ * registration.
+ *
+ * TO ADD A COMMAND: it must register exactly one top-level command, be
+ * registered onto `program` (not onto a subcommand group), and have no other
+ * module contributing subcommands to it. The parity test enforces the shape;
+ * these three conditions are what make the entry correct in the first place.
+ */
+/**
+ * The hot paths, in descending order of how often automation calls them.
+ *
+ * `secrets` and `run` are the two commands HQ's own tooling puts on the inner
+ * loop: every fleet worker shells through one of them before each external
+ * command, which is exactly the shape that makes eager import expensive.
+ */
+export const LAZY_COMMANDS = [
+    {
+        name: "secrets",
+        register: async (program) => {
+            const { registerSecretsCommand } = await import("./commands/secrets.js");
+            registerSecretsCommand(program);
+        },
+    },
+    {
+        name: "run",
+        register: async (program) => {
+            const { registerRunCommand } = await import("./commands/run.js");
+            registerRunCommand(program);
+        },
+    },
+];
+/**
+ * Resolve `process.argv` to a manifest entry, or null to use the full graph.
+ *
+ * argv is `[node, hq, <name>, ...rest]`. `hq` declares no program-level options
+ * before the command name, so argv[2] is the command token when there is one;
+ * `--help`, `--version`, and a bare `hq` all fail the lookup and take the
+ * fallback, which is the intended behaviour — help must list every command.
+ */
+export function findLazyCommand(argv) {
+    const name = argv[2];
+    if (typeof name !== "string")
+        return null;
+    return LAZY_COMMANDS.find((candidate) => candidate.name === name) ?? null;
+}
+//# sourceMappingURL=lazy-commands.js.map

package/dist/lib/mesh/live/daemon/index.d.ts

@@ -5,7 +5,7 @@ export { CREDENTIAL_RENEWAL_FRACTION, DEFAULT_REFUSED_RETRY_MS, MAX_RETRY_DELAY_
 export type { BoundedTimeoutHandle, Contract3Bundle, CredentialRenewalErrorInfo, CredentialVendFailureKind, CredentialVendPostResult, CredentialsFetcher, PresenceCompany, TimerHost, } from "./credentials.js";
 export { amzDateOf, hex, presignIotWssUrl, rfc3986Encode } from "./presign.js";
 export type { IotCredentials } from "./presign.js";
-export { PresenceClient, backoffDelayMs, buildPresencePayload, defaultMqttConnect, isOwnPresenceTopic, } from "./presence.js";
+export { CLOSE_LOG_ALWAYS_COUNT, CLOSE_LOG_INTERVAL_MS, CONNECT_STABLE_GRACE_MS, PresenceClient, backoffDelayMs, buildPresencePayload, defaultMqttConnect, isOwnPresenceTopic, } from "./presence.js";
 export type { MeshMqttClientLike, MqttConnectFn, MqttConnectionState, PresenceClientOptions, PresencePayload, PresenceRefusal, } from "./presence.js";
 export { defaultDaemonState, patchDaemonState, readDaemonState, writeDaemonState, } from "./state.js";
 export type { DaemonStateFile, PresenceRefusalState } from "./state.js";

package/dist/lib/mesh/live/daemon/index.js

@@ -2,7 +2,7 @@ export { DAEMON_DIRNAME, DAEMON_LOG_MAX_BYTES, DAEMON_LOG_NAME, DAEMON_PID_NAME,
 export { acquirePidLock, defaultPidLockDeps, parsePidLock, pidLockStatus, readPidLock, releasePidLock, resolveDaemonDir, } from "./pid-lock.js";
 export { CREDENTIAL_RENEWAL_FRACTION, DEFAULT_REFUSED_RETRY_MS, MAX_RETRY_DELAY_MS, MAX_TIMER_DELAY_MS, MQTT_KEEPALIVE_SECONDS, REALTIME_CREDENTIALS_PATH, REFUSED_RETRY_ENV, CredentialRenewalManager, CredentialVendError, classifyCredentialVendFailure, clampRetryDelayMs, createContract3Fetcher, defaultRefusedRetryMs, extractVendErrorCode, isCredentialVendRefused, normalizeContract3Bundle, parseRetryAfterMs, realTimerHost, refusedRetryDelayMs, renewalDelayMs, scheduleBoundedTimeout, } from "./credentials.js";
 export { amzDateOf, hex, presignIotWssUrl, rfc3986Encode } from "./presign.js";
-export { PresenceClient, backoffDelayMs, buildPresencePayload, defaultMqttConnect, isOwnPresenceTopic, } from "./presence.js";
+export { CLOSE_LOG_ALWAYS_COUNT, CLOSE_LOG_INTERVAL_MS, CONNECT_STABLE_GRACE_MS, PresenceClient, backoffDelayMs, buildPresencePayload, defaultMqttConnect, isOwnPresenceTopic, } from "./presence.js";
 export { defaultDaemonState, patchDaemonState, readDaemonState, writeDaemonState, } from "./state.js";
 export { appendDaemonLog, daemonLogLine, ensureDaemonLog, resolveDaemonAssetDir, rotateDaemonLogIfNeeded, } from "./log.js";
 export { BOARD_REFRESH_INTERVAL_MS, createVaultBoardReader, formatBoardMarkdown, refreshBoundSessionBoards, writeBoardMarkdown, } from "./board-refresh.js";

package/dist/lib/mesh/live/daemon/presence.d.ts

@@ -7,11 +7,22 @@
  * - Offline is server-only (IoT lifecycle → PresenceIngestFunction)
  * - Never subscribes to thread topics
  * - Reconnects with monotonic full-jitter backoff 1s–60s on close / network
+ * - Backoff resets only after the connection stays up past
+ *   {@link CONNECT_STABLE_GRACE_MS} (broker accept-then-close must not reset)
  * - Server credential refusals use a long retry (default 10m ±20%)
  */
 import { type IClientOptions, type MqttClient } from "mqtt";
 import { type Contract3Bundle, type CredentialsFetcher, type TimerHost } from "./credentials.js";
 export type MqttConnectionState = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
+/**
+ * A connection that drops before this grace window after `connect` is treated
+ * as a failed attempt: backoff counters are not reset (AWS IoT often accepts
+ * then closes immediately after a denied publish).
+ */
+export declare const CONNECT_STABLE_GRACE_MS = 5000;
+/** Always emit the first N close info lines, then at most one per interval. */
+export declare const CLOSE_LOG_ALWAYS_COUNT = 3;
+export declare const CLOSE_LOG_INTERVAL_MS = 60000;
 export interface PresencePayload {
     v: 1;
     status: "online" | "offline";
@@ -49,6 +60,8 @@ export interface PresenceClientOptions {
     onOnline?: (companies: string[]) => void;
     onState?: (state: MqttConnectionState) => void;
     onError?: (err: unknown) => void;
+    /** Non-error info lines (e.g. rate-limited mqtt close / backoff). */
+    onInfo?: (message: string) => void;
     /** Fired when refusal appears, code changes, clears, or nextRetryAt updates. */
     onRefusal?: (refusal: PresenceRefusal | null) => void;
     now?: () => Date;
@@ -78,6 +91,10 @@ export declare class PresenceClient {
     private attempt;
     private lastBackoffMs;
     private reconnectHandle;
+    private stableHandle;
+    private connectedAtMs;
+    private closeLogCount;
+    private lastCloseLogAtMs;
     private stopped;
     private generation;
     private publishedTopics;
@@ -118,7 +135,9 @@ export declare class PresenceClient {
     /** Publish retained online to every own presence topic (connect / renew). */
     private publishAll;
     private scheduleReconnect;
+    private maybeLogClose;
     private clearReconnect;
+    private clearStableTimer;
 }
 /** Production mqtt.connect wrapper (typed). */
 export declare function defaultMqttConnect(url: string, opts: IClientOptions): MqttClient;

package/dist/lib/mesh/live/daemon/presence.js

@@ -7,11 +7,22 @@
  * - Offline is server-only (IoT lifecycle → PresenceIngestFunction)
  * - Never subscribes to thread topics
  * - Reconnects with monotonic full-jitter backoff 1s–60s on close / network
+ * - Backoff resets only after the connection stays up past
+ *   {@link CONNECT_STABLE_GRACE_MS} (broker accept-then-close must not reset)
  * - Server credential refusals use a long retry (default 10m ±20%)
  */
 import mqtt from "mqtt";
 import { CredentialVendError, CredentialRenewalManager, MQTT_KEEPALIVE_SECONDS, clampRetryDelayMs, defaultRefusedRetryMs, realTimerHost, refusedRetryDelayMs, scheduleBoundedTimeout, } from "./credentials.js";
 import { presignIotWssUrl } from "./presign.js";
+/**
+ * A connection that drops before this grace window after `connect` is treated
+ * as a failed attempt: backoff counters are not reset (AWS IoT often accepts
+ * then closes immediately after a denied publish).
+ */
+export const CONNECT_STABLE_GRACE_MS = 5_000;
+/** Always emit the first N close info lines, then at most one per interval. */
+export const CLOSE_LOG_ALWAYS_COUNT = 3;
+export const CLOSE_LOG_INTERVAL_MS = 60_000;
 /**
  * Full-jitter capped exponential backoff (1s base → 60s cap by default),
  * floored at `previousMs` so consecutive failures never shrink the delay.
@@ -50,6 +61,10 @@ export class PresenceClient {
     attempt = 0;
     lastBackoffMs = 0;
     reconnectHandle = null;
+    stableHandle = null;
+    connectedAtMs = null;
+    closeLogCount = 0;
+    lastCloseLogAtMs = Number.NEGATIVE_INFINITY;
     stopped = false;
     generation = 0;
     publishedTopics = [];
@@ -113,6 +128,8 @@ export class PresenceClient {
         this.generation += 1;
         this.renewal.stop();
         this.clearReconnect();
+        this.clearStableTimer();
+        this.connectedAtMs = null;
         this.teardownClient(false);
         this.clearRefusal(/* logClear */ false);
         this.setState("closed");
@@ -128,7 +145,7 @@ export class PresenceClient {
                 return;
             }
         }
-        // Backoff counters reset only on MQTT connect — not here.
+        // Backoff counters reset only after a stable connection — not here.
         this.clearReconnect();
         void this.connectOnce();
     }
@@ -155,7 +172,7 @@ export class PresenceClient {
         this.clearRefusal(true);
         if (this.stopped)
             return;
-        // Reconnect with the new presigned URL; backoff resets only on MQTT connect.
+        // Reconnect with the new presigned URL; backoff resets only after stable connect.
         await this.connectOnce();
     }
     handleRenewalError(err, info) {
@@ -200,6 +217,8 @@ export class PresenceClient {
         if (this.stopped)
             return;
         this.clearReconnect();
+        this.clearStableTimer();
+        this.connectedAtMs = null;
         const generation = ++this.generation;
         this.teardownClient(true);
         try {
@@ -233,8 +252,17 @@ export class PresenceClient {
             client.on("connect", () => {
                 if (this.stopped || generation !== this.generation)
                     return;
-                this.attempt = 0;
-                this.lastBackoffMs = 0;
+                // Do not reset attempt here — broker may accept then close immediately
+                // (denied publish / policy). Reset only after CONNECT_STABLE_GRACE_MS.
+                this.connectedAtMs = this.timers.now();
+                this.clearStableTimer();
+                this.stableHandle = scheduleBoundedTimeout(this.timers, () => {
+                    this.stableHandle = null;
+                    if (this.stopped || generation !== this.generation)
+                        return;
+                    this.attempt = 0;
+                    this.lastBackoffMs = 0;
+                }, CONNECT_STABLE_GRACE_MS);
                 this.setState("connected");
                 void this.publishAll("online").then(() => {
                     this.options.onOnline?.(bundle.companies.map((c) => c.companyUid));
@@ -248,7 +276,13 @@ export class PresenceClient {
             client.on("close", () => {
                 if (this.stopped || generation !== this.generation)
                     return;
-                this.scheduleReconnect();
+                const elapsedMs = this.connectedAtMs != null
+                    ? Math.max(0, this.timers.now() - this.connectedAtMs)
+                    : 0;
+                this.connectedAtMs = null;
+                this.clearStableTimer();
+                const delay = this.scheduleReconnect();
+                this.maybeLogClose(elapsedMs, delay);
             });
         }
         catch (err) {
@@ -295,7 +329,7 @@ export class PresenceClient {
     }
     scheduleReconnect(opts) {
         if (this.stopped)
-            return;
+            return 0;
         this.setState("reconnecting");
         this.clearReconnect();
         let delay;
@@ -326,6 +360,17 @@ export class PresenceClient {
             }
             void this.connectOnce();
         }, delay);
+        return delay;
+    }
+    maybeLogClose(elapsedMs, delayMs) {
+        const now = this.timers.now();
+        const withinAlways = this.closeLogCount < CLOSE_LOG_ALWAYS_COUNT;
+        const intervalElapsed = now - this.lastCloseLogAtMs >= CLOSE_LOG_INTERVAL_MS;
+        if (!withinAlways && !intervalElapsed)
+            return;
+        this.closeLogCount += 1;
+        this.lastCloseLogAtMs = now;
+        this.options.onInfo?.(`presence mqtt closed after ${elapsedMs}ms; reconnect in ${delayMs}ms`);
     }
     clearReconnect() {
         if (this.reconnectHandle !== null) {
@@ -333,6 +378,12 @@ export class PresenceClient {
             this.reconnectHandle = null;
         }
     }
+    clearStableTimer() {
+        if (this.stableHandle !== null) {
+            this.stableHandle.clear();
+            this.stableHandle = null;
+        }
+    }
 }
 /** Production mqtt.connect wrapper (typed). */
 export function defaultMqttConnect(url, opts) {

package/dist/lib/mesh/live/daemon/run.js

@@ -64,17 +64,18 @@ export async function runMeshDaemon(deps = {}) {
     }
     writeDaemonState(dir, defaultDaemonState(lockDeps.pid, now));
     log(dir, `daemon started pid=${lockDeps.pid}`);
-    let token;
     // Opt into machine-credential minting when the box has creds (systemd exports
     // HQ_MACHINE_CREDS_FILE). On a person laptop with no machine creds this falls
     // through to the person login cache inside ensureCognitoToken.
+    //
+    // Resolve the token on EVERY use. ensureCognitoToken reads the on-disk cache
+    // and refreshes/mints when the token is near expiry, so this is cheap; a
+    // process-lifetime memo (the previous behaviour) handed a Cognito token that
+    // expires after ~1h to every vend/flush forever, so the second credential
+    // renewal (~96 min in) and everything after it failed with HTTP 401 and the
+    // daemon went dark once its IoT credentials expired.
     const defaultGetToken = async () => ensureCognitoToken({ interactive: false, tokenSource: "machine" });
-    const getToken = deps.getToken ??
-        (async () => {
-            if (!token)
-                token = await defaultGetToken();
-            return token;
-        });
+    const getToken = deps.getToken ?? defaultGetToken;
     const flushFn = deps.flush ??
         (async () => {
             const t = await getToken();
@@ -152,6 +153,9 @@ export async function runMeshDaemon(deps = {}) {
                 patchDaemonState(dir, { lastErrorCode: msg.slice(0, 120) }, now);
                 log(dir, `presence error: ${msg.slice(0, 200)}`);
             },
+            onInfo: (message) => {
+                log(dir, message.slice(0, 200));
+            },
         };
         presence = new PresenceClient(presenceOpts);
         try {

package/dist/main.js

@@ -8,60 +8,6 @@ import "./node-preflight.js";
 import "./node-network-compat.js";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
-import { registerAddCommand } from "./commands/add.js";
-import { registerSyncCommand } from "./commands/sync.js";
-import { registerListCommand } from "./commands/list.js";
-import { registerUpdateCommand } from "./commands/update.js";
-import { registerCloudCommands } from "./commands/cloud.js";
-import { registerSyncModeCommand } from "./commands/sync-mode.js";
-import { registerSyncNarrowCommand } from "./commands/sync-narrow.js";
-import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
-import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
-import { registerLoginCommand } from "./commands/login.js";
-import { registerLogoutCommand } from "./commands/logout.js";
-import { registerWhoamiCommand } from "./commands/whoami.js";
-import { registerOnboardCommand } from "./commands/onboard.js";
-import { registerPackageInstallCommand } from "./commands/pkg-install.js";
-import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
-import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
-import { registerPackageListCommand } from "./commands/pkg-list.js";
-import { registerPacksCommand } from "./commands/packs.js";
-import { registerPublishCommand } from "./commands/publish.js";
-import { registerCreatorsCommand } from "./commands/creators.js";
-import { registerTeamSyncCommand } from "./commands/team-sync.js";
-import { registerAuthCommands } from "./commands/auth.js";
-import { registerApiKeysCommand } from "./commands/api-keys.js";
-import { registerSecretsCommand } from "./commands/secrets.js";
-import { registerRunCommand } from "./commands/run.js";
-import { registerGroupsCommand } from "./commands/groups.js";
-import { registerWorkersCommand } from "./commands/workers.js";
-import { registerGroupGrantsCommand } from "./commands/group-grants.js";
-import { registerFilesCommand } from "./commands/files.js";
-import { registerFilesBrowseCommands } from "./commands/files-browse.js";
-import { registerSkillCommand } from "./commands/skill.js";
-import { registerMembersCommand } from "./commands/members.js";
-import { registerPeopleCommand } from "./commands/people.js";
-import { registerDmCommand } from "./commands/dm.js";
-import { registerChannelsCommand } from "./commands/channels.js";
-import { registerFeedbackCommand } from "./commands/feedback.js";
-import { registerMeetingsCommand } from "./commands/meetings.js";
-import { registerSourcesCommand } from "./commands/sources.js";
-import { registerSignalsCommand } from "./commands/signals.js";
-import { registerIntegrationsCommand } from "./commands/integrations.js";
-import { registerReindexCommand } from "./commands/reindex.js";
-import { registerRescueCommand } from "./commands/rescue.js";
-import { registerMcpCommand } from "./commands/mcp-status.js";
-import { registerCrmCommand } from "./commands/crm.js";
-import { registerCompanyCommand } from "./commands/company.js";
-import { registerAgentsCommand } from "./commands/agents.js";
-import { registerOutpostsCommand } from "./commands/outposts.js";
-import { registerBillingCommand } from "./commands/billing.js";
-import { registerDbCommand } from "./commands/db.js";
-import { registerCoreCommands } from "./commands/core.js";
-import { registerSearchCommand } from "./commands/search.js";
-import { registerIndexCommand } from "./commands/index-cmd.js";
-import { registerDoctorCommand } from "./commands/doctor.js";
-import { registerMeshCommand } from "./commands/mesh.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { syncStateLockMessage } from "./utils/sync-state-lock-error.js";
@@ -92,6 +38,7 @@ import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
+import { findLazyCommand } from "./lazy-commands.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
@@ -148,151 +95,6 @@ program
     .name("hq")
     .description("HQ management CLI — modules, packages, and cloud sync")
     .version(CLI_VERSION);
-// Module management subcommand group
-const modulesCmd = program
-    .command("modules")
-    .description("Module management commands");
-registerAddCommand(modulesCmd);
-registerSyncCommand(modulesCmd);
-registerListCommand(modulesCmd);
-registerUpdateCommand(modulesCmd);
-// Package management subcommand group
-const packagesCmd = program
-    .command("packages")
-    .description("Package management commands");
-registerPackageInstallCommand(packagesCmd);
-registerPackageRemoveCommand(packagesCmd);
-registerPackageUpdateCommand(packagesCmd);
-registerPackageListCommand(packagesCmd);
-// Content-pack lifecycle (core/packages/hq-pack-*). Distinct from the registry
-// `packages` system above. Available as both `hq packages packs …` (grouped)
-// and `hq packs …` (top-level convenience).
-registerPacksCommand(packagesCmd);
-registerPacksCommand(program);
-// Top-level shortcuts for package commands
-// "hq install <slug>" = "hq packages install <slug>"
-// "hq remove <slug>"  = "hq packages remove <slug>"
-registerPackageInstallCommand(program);
-registerPackageRemoveCommand(program);
-// Marketplace publish (top-level — packer + authenticated upload, US-004)
-// "hq publish <skill-or-worker-path>" packages and submits a pack to the
-// marketplace via POST /v1/listings.
-registerPublishCommand(program);
-// `hq creators apply` — request verified-creator access (required to publish).
-registerCreatorsCommand(program);
-// Cloud sync subcommand group
-const syncCmd = program
-    .command("sync")
-    .description("Cloud sync commands — sync HQ to S3 for mobile access");
-registerCloudCommands(syncCmd);
-registerSyncModeCommand(syncCmd);
-registerSyncNarrowCommand(syncCmd);
-// Cloud provisioning subcommand group (entity + bucket + initial sync)
-// Distinct from `hq sync` which assumes provisioning has already happened.
-const cloudCmd = program
-    .command("cloud")
-    .description("Cloud commands — provision entities and manage cloud-backed companies");
-registerCloudProvisionCommands(cloudCmd);
-registerCloudDemoteCommands(cloudCmd);
-// Team commands (top-level)
-registerTeamSyncCommand(program);
-// Auth commands (top-level — Cognito OAuth)
-registerLoginCommand(program);
-registerLogoutCommand(program);
-registerWhoamiCommand(program);
-registerAuthCommands(program);
-// Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
-registerSecretsCommand(program);
-// Vault databases (subcommand group — hq db status|sql|migrate|provision)
-registerDbCommand(program);
-// API key management (subcommand group — hq api-keys create|list|revoke)
-registerApiKeysCommand(program);
-// Schema-driven dev runner — hq run [options] -- <cmd>
-registerRunCommand(program);
-// Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
-registerGroupsCommand(program);
-// Worker discovery + sharing (subcommand group — hq workers list|share)
-registerWorkersCommand(program);
-// Cross-company group grants (subcommand group —
-// hq group-grants grant|revoke|outbound|inbound)
-registerGroupGrantsCommand(program);
-// Files ACL management (subcommand group — hq files share|unshare|acl)
-// `registerFilesCommand` returns the `files` group so we can attach the
-// browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
-const filesCmd = registerFilesCommand(program);
-registerFilesBrowseCommands(filesCmd);
-// Comment-only skill improvement loop. Structured suggestion/review commands are
-// intentionally absent; live content changes remain governed by FILE_ACL sync.
-registerSkillCommand(program);
-// Membership management (subcommand group — hq members invite|list|revoke)
-registerMembersCommand(program);
-// People directory (subcommand group — hq people list|search|resolve), reading
-// the local companies/<co>/people store scoped to one company.
-registerPeopleCommand(program);
-registerDmCommand(program);
-registerChannelsCommand(program);
-// Onboarding (top-level — Cognito + vault-service provisioning)
-registerOnboardCommand(program);
-// Feedback (subcommand group — hq feedback bug|feature)
-registerFeedbackCommand(program);
-// Meetings (subcommand group — hq meetings list|get|search|transcript|notes)
-registerMeetingsCommand(program);
-// Sources read surface (subcommand group — hq sources list|get|channels|entities)
-registerSourcesCommand(program);
-// Signals read surface (subcommand group — hq signals list|get|types|entities)
-registerSignalsCommand(program);
-// Company-connected apps via the governed integration gateway
-// (subcommand group — hq integrations list|tools|call|approve|reject)
-registerIntegrationsCommand(program);
-// Skill/personal-overlay mirroring + workers-registry regen. Invoked by the
-// hq-core reindex hook shim (Stop / PostToolUse) and by sync()/rescue() after
-// they change on-disk sources. Keeps a `master-sync` alias for one release.
-// Implementation lives in @indigoai-us/hq-cloud.
-registerReindexCommand(program);
-// Drift-preserving HQ-core re-sync (top-level — `hq rescue`). CLI sibling of
-// the HQ Sync app's "Update / Restore" pill; drives the same replace-rescue.sh
-// shipped from @indigoai-us/hq-cloud.
-registerRescueCommand(program);
-// MCP pack observability (subcommand group — `hq mcp status`). Read-only
-// provenance-based status across BOTH Claude + Codex runtimes (reads `_hqPack`
-// off the configs, NOT linkStatus), with secret-redacted output + `--json`.
-registerMcpCommand(program);
-// Native CRM entity upsert (subcommand group — `hq crm entity upsert`). Wraps
-// POST /crm/entities (the ontology write gate) so an authenticated company
-// member can create/update canonical CRM entities in the company vault.
-registerCrmCommand(program);
-// Company settings (subcommand group — `hq company settings set`). Owner-only
-// toggles for crmEnabled / ontologyEnabled via PUT /company-settings.
-registerCompanyCommand(program);
-// Cloud agent management (subcommand group — `hq agents …`). Rename, reconfigure,
-// start/stop, and tear down a company's fleet agents via the hq-pro /v1/agents
-// control plane — the same routes the web console's agents panel calls.
-registerAgentsCommand(program);
-// Personal Outpost management (subcommand group — `hq outposts …`). List, inspect,
-// enable Codex on, refresh login for, and destroy your EC2 boxes via the hq-pro
-// /outpost/* control plane.
-registerOutpostsCommand(program);
-// Billing (subcommand group — `hq billing …`). Check subscription/card state and
-// mint a shareable Stripe card-capture link — the client side of the paid-
-// provisioning gate for agents & Outposts.
-registerBillingCommand(program);
-// HQ scaffold scripts hosted by the CLI (hidden group — `hq core …`). Not a
-// public surface: every entry is invoked by an HQ skill, hook, or forwarder, and
-// the source-root entries are maintainer tools that must never touch a live
-// install. Registered from a manifest in the module, not wired per script here.
-registerCoreCommands(program);
-// Local qmd search and index management. Kept distinct from `hq reindex`,
-// which converges scaffold-owned files and hooks rather than search data.
-registerSearchCommand(program);
-registerIndexCommand(program);
-// Hook guardrail diagnostics (top-level — `hq doctor`). Read-only, offline
-// verification that HQ's hooks are wired and firing, backed by an extensible
-// check registry so later check families (vault, sync, MCP, …) plug in without
-// engine changes.
-registerDoctorCommand(program);
-// Work mesh (subcommand group — `hq mesh …`). Native REST + cache. Distinct
-// from `hq doctor` (hook guardrails). Does not start MQTT listen.
-registerMeshCommand(program);
 program.hook("preAction", async () => {
     // Both are best-effort and fully swallowed: neither can change the command's
     // result or exit code. The 1.2s bound they carry is a TIMER, so it only
@@ -351,6 +153,19 @@ export async function runCli() {
                 }
             }
         }
+        // Register only what this invocation needs. A hot command named in the
+        // lazy manifest imports its own module and nothing else; everything else —
+        // `--help`, a bare `hq`, an unknown command, any command not on the
+        // manifest — falls back to the complete graph, so its behaviour is
+        // unchanged. See register-all.ts for the measurements that motivated this.
+        const lazy = findLazyCommand(process.argv);
+        if (lazy) {
+            await lazy.register(program);
+        }
+        else {
+            const { registerAllCommands } = await import("./register-all.js");
+            registerAllCommands(program);
+        }
         await program.parseAsync();
     }
     catch (err) {

package/dist/register-all.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The full hq command graph — every `register*Command` call, moved here verbatim
+ * from main.ts.
+ *
+ * WHY IT IS ITS OWN MODULE: these 54 imports pull ~60 command modules and their
+ * dependency subtrees, and main.ts used to load all of them at module scope. On
+ * an outpost that cost real CPU, because the agent fleet calls `hq secrets`
+ * about 39 times a minute and each invocation paid for the entire graph before
+ * running one command. Measured on Outpost 2 (i-09424eff61920a4ac), CPU-seconds
+ * per process:
+ *
+ *   node -e ""                   0.03
+ *   dist/commands/secrets.js     1.13   <- what `hq secrets` actually needs
+ *   dist/main.js (full graph)    1.88   <- what it used to pay
+ *
+ * So ~0.75 CPU-seconds of every `hq secrets` was spent importing commands it
+ * never ran. At 39 invocations/minute that is ~0.5 of a core, continuously.
+ *
+ * Splitting the graph out lets the entrypoint import ONE command module for the
+ * hot paths named in lazy-commands.ts, and fall back to this module — the
+ * complete, unchanged registration — for everything else: `--help`, a bare
+ * `hq`, an unknown command, and every command not in that manifest. Anything
+ * not on the manifest therefore behaves exactly as before.
+ *
+ * Keep this list and lazy-commands.ts in sync through the parity test in
+ * lazy-commands.test.ts, which registers both ways and compares the resulting
+ * command shapes. Same discipline as commands/scaffold-fast.ts and core.ts.
+ */
+import type { Command } from "commander";
+/** Register the complete hq command graph onto `program`. */
+export declare function registerAllCommands(program: Command): void;
+//# sourceMappingURL=register-all.d.ts.map

package/dist/register-all.js

@@ -0,0 +1,231 @@
+/**
+ * The full hq command graph — every `register*Command` call, moved here verbatim
+ * from main.ts.
+ *
+ * WHY IT IS ITS OWN MODULE: these 54 imports pull ~60 command modules and their
+ * dependency subtrees, and main.ts used to load all of them at module scope. On
+ * an outpost that cost real CPU, because the agent fleet calls `hq secrets`
+ * about 39 times a minute and each invocation paid for the entire graph before
+ * running one command. Measured on Outpost 2 (i-09424eff61920a4ac), CPU-seconds
+ * per process:
+ *
+ *   node -e ""                   0.03
+ *   dist/commands/secrets.js     1.13   <- what `hq secrets` actually needs
+ *   dist/main.js (full graph)    1.88   <- what it used to pay
+ *
+ * So ~0.75 CPU-seconds of every `hq secrets` was spent importing commands it
+ * never ran. At 39 invocations/minute that is ~0.5 of a core, continuously.
+ *
+ * Splitting the graph out lets the entrypoint import ONE command module for the
+ * hot paths named in lazy-commands.ts, and fall back to this module — the
+ * complete, unchanged registration — for everything else: `--help`, a bare
+ * `hq`, an unknown command, and every command not in that manifest. Anything
+ * not on the manifest therefore behaves exactly as before.
+ *
+ * Keep this list and lazy-commands.ts in sync through the parity test in
+ * lazy-commands.test.ts, which registers both ways and compares the resulting
+ * command shapes. Same discipline as commands/scaffold-fast.ts and core.ts.
+ */
+import { registerAddCommand } from "./commands/add.js";
+import { registerSyncCommand } from "./commands/sync.js";
+import { registerListCommand } from "./commands/list.js";
+import { registerUpdateCommand } from "./commands/update.js";
+import { registerCloudCommands } from "./commands/cloud.js";
+import { registerSyncModeCommand } from "./commands/sync-mode.js";
+import { registerSyncNarrowCommand } from "./commands/sync-narrow.js";
+import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
+import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
+import { registerLoginCommand } from "./commands/login.js";
+import { registerLogoutCommand } from "./commands/logout.js";
+import { registerWhoamiCommand } from "./commands/whoami.js";
+import { registerOnboardCommand } from "./commands/onboard.js";
+import { registerPackageInstallCommand } from "./commands/pkg-install.js";
+import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
+import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
+import { registerPackageListCommand } from "./commands/pkg-list.js";
+import { registerPacksCommand } from "./commands/packs.js";
+import { registerPublishCommand } from "./commands/publish.js";
+import { registerCreatorsCommand } from "./commands/creators.js";
+import { registerTeamSyncCommand } from "./commands/team-sync.js";
+import { registerAuthCommands } from "./commands/auth.js";
+import { registerApiKeysCommand } from "./commands/api-keys.js";
+import { registerSecretsCommand } from "./commands/secrets.js";
+import { registerRunCommand } from "./commands/run.js";
+import { registerGroupsCommand } from "./commands/groups.js";
+import { registerWorkersCommand } from "./commands/workers.js";
+import { registerGroupGrantsCommand } from "./commands/group-grants.js";
+import { registerFilesCommand } from "./commands/files.js";
+import { registerFilesBrowseCommands } from "./commands/files-browse.js";
+import { registerSkillCommand } from "./commands/skill.js";
+import { registerMembersCommand } from "./commands/members.js";
+import { registerPeopleCommand } from "./commands/people.js";
+import { registerDmCommand } from "./commands/dm.js";
+import { registerChannelsCommand } from "./commands/channels.js";
+import { registerFeedbackCommand } from "./commands/feedback.js";
+import { registerMeetingsCommand } from "./commands/meetings.js";
+import { registerSourcesCommand } from "./commands/sources.js";
+import { registerSignalsCommand } from "./commands/signals.js";
+import { registerIntegrationsCommand } from "./commands/integrations.js";
+import { registerReindexCommand } from "./commands/reindex.js";
+import { registerRescueCommand } from "./commands/rescue.js";
+import { registerMcpCommand } from "./commands/mcp-status.js";
+import { registerCrmCommand } from "./commands/crm.js";
+import { registerCompanyCommand } from "./commands/company.js";
+import { registerAgentsCommand } from "./commands/agents.js";
+import { registerOutpostsCommand } from "./commands/outposts.js";
+import { registerBillingCommand } from "./commands/billing.js";
+import { registerDbCommand } from "./commands/db.js";
+import { registerCoreCommands } from "./commands/core.js";
+import { registerSearchCommand } from "./commands/search.js";
+import { registerIndexCommand } from "./commands/index-cmd.js";
+import { registerDoctorCommand } from "./commands/doctor.js";
+import { registerMeshCommand } from "./commands/mesh.js";
+/** Register the complete hq command graph onto `program`. */
+export function registerAllCommands(program) {
+    // Module management subcommand group
+    const modulesCmd = program
+        .command("modules")
+        .description("Module management commands");
+    registerAddCommand(modulesCmd);
+    registerSyncCommand(modulesCmd);
+    registerListCommand(modulesCmd);
+    registerUpdateCommand(modulesCmd);
+    // Package management subcommand group
+    const packagesCmd = program
+        .command("packages")
+        .description("Package management commands");
+    registerPackageInstallCommand(packagesCmd);
+    registerPackageRemoveCommand(packagesCmd);
+    registerPackageUpdateCommand(packagesCmd);
+    registerPackageListCommand(packagesCmd);
+    // Content-pack lifecycle (core/packages/hq-pack-*). Distinct from the registry
+    // `packages` system above. Available as both `hq packages packs …` (grouped)
+    // and `hq packs …` (top-level convenience).
+    registerPacksCommand(packagesCmd);
+    registerPacksCommand(program);
+    // Top-level shortcuts for package commands
+    // "hq install <slug>" = "hq packages install <slug>"
+    // "hq remove <slug>"  = "hq packages remove <slug>"
+    registerPackageInstallCommand(program);
+    registerPackageRemoveCommand(program);
+    // Marketplace publish (top-level — packer + authenticated upload, US-004)
+    // "hq publish <skill-or-worker-path>" packages and submits a pack to the
+    // marketplace via POST /v1/listings.
+    registerPublishCommand(program);
+    // `hq creators apply` — request verified-creator access (required to publish).
+    registerCreatorsCommand(program);
+    // Cloud sync subcommand group
+    const syncCmd = program
+        .command("sync")
+        .description("Cloud sync commands — sync HQ to S3 for mobile access");
+    registerCloudCommands(syncCmd);
+    registerSyncModeCommand(syncCmd);
+    registerSyncNarrowCommand(syncCmd);
+    // Cloud provisioning subcommand group (entity + bucket + initial sync)
+    // Distinct from `hq sync` which assumes provisioning has already happened.
+    const cloudCmd = program
+        .command("cloud")
+        .description("Cloud commands — provision entities and manage cloud-backed companies");
+    registerCloudProvisionCommands(cloudCmd);
+    registerCloudDemoteCommands(cloudCmd);
+    // Team commands (top-level)
+    registerTeamSyncCommand(program);
+    // Auth commands (top-level — Cognito OAuth)
+    registerLoginCommand(program);
+    registerLogoutCommand(program);
+    registerWhoamiCommand(program);
+    registerAuthCommands(program);
+    // Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
+    registerSecretsCommand(program);
+    // Vault databases (subcommand group — hq db status|sql|migrate|provision)
+    registerDbCommand(program);
+    // API key management (subcommand group — hq api-keys create|list|revoke)
+    registerApiKeysCommand(program);
+    // Schema-driven dev runner — hq run [options] -- <cmd>
+    registerRunCommand(program);
+    // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
+    registerGroupsCommand(program);
+    // Worker discovery + sharing (subcommand group — hq workers list|share)
+    registerWorkersCommand(program);
+    // Cross-company group grants (subcommand group —
+    // hq group-grants grant|revoke|outbound|inbound)
+    registerGroupGrantsCommand(program);
+    // Files ACL management (subcommand group — hq files share|unshare|acl)
+    // `registerFilesCommand` returns the `files` group so we can attach the
+    // browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
+    const filesCmd = registerFilesCommand(program);
+    registerFilesBrowseCommands(filesCmd);
+    // Comment-only skill improvement loop. Structured suggestion/review commands are
+    // intentionally absent; live content changes remain governed by FILE_ACL sync.
+    registerSkillCommand(program);
+    // Membership management (subcommand group — hq members invite|list|revoke)
+    registerMembersCommand(program);
+    // People directory (subcommand group — hq people list|search|resolve), reading
+    // the local companies/<co>/people store scoped to one company.
+    registerPeopleCommand(program);
+    registerDmCommand(program);
+    registerChannelsCommand(program);
+    // Onboarding (top-level — Cognito + vault-service provisioning)
+    registerOnboardCommand(program);
+    // Feedback (subcommand group — hq feedback bug|feature)
+    registerFeedbackCommand(program);
+    // Meetings (subcommand group — hq meetings list|get|search|transcript|notes)
+    registerMeetingsCommand(program);
+    // Sources read surface (subcommand group — hq sources list|get|channels|entities)
+    registerSourcesCommand(program);
+    // Signals read surface (subcommand group — hq signals list|get|types|entities)
+    registerSignalsCommand(program);
+    // Company-connected apps via the governed integration gateway
+    // (subcommand group — hq integrations list|tools|call|approve|reject)
+    registerIntegrationsCommand(program);
+    // Skill/personal-overlay mirroring + workers-registry regen. Invoked by the
+    // hq-core reindex hook shim (Stop / PostToolUse) and by sync()/rescue() after
+    // they change on-disk sources. Keeps a `master-sync` alias for one release.
+    // Implementation lives in @indigoai-us/hq-cloud.
+    registerReindexCommand(program);
+    // Drift-preserving HQ-core re-sync (top-level — `hq rescue`). CLI sibling of
+    // the HQ Sync app's "Update / Restore" pill; drives the same replace-rescue.sh
+    // shipped from @indigoai-us/hq-cloud.
+    registerRescueCommand(program);
+    // MCP pack observability (subcommand group — `hq mcp status`). Read-only
+    // provenance-based status across BOTH Claude + Codex runtimes (reads `_hqPack`
+    // off the configs, NOT linkStatus), with secret-redacted output + `--json`.
+    registerMcpCommand(program);
+    // Native CRM entity upsert (subcommand group — `hq crm entity upsert`). Wraps
+    // POST /crm/entities (the ontology write gate) so an authenticated company
+    // member can create/update canonical CRM entities in the company vault.
+    registerCrmCommand(program);
+    // Company settings (subcommand group — `hq company settings set`). Owner-only
+    // toggles for crmEnabled / ontologyEnabled via PUT /company-settings.
+    registerCompanyCommand(program);
+    // Cloud agent management (subcommand group — `hq agents …`). Rename, reconfigure,
+    // start/stop, and tear down a company's fleet agents via the hq-pro /v1/agents
+    // control plane — the same routes the web console's agents panel calls.
+    registerAgentsCommand(program);
+    // Personal Outpost management (subcommand group — `hq outposts …`). List, inspect,
+    // enable Codex on, refresh login for, and destroy your EC2 boxes via the hq-pro
+    // /outpost/* control plane.
+    registerOutpostsCommand(program);
+    // Billing (subcommand group — `hq billing …`). Check subscription/card state and
+    // mint a shareable Stripe card-capture link — the client side of the paid-
+    // provisioning gate for agents & Outposts.
+    registerBillingCommand(program);
+    // HQ scaffold scripts hosted by the CLI (hidden group — `hq core …`). Not a
+    // public surface: every entry is invoked by an HQ skill, hook, or forwarder, and
+    // the source-root entries are maintainer tools that must never touch a live
+    // install. Registered from a manifest in the module, not wired per script here.
+    registerCoreCommands(program);
+    // Local qmd search and index management. Kept distinct from `hq reindex`,
+    // which converges scaffold-owned files and hooks rather than search data.
+    registerSearchCommand(program);
+    registerIndexCommand(program);
+    // Hook guardrail diagnostics (top-level — `hq doctor`). Read-only, offline
+    // verification that HQ's hooks are wired and firing, backed by an extensible
+    // check registry so later check families (vault, sync, MCP, …) plug in without
+    // engine changes.
+    registerDoctorCommand(program);
+    // Work mesh (subcommand group — `hq mesh …`). Native REST + cache. Distinct
+    // from `hq doctor` (hook guardrails). Does not start MQTT listen.
+    registerMeshCommand(program);
+}
+//# sourceMappingURL=register-all.js.map

package/package.json

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