@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/workers-registry/read.js

@@ -0,0 +1,17 @@
+/**
+ * Reader for the auto-generated core/workers/registry.yaml (see ./index.ts
+ * for the generator). Lives in lib so bot code can use it without importing
+ * a command module.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseUserYaml } from "../../utils/user-yaml-error.js";
+/** Read + parse the worker registry. Empty array if it does not exist. */
+export function readWorkerRegistry(hqRoot) {
+    const p = path.join(hqRoot, "core/workers/registry.yaml");
+    if (!fs.existsSync(p))
+        return [];
+    const doc = parseUserYaml(fs.readFileSync(p, "utf8"), p);
+    return doc?.workers ?? [];
+}
+//# sourceMappingURL=read.js.map

package/dist/main.d.ts

@@ -5,6 +5,32 @@
 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;
+/**
+ * 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.
+ */
+declare class ForegroundNetworkBudget {
+    private readonly budgetMs;
+    private readonly now;
+    private consumedMs;
+    constructor(budgetMs?: number, now?: () => number);
+    timeoutFor(phaseMaximumMs: number, reservedMs?: number): number;
+    waitFor<T>(phaseMaximumMs: number, reservedMs: number, work: (timeoutMs: number) => Promise<T>): Promise<T | undefined>;
+}
+/** Create a shared invocation budget; exported so the time accounting is directly testable. */
+export declare function createForegroundNetworkBudget(options?: {
+    budgetMs?: number;
+    now?: () => number;
+}): ForegroundNetworkBudget;
 export type StreamErrorDependencies = {
     stderr: Pick<typeof process.stderr, "write">;
     exit: (code: number) => void;
@@ -15,7 +41,13 @@ 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>;
+export {};
 //# sourceMappingURL=main.d.ts.map

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 { 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 { environmentalFsErrorMessage, filesystemErrorCaptureContext, filesystemErrorMessage, } 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,7 +24,9 @@ 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";
@@ -35,14 +37,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, isPlanGateError, offerTeamUpgrade, } from "./utils/plan-gate-error.js";
+import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
-import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
+import { printVersionAndNudge, 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 } from "./lazy-commands.js";
-import { emitCliSessionStarted } from "./utils/cli-telemetry.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 { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
@@ -52,8 +54,68 @@ 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;
+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));
+        }
+    }
+}
+/** Create a shared invocation budget; exported so the time accounting is directly testable. */
+export function createForegroundNetworkBudget(options = {}) {
+    if (options.budgetMs === undefined && options.now === undefined) {
+        return new ForegroundNetworkBudget();
+    }
+    return new ForegroundNetworkBudget(options.budgetMs ?? FOREGROUND_NETWORK_BUDGET_MS, options.now ?? (() => performance.now()));
+}
+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
@@ -102,39 +164,64 @@ export function handleStreamError(err, deps = defaultStreamErrorDependencies) {
 }
 process.stdout.on("error", (err) => handleStreamError(err));
 process.stderr.on("error", (err) => handleStreamError(err));
-initSentry();
+runGlobalNetworkLifecycle(process.argv, () => initSentry());
 const program = new Command();
 program
     .name("hq")
     .description("HQ management CLI — modules, packages, and cloud sync")
-    .version(CLI_VERSION);
+    .version(CLI_VERSION)
+    .option("--verbose", "Show verbose diagnostics, including SDK runtime warnings");
 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. 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.
+    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 }),
+        ]));
+    });
 });
 export async function runCli() {
-    // 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();
+    const foregroundNetworkBudget = createForegroundNetworkBudget();
+    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 });
+        });
+    }
     // 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 {
-        Sentry.addBreadcrumb({
+        runGlobalNetworkLifecycle(process.argv, () => 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
@@ -148,33 +235,43 @@ 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.
-        if (!shouldSkipGate(process.argv)) {
-            const gate = await enforceVersionGate(async (decision) => {
+        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) => {
                 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;
+                return "reexec";
             const cachedLatest = staleAgainstCachedLatest();
             if (cachedLatest) {
                 const outcome = await autoUpdateAndReexec(process.argv, cachedLatest);
                 if (outcome.action === "reexec") {
                     reexecStatus = outcome.reexecStatus ?? 0;
-                    return;
+                    return "reexec";
                 }
             }
+            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 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 +279,7 @@ export async function runCli() {
                     await lazy.register(program);
                 }
                 else {
-                    const { registerAllCommands } = await import("./register-all.js");
-                    registerAllCommands(program);
+                    registerCommandCatalog(program);
                 }
             },
             argv: process.argv,
@@ -198,6 +294,7 @@ export async function runCli() {
             return;
         }
         await program.parseAsync();
+        maybeShowFirstSyncNextStep();
     }
     catch (err) {
         await handleTopLevelError(err);
@@ -205,18 +302,38 @@ 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.
-        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);
+        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);
+        });
         // 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 = {
@@ -248,6 +365,9 @@ 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
@@ -320,21 +440,78 @@ 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 (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`);
+    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;
         deps.setExitCode(1);
-        if (canOfferTeamUpgrade()) {
-            try {
-                await offerTeamUpgrade(async () => {
-                    await upgradeToTeam({ companyUid: err.details.companyUid });
-                });
+        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`);
+                    }
+                }
             }
