@indigoai-us/hq-cli 5.345.69 → 5.345.70

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+## [5.345.70] — 2026-10-10
+- Native `hq core` fast-route imports now use the bounded torn-install recovery path. If an update temporarily removes a route module, the CLI waits for the package tree to settle and re-executes once; a module that remains missing prints the reinstall remedy.
+
 ## [5.345.69] — 2026-10-10
 - Supported native core handlers now run by default without a flag snapshot. Explicit false values still turn them off; delegate and worker-skills remain default-off pending parity.
 

package/dist/fast-core.d.ts

@@ -7,17 +7,26 @@
  * module. The registration in `core.ts` remains the complete fallback path.
  */
 import { parseFastCore } from "./fast-scaffold.js";
+type RecoveredModule<T> = {
+    module?: T;
+    reexecStatus?: number;
+};
+type RecoverFastImportOptions = {
+    reexecOnSettled?: boolean;
+};
+type RecoverFastImport = <T>(load: () => Promise<T>, options?: RecoverFastImportOptions) => Promise<RecoveredModule<T>>;
 export declare function readStdinIfPiped(stream: NodeJS.ReadStream, maxBytes?: number): Promise<string>;
 /**
  * Run the fast-path core command named in `argv` and exit with its code.
  * Only call when {@link isFastCoreRequest} is true; a non-match returns without
  * doing anything.
  */
-export declare function runFastCore(argv: readonly string[], parsed?: ReturnType<typeof parseFastCore>): Promise<void>;
+export declare function runFastCore(argv: readonly string[], parsed?: ReturnType<typeof parseFastCore>, recoverImport?: RecoverFastImport): Promise<void>;
 /**
  * Resolve valid explicit roots for the two measured hook routes without loading
  * the general root resolver. Anything uncertain falls through to that resolver,
  * which retains its diagnostics and cwd-discovery behavior.
  */
 export declare function resolveExplicitFastLiveRoot(hqRootArg: string | undefined, env: NodeJS.ProcessEnv): string | undefined;
+export {};
 //# sourceMappingURL=fast-core.d.ts.map

package/dist/fast-core.js

