@indigoai-us/hq-cli 5.111.2 → 5.113.0

package/dist/main.d.ts

@@ -5,6 +5,12 @@
 import "./node-preflight.js";
 import "./node-network-compat.js";
 import { Sentry } from "./sentry.js";
+/**
+ * Total time one CLI invocation may await foreground network work. This spans
+ * the hard version decision, pre-action observability, and release-health
+ * finalization; command execution itself does not consume this allowance.
+ */
+export declare const FOREGROUND_NETWORK_BUDGET_MS = 1500;
 export type StreamErrorDependencies = {
     stderr: Pick<typeof process.stderr, "write">;
     exit: (code: number) => void;

package/dist/main.js

@@ -9,7 +9,7 @@ import "./node-network-compat.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { initSentry, Sentry } from "./sentry.js";
+import { finishSentrySession, initSentry, Sentry } from "./sentry.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { syncStateLockMessage } from "./utils/sync-state-lock-error.js";
@@ -41,7 +41,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 { findLazyCommand, registerCommandCatalog } 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";
@@ -52,8 +52,57 @@ import { registerCommandsWithRecovery } from "./startup-registration.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";
-/** Hard upper bound for non-user-visible release-health finalization. */
-const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
+/**
+ * Total time one CLI invocation may await foreground network work. This spans
+ * the hard version decision, pre-action observability, and release-health
+ * finalization; command execution itself does not consume this allowance.
+ */
+export const FOREGROUND_NETWORK_BUDGET_MS = 1_500;
+/**
+ * Release health must always have a chance to flush an already-captured error
+ * and refresh the cache after a command. Reserve this before earlier work.
+ */
+const FINALIZATION_FOREGROUND_WAIT_MS = 500;
+/**
+ * A stalled version endpoint must leave the invocation heartbeat a chance to
+ * send. A timely blocked response is still enforced exactly as before.
+ */
+const VERSION_GATE_FOREGROUND_WAIT_MS = 750;
+/** Existing telemetry/health cap, now also bounded by the shared deadline. */
+const OBSERVABILITY_FOREGROUND_WAIT_MS = 1_200;
+/**
+ * Shared accounting for awaited foreground network work. Each lifecycle phase
+ * debits only the bounded await it performs; ordinary command runtime leaves
+ * the allowance untouched. Earlier phases reserve the finalization floor, so
+ * error flushing cannot disappear after a long command.
+ */
+class ForegroundNetworkBudget {
+    budgetMs;
+    now;
+    consumedMs = 0;
+    constructor(budgetMs = FOREGROUND_NETWORK_BUDGET_MS, now = () => performance.now()) {
+        this.budgetMs = budgetMs;
+        this.now = now;
+    }
+    timeoutFor(phaseMaximumMs, reservedMs = 0) {
+        return Math.max(0, Math.min(phaseMaximumMs, Math.floor(this.budgetMs - reservedMs - this.consumedMs)));
+    }
+    async waitFor(phaseMaximumMs, reservedMs, work) {
+        const timeoutMs = this.timeoutFor(phaseMaximumMs, reservedMs);
+        if (timeoutMs === 0)
+            return undefined;
+        const startedAt = this.now();
+        try {
+            return await work(timeoutMs);
+        }
+        finally {
+            // A timer cannot interrupt synchronous work. Do not let a blocked event
+            // loop consume the finalization reserve as though it were network wait.
+            this.consumedMs += Math.min(timeoutMs, Math.max(0, this.now() - startedAt));
+        }
+    }
+}
+let activeForegroundNetworkBudget;
 /**
  * The RUNNING install's own entrypoint (`<pkg>/dist/index.js`), used as the
  * torn-install recovery re-exec target. It must be this resolved path — never
@@ -110,17 +159,23 @@ program
     .version(CLI_VERSION);
 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
-    // preempts asynchronous work — synchronous work inside them runs to
-    // completion regardless, because the timer cannot be serviced while the
-    // event loop is blocked. Keep anything added here asynchronous, or
-    // separately cheap: this hook is on the path of EVERY hq command.
-    await Promise.all([
-        emitCliSessionStarted(),
-        reportCliClientHealthInvocation(),
-    ]);
+    // result or exit code. They receive only the shared pre-finalization
+    // allowance (up to 1.2s), and that bound is a TIMER, so it only preempts
+    // asynchronous work — synchronous work inside them runs to completion
+    // regardless, because the timer cannot be serviced while the event loop is
+    // blocked. Keep anything added here asynchronous, or separately cheap: this
+    // hook is on the path of EVERY hq command.
+    const budget = activeForegroundNetworkBudget;
+    if (!budget)
+        return;
+    await budget.waitFor(OBSERVABILITY_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => Promise.all([
+        emitCliSessionStarted(timeoutMs),
+        reportCliClientHealthInvocation({ timeoutMs }),
+    ]));
 });
 export async function runCli() {
+    const foregroundNetworkBudget = new ForegroundNetworkBudget();
+    activeForegroundNetworkBudget = foregroundNetworkBudget;
     // Begin one registry refresh without awaiting it. Every command gate reads
     // only the client's held snapshot and falls back locally, so an offline or
     // slow registry cannot delay command parsing or alter a command failure.
@@ -149,12 +204,12 @@ export async function runCli() {
         //    `version-check.ts`); whichever fires first re-execs, and the child
         //    carries a guard env so it can never update again.
         if (!shouldSkipGate(process.argv)) {
-            const gate = await enforceVersionGate(async (decision) => {
+            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 === "reexec")
                     reexecStatus = outcome.reexecStatus ?? 0;
                 return outcome.action === "reexec";
-            });
+            }, { timeoutMs }))) ?? "continue";
             if (gate === "reexec")
                 return;
             const cachedLatest = staleAgainstCachedLatest();
@@ -166,15 +221,11 @@ 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.
-        // The same lazy/full registration as before, wrapped so it recovers ONCE if
-        // a global reinstall is tearing the install tree out from under these
-        // deferred imports (Sentry HQ-CLI-1G/1H/1J/1K). Which modules are imported,
-        // and in what order, is unchanged — only the failure handling is added.
+        // Register every contributor for the selected root only. Root help and
+        // unknown-command recovery use generated metadata, so they keep the full
+        // Commander surface without evaluating every command implementation.
+        // Registration remains inside the torn-install recovery boundary: deferred
+        // import failures still receive the same one-shot settled-tree re-exec.
         const registration = await registerCommandsWithRecovery({
             register: async () => {
                 const lazy = findLazyCommand(process.argv);
@@ -182,8 +233,7 @@ export async function runCli() {
                     await lazy.register(program);
                 }
                 else {
-                    const { registerAllCommands } = await import("./register-all.js");
-                    registerAllCommands(program);
+                    registerCommandCatalog(program);
                 }
             },
             argv: process.argv,
@@ -207,16 +257,24 @@ export async function runCli() {
         // process.exitCode — safe to run after exit codes have been set.
         emitPlanLimitNag();
         // Release health: finalize the per-run session before the flush.
-        Sentry.endSession();
+        finishSentrySession();
         // Neither task may turn a successful command into Node's
         // `unsettled top-level await` exit. They are observability-only after the
         // command has completed, so a bounded best-effort wait is the terminal
-        // lifecycle boundary for this invocation.
-        await settleWithin([refreshVersionCache(), Sentry.flush(2000)], RELEASE_HEALTH_SETTLE_TIMEOUT_MS);
+        // lifecycle boundary for this invocation. The budget reserves this 500 ms
+        // slice even when the command itself was long-running.
+        const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
+        await settleWithin([
+            refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
+            Sentry.flush(releaseHealthTimeoutMs),
+        ], releaseHealthTimeoutMs);
         // Last, so it wins over anything the (skipped) command path would have
         // set: the re-exec'd child's status IS this invocation's result.
         if (reexecStatus !== null)
             process.exitCode = reexecStatus;
+        if (activeForegroundNetworkBudget === foregroundNetworkBudget) {
+            activeForegroundNetworkBudget = undefined;
+        }
     }
 }
 const defaultTopLevelErrorDependencies = {

package/dist/register-all.d.ts

@@ -1,32 +1,7 @@
 /**
- * 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.
+ * Complete command registration, retained as the eager reference used by the
+ * generated-catalog check and parity tests. Runtime dispatch uses the same
+ * plan one root at a time through lazy-commands.ts.
  */
-import type { Command } from "commander";
-/** Register the complete hq command graph onto `program`. */
-export declare function registerAllCommands(program: Command): void;
+export { registerAllCommands, registerCommandRoot } from "./command-registration-plan.js";
 //# sourceMappingURL=register-all.d.ts.map

package/dist/register-all.js

@@ -1,238 +1,7 @@
 /**
- * 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.
+ * Complete command registration, retained as the eager reference used by the
+ * generated-catalog check and parity tests. Runtime dispatch uses the same
+ * plan one root at a time through lazy-commands.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 { registerSyncManifestCommand } from "./commands/sync-manifest.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 { registerAccessCommand } from "./commands/access.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 { registerBotCommand } from "./commands/bot.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);
-    registerSyncManifestCommand(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);
-    // Top-level `hq access` — vault existence + ACL probe (self-healing ladder).
-    registerAccessCommand(program);
-    // 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);
-    registerBotCommand(program);
-}
+export { registerAllCommands, registerCommandRoot } from "./command-registration-plan.js";
 //# sourceMappingURL=register-all.js.map

package/dist/sentry.d.ts

@@ -1,5 +1,5 @@
 import * as Sentry from "@sentry/node";
-import type { ErrorEvent, EventHint } from "@sentry/node";
+import type { ErrorEvent, EventHint, NodeOptions } from "@sentry/node";
 /**
  * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
  * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
@@ -11,6 +11,12 @@ import type { ErrorEvent, EventHint } from "@sentry/node";
  * Consistent with the swallow-EPIPE posture established in #138.
  */
 export declare function epipeAwareBeforeSend(event: ErrorEvent, hint: EventHint): ErrorEvent | null;
-export declare function initSentry(): void;
+/**
+ * Tests substitute only the transport so the real SDK lifecycle can be
+ * exercised without an ingest request. Production callers pass nothing.
+ */
+export declare function initSentry(overrides?: Partial<Pick<NodeOptions, "transport">>): void;
+/** Finish HQ's one per-invocation release-health session. */
+export declare function finishSentrySession(): void;
 export { Sentry };
 //# sourceMappingURL=sentry.d.ts.map

package/dist/sentry.js

@@ -78,12 +78,20 @@ export function epipeAwareBeforeSend(event, hint) {
         event.fingerprint = fingerprint;
     return beforeSend(event, hint);
 }
-export function initSentry() {
+/**
+ * Tests substitute only the transport so the real SDK lifecycle can be
+ * exercised without an ingest request. Production callers pass nothing.
+ */
+export function initSentry(overrides = {}) {
     const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
     if (!dsn)
         return;
     Sentry.init({
         dsn,
+        // import-in-the-middle's async ESM loader makes every later CLI import
+        // substantially slower. Keep HQ's explicit breadcrumbs, but give up
+        // automatic ESM third-party instrumentation (its spans/breadcrumbs).
+        registerEsmLoaderHooks: false,
         // CLI_VERSION reads package.json at runtime; npm_package_version is only
         // set under `npm run`, so an installed `hq` binary would always report
         // 0.0.0 and never match the uploaded source maps.
@@ -94,6 +102,10 @@ export function initSentry() {
         },
         beforeSend: epipeAwareBeforeSend,
         beforeBreadcrumb,
+        // HQ owns this short-lived CLI session explicitly below and closes it from
+        // main.ts. Leaving the SDK default enabled starts a competing session.
+        integrations: (defaults) => defaults.filter((integration) => integration.name !== "ProcessSession"),
+        ...overrides,
     });
     // Attribute events to the logged-in HQ identity (best-effort; null when not
     // logged in). A CLI process is one user, so global setUser is correct here.
@@ -105,5 +117,9 @@ export function initSentry() {
     // "errored", so crash-free numbers per release stay accurate.
     Sentry.startSession();
 }
+/** Finish HQ's one per-invocation release-health session. */
+export function finishSentrySession() {
+    Sentry.endSession();
+}
 export { Sentry };
 //# sourceMappingURL=sentry.js.map

package/dist/utils/cli-telemetry.d.ts

@@ -1,6 +1,7 @@
+export declare const TELEMETRY_TIMEOUT_MS = 1200;
 /**
  * Emit the authenticated CLI session signal using an already-cached token.
  * This deliberately never refreshes a session or opens a browser.
  */
-export declare function emitCliSessionStarted(): Promise<void>;
+export declare function emitCliSessionStarted(timeoutMs?: number): Promise<void>;
 //# sourceMappingURL=cli-telemetry.d.ts.map

package/dist/utils/cli-telemetry.js

@@ -1,17 +1,17 @@
 import { CLI_VERSION } from "../cli-version.js";
 import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
 import { vaultApiFetch } from "./vault-api.js";
-const TELEMETRY_TIMEOUT_MS = 1_200;
+export const TELEMETRY_TIMEOUT_MS = 1_200;
 let cliSessionStartedPromise;
 /**
  * Emit the authenticated CLI session signal using an already-cached token.
  * This deliberately never refreshes a session or opens a browser.
  */
-export function emitCliSessionStarted() {
-    cliSessionStartedPromise ??= emitCachedCliSessionStarted();
+export function emitCliSessionStarted(timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    cliSessionStartedPromise ??= emitCachedCliSessionStarted(timeoutMs);
     return cliSessionStartedPromise;
 }
-async function emitCachedCliSessionStarted() {
+async function emitCachedCliSessionStarted(timeoutMs) {
     try {
         const cached = loadCachedTokens();
         if (!cached || isExpiring(cached, 120))
@@ -20,7 +20,7 @@ async function emitCachedCliSessionStarted() {
         if (!token)
             return;
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
         try {
             const response = await vaultApiFetch({
                 token,

package/dist/utils/contribution-table.d.ts

@@ -99,5 +99,5 @@ export declare const CONTRIBUTION_KEYS: ContributionKey[];
  */
 export declare function payloadFor(key: ContributionKey, item: string): string;
 /** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
-export declare const SYMLINK_KEYS: ("workers" | "knowledge" | "skills" | "commands" | "hooks" | "policies" | "scripts" | "mcp")[];
+export declare const SYMLINK_KEYS: ("workers" | "mcp" | "knowledge" | "skills" | "commands" | "hooks" | "policies" | "scripts")[];
 //# sourceMappingURL=contribution-table.d.ts.map

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

@@ -17,7 +17,10 @@ export declare function staleAgainstCachedLatest(now?: number): string | null;
  * means the loop guard is skipped this once, never a broken CLI.
  */
 export declare function markLatestIneffective(version: string, now?: number): void;
-export declare function refreshVersionCache(): Promise<void>;
+export interface RefreshVersionCacheOptions {
+    timeoutMs?: number;
+}
+export declare function refreshVersionCache(options?: RefreshVersionCacheOptions): Promise<void>;
 export declare const __test__: {
     CACHE_TTL_MS: number;
     isKnownNoninteractiveStatusProbe: typeof isKnownNoninteractiveStatusProbe;

package/dist/utils/version-check.js

@@ -166,7 +166,7 @@ export function markLatestIneffective(version, now = Date.now()) {
         ineffectiveAt: now,
     });
 }
-export async function refreshVersionCache() {
+export async function refreshVersionCache(options = {}) {
     if (isOptedOut())
         return;
     if (isKnownNoninteractiveStatusProbe())
@@ -183,7 +183,7 @@ export async function refreshVersionCache() {
             return;
         const res = await fetch(REGISTRY_URL, {
             headers: { Accept: "application/json" },
-            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            signal: AbortSignal.timeout(options.timeoutMs ?? FETCH_TIMEOUT_MS),
         });
         if (!res.ok)
             return;

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

@@ -404,7 +404,11 @@ declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: En
  * must exit rather than running the command a second time.
  */
 export type VersionGateOutcome = "continue" | "reexec";
-export declare function enforceVersionGate(onUpdateRecommended?: (decision: VersionCheckResponse, install: RunningInstall) => Promise<boolean>): Promise<VersionGateOutcome>;
+/** Optional caller-owned bound for the network-only version decision. */
+export interface VersionGateOptions {
+    timeoutMs?: number;
+}
+export declare function enforceVersionGate(onUpdateRecommended?: (decision: VersionCheckResponse, install: RunningInstall) => Promise<boolean>, options?: VersionGateOptions): Promise<VersionGateOutcome>;
 /**
  * Cheap argv pre-check: skip the gate for `--version` / `-V` so users
  * inspecting a broken install can still see what they have without being