@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/dist/main.d.ts

@@ -5,13 +5,6 @@
 import "./node-preflight.js";
 import "./node-network-compat.js";
 import { Sentry } from "./sentry.js";
-import { upgradeToTeam } from "./utils/team-upgrade.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;
@@ -22,11 +15,6 @@ export type TopLevelErrorDependencies = {
     sentry: Pick<typeof Sentry, "captureException">;
     stderr: Pick<typeof process.stderr, "write">;
     setExitCode: (code: number) => void;
-    interactive?: boolean;
-    argv?: readonly string[];
-    ask?: (question: string) => Promise<string>;
-    openUrl?: (url: string) => Promise<void>;
-    upgradeToTeam?: typeof upgradeToTeam;
 };
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export declare function handleTopLevelError(err: unknown, deps?: TopLevelErrorDependencies): Promise<void>;

package/dist/main.js

@@ -9,9 +9,9 @@ import "./node-network-compat.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { finishSentrySession, initSentry, Sentry } from "./sentry.js";
+import { initSentry, Sentry } from "./sentry.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
-import { environmentalFsErrorMessage, filesystemErrorCaptureContext, filesystemErrorMessage, } from "./utils/environmental-error.js";
+import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { syncStateLockMessage } from "./utils/sync-state-lock-error.js";
 import { networkTransportErrorMessage } from "./utils/network-transport-error.js";
 import { qmdNativeBindingErrorMessage } from "./utils/qmd-native-binding-error.js";
@@ -24,9 +24,7 @@ import { qmdStoreUnopenableMessage } from "./utils/qmd-store-unopenable-error.js
 import { qmdQueryDocumentMessage } from "./utils/qmd-query-document-error.js";
 import { qmdModelDownloadMessage } from "./utils/qmd-model-download-error.js";
 import { qmdWorkdirMissingMessage } from "./utils/qmd-workdir-missing-error.js";