@@ -33,7 +33,7 @@ export async function readStdinIfPiped(stream, maxBytes) {
  * Only call when {@link isFastCoreRequest} is true; a non-match returns without
  * doing anything.
  */
-export async function runFastCore(argv, parsed = parseFastCore(argv)) {
+export async function runFastCore(argv, parsed = parseFastCore(argv), recoverImport = async (load) => ({ module: await load() })) {
     if (!parsed)
         return;
     const profile = wantsFastRouteProfile(process.env);
@@ -54,7 +54,14 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
             familyEnabled = envOverride;
         }
         else {
-            const { fastFlagEnabled, fastFlagEnabledDefaultOn } = await import("./native-fast-route.js");
+            const loaded = await recoverImport(() => import("./native-fast-route.js"));
+            if (loaded.reexecStatus !== undefined) {
+                process.exitCode = loaded.reexecStatus;
+                return;
+            }
+            if (!loaded.module)
+                throw new Error("Native fast-route module did not load");
+            const { fastFlagEnabled, fastFlagEnabledDefaultOn } = loaded.module;
             const readFamilyFlag = isDefaultOnFastFamily(entry.familyFlagKey)
                 ? fastFlagEnabledDefaultOn
                 : fastFlagEnabled;
@@ -62,15 +69,28 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
         }
     }
     if (entry.kind === "native" && entry.fallbackToCommandGraph && !familyEnabled) {
-        const { runCli } = await import("./main.js");
-        await runCli();
+        const loaded = await recoverImport(() => import("./main.js"));
+        if (loaded.reexecStatus !== undefined) {
+            process.exitCode = loaded.reexecStatus;
+            return;
+        }
+        if (!loaded.module)
+            throw new Error("Main command graph did not load");
+        await loaded.module.runCli();
         return;
     }
     familyFlagMs = profileElapsed(profileStart, profileMark());
     const useShell = entry.kind === "native" && Boolean(entry.familyFlagKey) && !familyEnabled;
     let worktreeScopeFixEnabled;
     if (entry.name === "repo-run-registry") {
-        const { coreRrrWorktreeScopeFixFastFlagEnabled } = await import("./commands/core-rrr-worktree-scope-fix-fast-flag.js");
+        const loaded = await recoverImport(() => import("./commands/core-rrr-worktree-scope-fix-fast-flag.js"));
+        if (loaded.reexecStatus !== undefined) {
+            process.exitCode = loaded.reexecStatus;
+            return;
+        }
+        if (!loaded.module)
+            throw new Error("Repo-run-registry flag module did not load");
+        const { coreRrrWorktreeScopeFixFastFlagEnabled } = loaded.module;
         worktreeScopeFixEnabled = await coreRrrWorktreeScopeFixFastFlagEnabled(process.env);
     }
     const shouldInjectRoot = useShell
@@ -96,14 +116,27 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
             hqRoot = shortcutRoot;
         }
         else {
-            const { resolveLiveRoot } = await import("./utils/hq-roots-core.js");
+            const loaded = await recoverImport(() => import("./utils/hq-roots-core.js"));
+            if (loaded.reexecStatus !== undefined) {
+                process.exitCode = loaded.reexecStatus;
+                return;
+            }
+            if (!loaded.module)
+                throw new Error("HQ root resolver did not load");
+            const { resolveLiveRoot } = loaded.module;
             try {
                 hqRoot = resolveLiveRoot(parsed.hqRootArg ? { hqRoot: parsed.hqRootArg } : {});
             }
             catch {
                 if (entry.kind === "native") {
-                    const { runCli } = await import("./main.js");
-                    await runCli();
+                    const loaded = await recoverImport(() => import("./main.js"));
+                    if (loaded.reexecStatus !== undefined) {
+                        process.exitCode = loaded.reexecStatus;
+                        return;
+                    }
+                    if (!loaded.module)
+                        throw new Error("Main command graph did not load");
+                    await loaded.module.runCli();
                     return;
                 }
                 hqRoot = undefined;
@@ -113,9 +146,22 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
     rootResolutionMs = profileElapsed(rootResolutionStartedAt, profileMark());
     if (entry.kind === "native" && !useShell) {
         const handlerImportStartedAt = profileMark();
-        const { installFastPathStreamErrorHandlers } = await import("./utils/fast-stream-errors.js");
-        installFastPathStreamErrorHandlers();
-        const handlerModule = await import(entry.modulePath);
+        const errorHandlers = await recoverImport(() => import("./utils/fast-stream-errors.js"));
+        if (errorHandlers.reexecStatus !== undefined) {
+            process.exitCode = errorHandlers.reexecStatus;
+            return;
+        }
+        if (!errorHandlers.module)
+            throw new Error("Fast-path stream error handlers did not load");
+        errorHandlers.module.installFastPathStreamErrorHandlers();
+        const loadedHandler = await recoverImport(() => import(entry.modulePath));
+        if (loadedHandler.reexecStatus !== undefined) {
+            process.exitCode = loadedHandler.reexecStatus;
+            return;
+        }
+        if (!loadedHandler.module)
+            throw new Error("Native fast handler module did not load");
+        const handlerModule = loadedHandler.module;
         const handler = handlerModule[entry.exportName];
         if (typeof handler !== "function") {
             throw new Error(`Native fast handler ${entry.exportName} was not exported`);
@@ -140,8 +186,16 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
             if (!entry.fallbackToCommandGraph) {
                 throw new Error(`Native fast handler ${entry.exportName} requested an unavailable command-graph fallback`);
             }
-            const { runCli } = await import("./main.js");
-            await runCli();
+            // The fast handler has already run (and may have consumed stdin). If a
+            // torn main import is detected now, report it without replaying the command.
+            const loaded = await recoverImport(() => import("./main.js"), { reexecOnSettled: false });
+            if (loaded.reexecStatus !== undefined) {
+                process.exitCode = loaded.reexecStatus;
+                return;
+            }
+            if (!loaded.module)
+                throw new Error("Main command graph did not load");
+            await loaded.module.runCli();
             return;
         }
         // Let Node drain handler output before terminating. The timeout guard's
@@ -167,7 +221,14 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
         ...(entry.name === "repo-run-registry" ? { HQ_FLAG_CORE_RRR_WORKTREE_SCOPE_FIX: String(worktreeScopeFixEnabled) } : {}),
     };
     // Keep the rollback runner off native commands' import path.
-    const { runBundledScript } = await import("./utils/run-bundled-script.js");
+    const runner = await recoverImport(() => import("./utils/run-bundled-script.js"));
+    if (runner.reexecStatus !== undefined) {
+        process.exitCode = runner.reexecStatus;
+        return;
+    }
+    if (!runner.module)
+        throw new Error("Bundled-script runner did not load");
+    const { runBundledScript } = runner.module;
     const { code } = runBundledScript({
         asset,
         args: parsed.args,

package/dist/index.js

@@ -59,6 +59,80 @@ async function runMainWithInstallTreeRecovery() {
         throw error;
     }
 }
+/**
+ * Fast-route imports happen before main.ts command registration, so the
+ * registration recovery seam cannot see a torn fast module unless each import
+ * is run through the same bounded recovery boundary. Imports before handler
+ * execution may re-exec after a settled repair; the post-handler fallback passes
+ * reexecOnSettled=false so a torn main import is reported without replaying the
+ * handler or losing the stdin it already consumed.
+ */
+const recoverFastImport = async (load, options = {}) => {
+    try {
+        return { module: await load() };
+    }
+    catch {
+        // Keep the clean hook path free of startup-registration's update-lock and
+        // package-root imports. Only a failed import pays for the recovery seam.
+        const { registerCommandsWithRecovery } = await import("./startup-registration.js");
+        let module;
+        try {
+            const result = await registerCommandsWithRecovery({
+                register: async () => {
+                    module = await load();
+                },
+                argv: process.argv,
+                env: process.env,
+                entryPath: fileURLToPath(import.meta.url),
+                stderr: process.stderr,
+                reexecOnSettled: options.reexecOnSettled,
+            });
+            return result.reexecStatus === undefined
+                ? { module }
+                : { reexecStatus: result.reexecStatus };
+        }
+        catch (error) {
+            // Fast-route imports precede main.ts/Sentry initialization. When recovery
+            // cannot repair a still-absent module, report it here as the registration
+            // path does instead of relying on the later unhandled-rejection boundary.
+            const installTree = await import("./utils/install-tree-torn.js");
+            if (!installTree.isInstallTreeTornError(error))
+                throw error;
+            process.stderr.write(`${installTree.installTreeTornStderrLine(error)}\n`);
+            const sentry = await import("./sentry.js");
+            sentry.initSentry();
+            sentry.Sentry.captureException(error, installTree.installTreeTornCaptureContext(error));
+            sentry.finishSentrySession();
+            await sentry.Sentry.flush(2_000);
+            return { reexecStatus: 1 };
+        }
+    }
+};
+async function runFastCoreWithRecovery(parsed) {
+    const loaded = await recoverFastImport(() => import("./fast-core.js"));
+    if (loaded.reexecStatus !== undefined) {
+        process.exitCode = loaded.reexecStatus;
+        return;
+    }
+    if (!loaded.module)
+        throw new Error("Fast core module did not load");
+    await loaded.module.runFastCore(process.argv, parsed, recoverFastImport);
+}
+async function runNativeFastRouteWithRecovery(parsed) {
+    const loaded = await recoverFastImport(() => import("./native-fast-route.js"));
+    if (loaded.reexecStatus !== undefined) {
+        process.exitCode = loaded.reexecStatus;
+        return;
+    }
+    if (!loaded.module)
+        throw new Error("Native fast-route module did not load");
+    if (await loaded.module.nativeFastRouteEnabled(process.argv)) {
+        await runFastCoreWithRecovery(parsed);
+    }
+    else {
+        await runMainWithInstallTreeRecovery();
+    }
+}
 function dispatchCliEntry() {
     const versionRequest = isVersionRequest(process.argv);
     const helpRequest = !versionRequest && isCommandHelpRequest(process.argv);
@@ -99,21 +173,13 @@ function dispatchCliEntry() {
         // An explicit enabled override has already decided the global gate. Skip the
         // snapshot reader import on hot native plumbing paths; runFastCore still
         // checks the command-family flag before choosing native or shell rollback.
-        void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv, parsedFastCore));
+        void runFastCoreWithRecovery(parsedFastCore);
     }
     else if (parsedFastCore?.entry.kind === "native") {
         // Native routes are default-off. Resolve the company-scoped persisted flag
         // without loading the command graph; a miss or stale snapshot takes the
         // existing full-graph route.
-        void import("./native-fast-route.js").then(async ({ nativeFastRouteEnabled }) => {
-            if (await nativeFastRouteEnabled(process.argv)) {
-                const { runFastCore } = await import("./fast-core.js");
-                await runFastCore(process.argv, parsedFastCore);
-            }
-            else {
-                await runMainWithInstallTreeRecovery();
-            }
-        });
+        void runNativeFastRouteWithRecovery(parsedFastCore);
     }
     else if (parseSecretsEnvFastRequest(process.argv)) {
         const request = parseSecretsEnvFastRequest(process.argv);
@@ -138,7 +204,7 @@ function dispatchCliEntry() {
         // Hot relocated plumbing (`hq core hq-session`, `hq core checkpoint-stop-gate`)
         // dispatches straight to the bundled-script runner, so it never pays for the
         // ~60-module command graph main.ts imports. See src/fast-scaffold.ts.
-        void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv, parsedFastCore));
+        void runFastCoreWithRecovery(parsedFastCore);
     }
     else {
         // Keep the command lifecycle detached from module evaluation, as it was

package/dist/startup-registration.d.ts

@@ -88,6 +88,8 @@ export interface RegisterCommandsWithRecoveryArgs {
     /** The RUNNING install's own `dist/index.js` — the safe re-exec target. */
     entryPath: string;
     stderr: Pick<typeof process.stderr, "write">;
+    /** False when command execution already happened and must not be replayed. */
+    reexecOnSettled?: boolean;
     deps?: RegisterRecoveryDeps;
 }
 export interface RegisterCommandsWithRecoveryResult {

package/dist/startup-registration.js

@@ -179,6 +179,26 @@ export async function registerCommandsWithRecovery(args) {
         const treeState = result.sawLock || result.sawRetired || result.sawTreeChange
             ? "in_flight"
             : "stale";
+        if (args.reexecOnSettled === false) {
+            throw new InstallTreeTornError({
+                cause: err,
+                classified,
+                packageRoot,
+                versionGatePhase: readVersionGatePhase(deps),
+                outcome: "replay-unsafe",
+                treeState,
+                attempt: 1,
+                waitedMs: result.waitedMs,
+                sawLock: result.sawLock,
+                sawRetired: result.sawRetired,
+                retiredSiblingPresent: result.retiredSiblingPresent,
+                retiredSiblingKind: result.retiredSiblingKind,
+                installTargetState: result.installTargetState,
+                updaterPidAlive: result.updaterPidAlive,
+                sawTreeChange: result.sawTreeChange,
+                lockTool: result.lockTool,
+            });
+        }
         const child = spawn(process.execPath, [...execArgv, entryPath, ...argv.slice(2)], {
             stdio: "inherit",
             env: {

package/dist/utils/install-tree-torn.d.ts

@@ -336,7 +336,7 @@ export interface InstallRewriteSignalArgs {
  */
 export declare function installRewriteInProgress(args: InstallRewriteSignalArgs): boolean;
 /** The recovery OUTCOME, which — not the dialect — decides capture. */
-export type InstallTreeTornOutcome = "guarded" | "unsettled" | "reexec-failed" | "lock-held" | "stale_tree" | "retired_unverified";
+export type InstallTreeTornOutcome = "guarded" | "replay-unsafe" | "unsettled" | "reexec-failed" | "lock-held" | "stale_tree" | "retired_unverified";
 type InstallTreeState = "in_flight" | "stale";
 export type InstallTreeTornDiagnostics = {
     dialect: ModuleErrorDialect;

package/dist/utils/sentry-fingerprint.js

@@ -185,6 +185,7 @@ const KNOWN_INSTALL_TREE_UPDATERS = new Map([
 ]);
 const KNOWN_INSTALL_TREE_OUTCOMES = new Set([
     "guarded",
+    "replay-unsafe",
     "unsettled",
     "reexec-failed",
     "lock-held",

package/package.json

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