-            catch (upgradeErr) {
-                const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
-                deps.stderr.write(`hq: ${message}\n`);
+            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`);
+                }
             }
         }
     }
@@ -565,8 +742,9 @@ 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 an ESM module
-        // present at resolve was gone at read (HQ-CLI-1M, an esm-loader ENOENT).
+        // 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).
         // 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 —
@@ -574,11 +752,12 @@ 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 an
-        // esm-loader frame, 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 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
         // UNATTRIBUTABLE shapes are deliberately NOT suppressed and are captured
-        // WITH bounded context on the generic path below: an esm-loader ENOENT
+        // WITH bounded context on the generic path below: a loader/resolver 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
@@ -630,6 +809,14 @@ 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`);
         }
@@ -675,18 +862,31 @@ 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 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.
+            // 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.
             const spawnContext = qmdSpawnFailureCaptureContext(err);
             const installContext = incompleteInstallCaptureContext(err);
-            if (spawnContext || installContext) {
+            const qmdContext = qmdExitCaptureContext(err);
+            if (spawnContext || installContext || qmdContext) {
                 deps.sentry.captureException(err, {
-                    contexts: { ...spawnContext?.contexts, ...installContext },
+                    ...qmdContext,
+                    ...((spawnContext || installContext)
+                        ? { contexts: { ...spawnContext?.contexts, ...installContext } }
+                        : {}),
                 });
             }
             else {

package/dist/native-fast-route.d.ts

@@ -0,0 +1,7 @@
+/** Default-off flag check for native entrypoint routes. */
+export declare function nativeFastRouteEnabled(argv: readonly string[], env?: NodeJS.ProcessEnv): Promise<boolean>;
+/** Reads a default-off fast-route gate from its local override or fresh snapshot. */
+export declare function fastFlagEnabled(flagKey: string, env?: NodeJS.ProcessEnv, options?: {
+    numericEnvironmentOverride?: boolean;
+}): Promise<boolean>;
+//# sourceMappingURL=native-fast-route.d.ts.map

package/dist/native-fast-route.js

@@ -0,0 +1,45 @@
+/** Default-off flag check for native entrypoint routes. */
+import { localOverrideEnvVar, readLocalOverride } from "@indigoai-us/hq-flags-client";
+import { parseFastCore } from "./fast-scaffold.js";
+export async function nativeFastRouteEnabled(argv, env = process.env) {
+    const parsed = parseFastCore(argv);
+    if (!parsed || parsed.entry.kind !== "native")
+        return false;
+    return fastFlagEnabled(parsed.entry.flagKey, env);
+}
+/** Reads a default-off fast-route gate from its local override or fresh snapshot. */
+export async function fastFlagEnabled(flagKey, env = process.env, options = {}) {
+    const override = nativeRouteOverride(flagKey, env, options.numericEnvironmentOverride !== false);
+    if (override !== null)
+        return override;
+    try {
+        const [{ resolveProcessFlagCompanyContext }, { readFlagSnapshotFile }] = await Promise.all([
+            import("./lib/process-flag-company-context.js"),
+            import("./lib/flag-snapshot-file.js"),
+        ]);
+        const { companyUid } = resolveProcessFlagCompanyContext(env);
+        if (!companyUid)
+            return false;
+        return readFlagSnapshotFile(companyUid, { env })?.flags[flagKey] === true;
+    }
+    catch {
+        // The new path is a rollout optimization. Any unavailable local scope or
+        // cache data leaves the established full-graph route in control.
+        return false;
+    }
+}
+/** The route's documented CLI override also accepts the conventional 1/0. */
+function nativeRouteOverride(flagKey, env, numericEnvironmentOverride) {
+    const override = readLocalOverride(flagKey, env);
+    if (override !== null)
+        return override;
+    if (numericEnvironmentOverride) {
+        const raw = env[localOverrideEnvVar(flagKey)];
+        if (raw === "1")
+            return true;
+        if (raw === "0")
+            return false;
+    }
+    return null;
+}
+//# sourceMappingURL=native-fast-route.js.map

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

@@ -0,0 +1,12 @@
+/** Node network defaults shared by the full graph and the selective fast path. */
+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 without it. */
+    setAttemptTimeout?: ((milliseconds: number) => void) | null;
+}
+export declare function configureNodeNetworkCompatibility(options?: NodeNetworkCompatibilityOptions): boolean;
+/** Apply at most once when both entrypoint routing layers import this module. */
+export declare function configureNodeNetworkCompatibilityOnce(): boolean;
+//# sourceMappingURL=node-network-compat-core.d.ts.map