-import { qmdExitCaptureContext } from "./lib/search-index/qmd-exit-diagnostics.js";
 import { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
-import { checkpointStampWriteCaptureContext, checkpointStampWriteMessage, } from "./utils/checkpoint-stamp-write-error.js";
 import { incompleteInstallMessage, incompleteInstallCaptureContext, } from "./utils/incomplete-install-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isVarlockEnvError } from "./run/env-graph-guard.js";
@@ -37,14 +35,14 @@ import { browserLoginAbandonedMessage } from "./utils/browser-login-abandoned.js
 import { callbackPortBusyMessage, DEFAULT_CALLBACK_PORT } from "./utils/callback-port-busy.js";
 import { DEFAULT_COGNITO } from "./utils/cognito-session.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
-import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, } from "./utils/plan-gate-error.js";
+import { canOfferTeamUpgrade, formatPlanGateError, isPlanGateError, offerTeamUpgrade, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
-import { printVersionAndNudge, refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
+import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
-import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
-import { emitCliFirstSyncNextStepOutcome, emitCliLimitNoticeEngagement, emitCliLimitNoticeExposure, emitCliSessionStarted, emitPlanLimitInviteTeammateExposure, isCliLimitResourceKind, queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, takeFirstSyncStepOutcomes, takeCliLimitNoticeEngagements, takeCliLimitNoticeExposures, takePlanLimitInviteTeammateExposures, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.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";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
@@ -54,61 +52,8 @@ 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";
-import { runGlobalNetworkLifecycle } from "./utils/cli-network-lifecycle.js";
-import * as os from "node:os";
-import { adoptAgentIdentityEnv } from "./lib/agent-kit/adopt-identity.js";
-import { agentKitPaths } from "./lib/agent-kit/paths.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 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;
+/** Hard upper bound for non-user-visible release-health finalization. */
+const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
 /**
  * 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
@@ -157,64 +102,39 @@ export function handleStreamError(err, deps = defaultStreamErrorDependencies) {
 }
 process.stdout.on("error", (err) => handleStreamError(err));
 process.stderr.on("error", (err) => handleStreamError(err));
-runGlobalNetworkLifecycle(process.argv, () => initSentry());
+initSentry();
 const program = new Command();
 program
     .name("hq")
     .description("HQ management CLI — modules, packages, and cloud sync")
-    .version(CLI_VERSION)
-    .option("--verbose", "Show verbose diagnostics, including SDK runtime warnings");
+    .version(CLI_VERSION);
 program.hook("preAction", async () => {
-    // A host that pinned HQ_AGENT_DIR has declared that it IS that agent, so
-    // every command — `hq dm`, `hq secrets`, not only `hq agent …` — must
-    // mint as the agent. Without this, those commands looked for a person
-    // session, found none, and opened a browser sign-in that a headless bot can
-    // never complete. Only the explicit variable counts: a bot that merely lives
-    // beside its owner on the owner's computer must not take over the owner's
-    // commands.
-    if (process.env.HQ_AGENT_DIR?.trim()) {
-        adoptAgentIdentityEnv(agentKitPaths(os.homedir(), process.env), process.env);
-    }
     // Both are best-effort and fully swallowed: neither can change the command's
-    // 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.
-    await runGlobalNetworkLifecycle(process.argv, async () => {
-        const budget = activeForegroundNetworkBudget;
-        if (!budget)
-            return;
-        await budget.waitFor(OBSERVABILITY_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => Promise.all([
-            emitCliSessionStarted(timeoutMs),
-            reportCliClientHealthInvocation({ timeoutMs }),
-        ]));
-    });
+    // 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(),
+    ]);
 });
 export async function runCli() {
-    const foregroundNetworkBudget = new ForegroundNetworkBudget();
-    activeForegroundNetworkBudget = foregroundNetworkBudget;
-    // Login must be usable before any identity or company is available, so do
-    // not make a pre-auth feature-flag request on this path. Other commands
-    // retain the shared asynchronous registry refresh.
-    const isAuthLogin = process.argv[2] === "auth" && process.argv[3] === "login";
-    if (!isAuthLogin) {
-        runGlobalNetworkLifecycle(process.argv, () => {
-            void kickFlagRegistryReadiness({ sentry: Sentry });
-        });
-    }
+    // 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.
+    void kickFlagRegistryReadiness();
     // Set when a self-update re-exec'd this command on a newer CLI: the child
     // already did the work, so this process only has to carry its exit status
     // out (after the finally block's telemetry, hence not process.exit here).
     let reexecStatus = null;
-    let versionNudgeHandled = false;
     try {
-        runGlobalNetworkLifecycle(process.argv, () => Sentry.addBreadcrumb({
+        Sentry.addBreadcrumb({
             category: "command",
             message: sanitizeArgv(process.argv.slice(2)).join(" "),
             level: "info",
-        }));
+        });
         // Version handling, both halves. Skipped for inspection flags
         // (`--version`, `--help`) so users debugging a broken install can still
         // introspect what they have, and silent on any failure — neither half may
@@ -228,43 +148,33 @@ export async function runCli() {
         //    it (hq-pro's `updateRecommended` and the cached npm latest from
         //    `version-check.ts`); whichever fires first re-execs, and the child
         //    carries a guard env so it can never update again.
-        const versionAction = await runGlobalNetworkLifecycle(process.argv, async () => {
-            if (shouldSkipGate(process.argv))
-                return "continue";
-            const gate = (await foregroundNetworkBudget.waitFor(VERSION_GATE_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => enforceVersionGate(async (decision) => {
+        if (!shouldSkipGate(process.argv)) {
+            const gate = await 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 "reexec";
+                return;
             const cachedLatest = staleAgainstCachedLatest();
             if (cachedLatest) {
                 const outcome = await autoUpdateAndReexec(process.argv, cachedLatest);
                 if (outcome.action === "reexec") {
                     reexecStatus = outcome.reexecStatus ?? 0;
-                    return "reexec";
+                    return;
                 }
             }
-            return "continue";
-        });
-        if (versionAction === "reexec")
-            return;
-        // Commander exits immediately for its built-in --version action, before a
-        // nudge can be appended. Handle the global version-only form here so the
-        // installed semver stays the first stdout line and optional guidance follows.
-        if (process.argv.length === 3 &&
-            ["--version", "-V"].includes(process.argv[2] ?? "")) {
-            versionNudgeHandled = true;
-            await printVersionAndNudge();
-            return;
         }
-        // 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.
+        // 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.
         const registration = await registerCommandsWithRecovery({
             register: async () => {
                 const lazy = findLazyCommand(process.argv);
@@ -272,7 +182,8 @@ export async function runCli() {
                     await lazy.register(program);
                 }
                 else {
-                    registerCommandCatalog(program);
+                    const { registerAllCommands } = await import("./register-all.js");
+                    registerAllCommands(program);
                 }
             },
             argv: process.argv,
@@ -287,7 +198,6 @@ export async function runCli() {
             return;
         }
         await program.parseAsync();
-        maybeShowFirstSyncNextStep();
     }
     catch (err) {
         await handleTopLevelError(err);
@@ -295,38 +205,18 @@ export async function runCli() {
     finally {
         // Plan-limit nag (US-016): stderr-only, never throws, never touches
         // process.exitCode — safe to run after exit codes have been set.
-        await runGlobalNetworkLifecycle(process.argv, async () => {
-            emitPlanLimitNag();
-            // Release health: finalize the per-run session before the flush.
-            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. The budget reserves this 500 ms
-            // slice even when the command itself was long-running.
-            const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
-            const firstSyncOutcomeFlushes = takeFirstSyncStepOutcomes().map((outcome) => emitCliFirstSyncNextStepOutcome(outcome, releaseHealthTimeoutMs));
-            const inviteTeammateExposureFlushes = takePlanLimitInviteTeammateExposures().map((companyUid) => emitPlanLimitInviteTeammateExposure(companyUid, releaseHealthTimeoutMs));
-            const limitNoticeExposureFlushes = takeCliLimitNoticeExposures().map((exposure) => emitCliLimitNoticeExposure(exposure, releaseHealthTimeoutMs));
-            const limitNoticeEngagementFlushes = takeCliLimitNoticeEngagements().map((engagement) => emitCliLimitNoticeEngagement(engagement, releaseHealthTimeoutMs));
-            await settleWithin([
-                ...(versionNudgeHandled
-                    ? []
-                    : [refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs })]),
-                Sentry.flush(releaseHealthTimeoutMs),
-                ...firstSyncOutcomeFlushes,
-                ...inviteTeammateExposureFlushes,
-                ...limitNoticeExposureFlushes,
-                ...limitNoticeEngagementFlushes,
-            ], releaseHealthTimeoutMs);
-        });
+        emitPlanLimitNag();
+        // Release health: finalize the per-run session before the flush.
+        Sentry.endSession();
+        // 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);
         // 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 = {
@@ -358,9 +248,6 @@ function qmdSpawnFailureCaptureContext(err) {
 }
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export async function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies) {
-    // A typed plan gate, or an hq-cloud vault error carrying a plan-limit
-    // refusal (402 / PLAN_LIMIT_* from a sync, share or skill upload).
-    const planGate = planGateErrorFromVaultError(err);
     // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
     // (`hq … | head`, `source <(hq …)`, a parent that exited). That is normal
     // Unix behavior with no user-facing degradation — exit cleanly (0) and
@@ -433,78 +320,21 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         deps.stderr.write(`hq: ${callbackPortBusyMessage(err, DEFAULT_COGNITO.port ?? DEFAULT_CALLBACK_PORT)}\n`);
         deps.setExitCode(1);
     }
-    else if (planGate) {
-        // Plan denials are expected product limits, never a CLI crash. The
-        // server URL is always shown. Company refusals that the Workforce
-        // checkout satisfies retain the direct Stripe checkout action.
-        //
-        // A plan-limit refusal (a Starter hard stop) always prints its reason,
-        // usage and fix options, even non-interactively: the user can fix it
-        // without upgrading, and an agent or script reading stderr needs the
-        // reason to act on it. Feature refusals keep the URL-only
-        // non-interactive form, because upgrading is their only fix.
-        const interactive = deps.interactive ?? canOfferTeamUpgrade(deps.argv);
-        const message = formatPlanGateError(planGate, {
-            urlOnly: !interactive && planGate.code !== "PLAN_LIMIT_EXCEEDED",
-        });
-        deps.stderr.write(interactive ? `hq: ${message}\n` : `${message}\n`);
-        const promptExposure = isCliLimitResourceKind(planGate.details.resource ?? "")
-            ? queueCliLimitNoticeExposure(planGate.details.resource, "refusal", planGate.details.companyUid)
-            : null;
+    else if (isPlanGateError(err)) {
+        // hq-pro's plan denials are expected product limits, never a CLI crash.
+        // The shared vault client has already decoded and typed the small safe
+        // envelope; do not expose its raw body or retry a rejected creation.
+        deps.stderr.write(`hq: ${formatPlanGateError(err)}\n`);
         deps.setExitCode(1);
-        if (interactive && planGate.details.upgradeUrl) {
-            const companyUid = planGate.details.companyUid;
-            const isCompanyWorkforceCheckout = typeof companyUid === "string" &&
-                /^cmp_[A-Za-z0-9_-]+$/.test(companyUid) &&
-                (planGate.code === "PLAN_REQUIRED" ||
-                    planGate.code === "MEETING_PLAN_REQUIRED" ||
-                    planGate.code === "BILLING_REQUIRED");
-            if (isCompanyWorkforceCheckout && companyUid) {
-                try {
-                    const upgraded = await offerTeamUpgrade(async () => {
-                        await (deps.upgradeToTeam ?? upgradeToTeam)({ companyUid });
-                    }, {
-                        interactive: true,
-                        argv: deps.argv,
-                        ask: deps.ask,
-                    });
-                    if (upgraded)
-                        queueCliLimitNoticeEngagement(promptExposure);
-                }
-                catch (upgradeErr) {
-                    const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
-                    deps.stderr.write(`hq: ${message}\n`);
-                    try {
-                        const opened = await offerUpgradeLink(planGate.details.upgradeUrl, {
-                            interactive: true,
-                            argv: deps.argv,
-                            ask: deps.ask,
-                            openUrl: deps.openUrl,
-                        });
-                        if (opened)
-                            queueCliLimitNoticeEngagement(promptExposure);
-                    }
-                    catch (linkErr) {
-                        const linkMessage = linkErr instanceof Error ? linkErr.message : String(linkErr);
-                        deps.stderr.write(`hq: ${linkMessage}\n`);
-                    }
-                }
+        if (canOfferTeamUpgrade()) {
+            try {
+                await offerTeamUpgrade(async () => {
+                    await upgradeToTeam({ companyUid: err.details.companyUid });
+                });
             }
-            else {
-                try {
-                    const opened = await offerUpgradeLink(planGate.details.upgradeUrl, {
-                        interactive: true,
-                        argv: deps.argv,
-                        ask: deps.ask,
-                        openUrl: deps.openUrl,
-                    });
-                    if (opened)
-                        queueCliLimitNoticeEngagement(promptExposure);
-                }
-                catch (upgradeErr) {
-                    const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
-                    deps.stderr.write(`hq: ${message}\n`);
-                }
+            catch (upgradeErr) {
+                const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
+                deps.stderr.write(`hq: ${message}\n`);
             }
         }
     }
@@ -735,9 +565,8 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // install left a bundled file unwritten (HQ-CLI-1N, a CJS relative-sibling
         // MODULE_NOT_FOUND; HQ-CLI-1Q, a CJS BARE-specifier MODULE_NOT_FOUND for a
         // dependency the requiring third-party package's own manifest declares), or
-        // a concurrent global install rewrote the running tree so a module present
-        // at resolve was gone at read (HQ-CLI-1M, an esm-loader ENOENT; HQ-CLI-20,
-        // its CJS loader-read twin).
+        // a concurrent global install rewrote the running tree so an ESM module
+        // present at resolve was gone at read (HQ-CLI-1M, an esm-loader ENOENT).
         // All carry no hq-cli frames and reached the final else, filing a bare
         // crash and an unactionable line. An incomplete install is the caller's
         // machine, the disposition HQ-CLI-Y already established for the qmd CHILD —
@@ -745,12 +574,11 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // environmental family (after the typed qmd carriers and the hq state-write
         // carrier, before environmentalFsErrorMessage): the signatures are disjoint
         // — ENVIRONMENTAL_FS_CODES is only ENOSPC/EDQUOT/EROFS (never
-        // ENOENT/MODULE_NOT_FOUND), no qmd carrier sets requireStack or a loader
-        // source-read frame (esm/load or cjs/loader), and the classified file must
-        // sit under <packageRoot>/node_modules — so ordering changes nothing that
-        // exists. The
+        // ENOENT/MODULE_NOT_FOUND), no qmd carrier sets requireStack or an
+        // esm-loader frame, and the classified file must sit under
+        // <packageRoot>/node_modules — so ordering changes nothing that exists. The
         // UNATTRIBUTABLE shapes are deliberately NOT suppressed and are captured
-        // WITH bounded context on the generic path below: a loader/resolver ENOENT
+        // WITH bounded context on the generic path below: an esm-loader ENOENT
         // whose path did not survive, and a bare miss the requirer does NOT declare
         // (a possible undeclared/peer dependency, now named in the context).
         const incompleteInstallMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || storeMissingMsg || storeUnopenableMsg || queryDocumentMsg || modelDownloadMsg || workdirMissingMsg || stateWriteMsg
@@ -802,14 +630,6 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             lockMsg
             ? null
             : networkTransportErrorMessage(err);
-        // Windows EPERM/EACCES/EBUSY/UNKNOWN filesystem failures are not proven
-        // caller-owned conditions. Keep them at error level and attach bounded,
-        // installation-independent context so OneDrive/antivirus/path-length
-        // hypotheses can be separated without creating one issue per host path.
-        const checkpointStampContext = checkpointStampWriteCaptureContext(err);
-        const checkpointStampMessage = checkpointStampWriteMessage(err);
-        const fsContext = filesystemErrorCaptureContext(err);
-        const fsMsg = fsContext ? filesystemErrorMessage(err) : null;
         if (qmdMsg) {
             deps.stderr.write(`hq: ${qmdMsg}\n`);
         }
@@ -855,31 +675,18 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (transportMsg) {
             deps.stderr.write(`hq: ${transportMsg}\n`);
         }
-        else if (checkpointStampContext && checkpointStampMessage) {
-            deps.sentry.captureException(err, checkpointStampContext);
-            deps.stderr.write(`hq: ${checkpointStampMessage}\n`);
-        }
-        else if (fsMsg && fsContext) {
-            deps.sentry.captureException(err, fsContext);
-            deps.stderr.write(`hq: ${fsMsg}\n`);
-        }
         else {
             // A genuinely unclassified fault is still captured exactly once. Two
             // shapes attach bounded, hq-derived context so the next occurrence
             // carries the evidence this one lacked: a qmd spawn-level failure the fix
-            // could not attribute (HQ-CLI-1A), and a loader/resolver ENOENT whose path
-            // did not survive delivery (HQ-CLI-1M esm-load, HQ-CLI-1S resolve-time,
-            // HQ-CLI-20 CJS load-time — the unattributable incomplete-install shape).
-            // Every other error captures bare, exactly as before.
+            // could not attribute (HQ-CLI-1A), and an esm-loader ENOENT whose path
+            // did not survive delivery (HQ-CLI-1M — the unattributable incomplete-
+            // install shape). Every other error captures bare, exactly as before.
             const spawnContext = qmdSpawnFailureCaptureContext(err);
             const installContext = incompleteInstallCaptureContext(err);
-            const qmdContext = qmdExitCaptureContext(err);
-            if (spawnContext || installContext || qmdContext) {
+            if (spawnContext || installContext) {
                 deps.sentry.captureException(err, {
-                    ...qmdContext,
-                    ...((spawnContext || installContext)
-                        ? { contexts: { ...spawnContext?.contexts, ...installContext } }
-                        : {}),
+                    contexts: { ...spawnContext?.contexts, ...installContext },
                 });
             }
             else {

package/dist/node-network-compat.d.ts

@@ -1,3 +1,31 @@
-/** Unconditional compatibility setup for the full CLI command graph. */
-export { configureNodeNetworkCompatibility, HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS, type NodeNetworkCompatibilityOptions, } from "./node-network-compat-core.js";
+/**
+ * Node network defaults for HQ CLI entry points.
+ *
+ * Node's default 250 ms address-family attempt window can fail on hosts where
+ * IPv6 is advertised but black-holed. On affected WSL installations, undici's
+ * fetch() reaches ETIMEDOUT before its usable IPv4 path completes. A 1 second
+ * window fixes the connection while retaining Node's automatic family choice.
+ *
+ * Keep this module dependency-free and import it immediately after the Node
+ * version preflight. Operators can retain a custom value through NODE_OPTIONS
+ * or a direct Node CLI option; HQ only supplies the compatibility default when
+ * neither is present.
+ *
+ * Use a namespace import of `node:net` (not a static named import of
+ * `setDefaultAutoSelectFamilyAttemptTimeout`). Named ESM imports are linked
+ * before any entry-module body runs — including `node-preflight` — so importing
+ * a Node 18.13+/20.4+ API by name would turn unsupported runtimes into a
+ * module-link SyntaxError instead of the preflight's upgrade message.
+ */
+export declare const HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS = 1000;
+export interface NodeNetworkCompatibilityOptions {
+    nodeOptions?: string;
+    execArgv?: readonly string[];
+    /**
+     * Inject the net timeout setter (tests). Pass `null` to simulate a runtime
+     * that lacks `setDefaultAutoSelectFamilyAttemptTimeout`.
+     */
+    setAttemptTimeout?: ((milliseconds: number) => void) | null;
+}
+export declare function configureNodeNetworkCompatibility(options?: NodeNetworkCompatibilityOptions): boolean;
 //# sourceMappingURL=node-network-compat.d.ts.map

package/dist/node-network-compat.js

@@ -1,5 +1,52 @@
-/** Unconditional compatibility setup for the full CLI command graph. */
-import { configureNodeNetworkCompatibilityOnce } from "./node-network-compat-core.js";
-export { configureNodeNetworkCompatibility, HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS, } from "./node-network-compat-core.js";
-configureNodeNetworkCompatibilityOnce();
+/**
+ * Node network defaults for HQ CLI entry points.
+ *
+ * Node's default 250 ms address-family attempt window can fail on hosts where
+ * IPv6 is advertised but black-holed. On affected WSL installations, undici's
+ * fetch() reaches ETIMEDOUT before its usable IPv4 path completes. A 1 second
+ * window fixes the connection while retaining Node's automatic family choice.
+ *
+ * Keep this module dependency-free and import it immediately after the Node
+ * version preflight. Operators can retain a custom value through NODE_OPTIONS
+ * or a direct Node CLI option; HQ only supplies the compatibility default when
+ * neither is present.
+ *
+ * Use a namespace import of `node:net` (not a static named import of
+ * `setDefaultAutoSelectFamilyAttemptTimeout`). Named ESM imports are linked
+ * before any entry-module body runs — including `node-preflight` — so importing
+ * a Node 18.13+/20.4+ API by name would turn unsupported runtimes into a
+ * module-link SyntaxError instead of the preflight's upgrade message.
+ */
+import * as nodeNet from "node:net";
+export const HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS = 1000;
+const ATTEMPT_TIMEOUT_OPTION = "--network-family-autoselection-attempt-timeout";
+function hasExplicitAttemptTimeout(nodeOptions, execArgv) {
+    const optionPattern = new RegExp(`(?:^|\\s)${ATTEMPT_TIMEOUT_OPTION}(?:=|\\s|$)`);
+    return (optionPattern.test(nodeOptions) ||
+        execArgv.some((argument) => argument === ATTEMPT_TIMEOUT_OPTION ||
+            argument.startsWith(`${ATTEMPT_TIMEOUT_OPTION}=`)));
+}
+function resolveSetAttemptTimeout(override) {
+    if (override === null)
+        return undefined;
+    if (override)
+        return override;
+    const fn = nodeNet.setDefaultAutoSelectFamilyAttemptTimeout;
+    return typeof fn === "function" ? fn.bind(nodeNet) : undefined;
+}
+export function configureNodeNetworkCompatibility(options = {}) {
+    const nodeOptions = options.nodeOptions ?? process.env.NODE_OPTIONS ?? "";
+    const execArgv = options.execArgv ?? process.execArgv;
+    if (hasExplicitAttemptTimeout(nodeOptions, execArgv)) {
+        return false;
+    }
+    const setAttemptTimeout = resolveSetAttemptTimeout(options.setAttemptTimeout);
+    if (!setAttemptTimeout) {
+        // Runtime lacks the API (pre-Node 18.13 / preflight should already have exited).
+        return false;
+    }
+    setAttemptTimeout(HQ_NETWORK_FAMILY_ATTEMPT_TIMEOUT_MS);
+    return true;
+}
+configureNodeNetworkCompatibility();
 //# sourceMappingURL=node-network-compat.js.map

package/dist/node-preflight.d.ts

@@ -23,12 +23,6 @@ export interface NodeVersionCheck {
     major: number;
     message?: string;
 }
-export interface NodePreflightOptions {
-    versionString?: string;
-    skip?: string;
-    stderr?: Pick<NodeJS.WriteStream, "write">;
-    exit?: (code: number) => void;
-}
 /**
  * Pure check: is the given Node version string (e.g. "18.19.0") supported?
  * Defaults to the running runtime's version. An unparseable version is treated
@@ -41,5 +35,5 @@ export declare function checkNodeVersion(versionString?: string): NodeVersionChe
  * `HQ_SKIP_NODE_PREFLIGHT=1` to bypass (used by the test runner, which already
  * runs on a supported Node).
  */
-export declare function enforceNodeVersion(options?: NodePreflightOptions): void;
+export declare function enforceNodeVersion(): void;
 //# sourceMappingURL=node-preflight.d.ts.map