@indigoai-us/hq-cli 5.323.0 → 5.325.0

package/dist/commands/link.d.ts

@@ -0,0 +1,30 @@
+/**
+ * hq link / hq unlink / hq resolve-company — repo-to-company registry
+ * commands (hq-anywhere US-004). The registry lives at ~/.hq/registry.json;
+ * see src/lib/registry/registry.ts for the key and precedence rules.
+ */
+import { Command } from "commander";
+export interface MembershipCompany {
+    companyUid: string;
+    companySlug: string;
+}
+export interface LinkDeps {
+    /** Registry file path; tests point this at a temp dir. */
+    file?: string;
+    /** Active memberships for the signed-in user (reuses GET /membership/me). */
+    listMemberships?: () => Promise<MembershipCompany[]>;
+    now?: () => Date;
+}
+/** Link `dir` to `company` after confirming the caller is an active member. */
+export declare function linkFolder(company: string, dir: string | undefined, deps?: LinkDeps): Promise<{
+    key: string;
+    company: string;
+}>;
+export declare function unlinkFolder(dir: string | undefined, deps?: LinkDeps): string[];
+export declare function resolveCompany(dir: string | undefined, deps?: LinkDeps): import("../lib/registry/registry.js").ResolveResult;
+/** Seed manifest-sourced entries; called by `hq install --global` (US-005). */
+export declare function seedRegistryFromHqRoot(hqRoot: string, deps?: LinkDeps): import("../lib/registry/registry.js").SeedResult;
+export declare function registerLinkCommand(program: Command): void;
+export declare function registerUnlinkCommand(program: Command): void;
+export declare function registerResolveCompanyCommand(program: Command): void;
+//# sourceMappingURL=link.d.ts.map

package/dist/commands/link.js

@@ -0,0 +1,184 @@
+/**
+ * hq link / hq unlink / hq resolve-company — repo-to-company registry
+ * commands (hq-anywhere US-004). The registry lives at ~/.hq/registry.json;
+ * see src/lib/registry/registry.ts for the key and precedence rules.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Option } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { listActiveMembershipCompanies } from "../lib/mesh/api.js";
+import { requireAnywhereRuntime } from "./anywhere-runtime-flag.js";
+import { readCompaniesManifestMap } from "../lib/work-context/repo-remote.js";
+import { canonicalDir, keyForDir, readRegistry, registryDir, registryFile, removeEntriesForDir, resolveCompanyForDir, seedFromManifest, setEntry, writeRegistry, } from "../lib/registry/registry.js";
+async function defaultListMemberships() {
+    const token = await ensureCognitoToken({ interactive: false });
+    return listActiveMembershipCompanies(token);
+}
+function targetDir(dir) {
+    const resolved = path.resolve(dir?.trim() || process.cwd());
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+        throw Object.assign(new Error(`Not a directory: ${resolved}`), { expected: true });
+    }
+    return canonicalDir(resolved);
+}
+/** Link `dir` to `company` after confirming the caller is an active member. */
+export async function linkFolder(company, dir, deps = {}) {
+    const slug = company.trim();
+    if (!slug)
+        throw Object.assign(new Error("Company slug is required."), { expected: true });
+    const folder = targetDir(dir);
+    const memberships = await (deps.listMemberships ?? defaultListMemberships)();
+    const match = memberships.find((m) => m.companySlug.toLowerCase() === slug.toLowerCase() || m.companyUid === slug);
+    if (!match) {
+        throw Object.assign(new Error(`You are not an active member of '${slug}'. Check \`hq whoami\` and the company slug.`), { expected: true });
+    }
+    const file = deps.file ?? registryFile();
+    const registry = readRegistry(file);
+    const key = keyForDir(folder);
+    setEntry(registry, key, match.companySlug, "link", deps.now?.() ?? new Date());
+    writeRegistry(registry, file);
+    return { key, company: match.companySlug };
+}
+export function unlinkFolder(dir, deps = {}) {
+    const file = deps.file ?? registryFile();
+    const registry = readRegistry(file);
+    const removed = removeEntriesForDir(registry, targetDir(dir));
+    if (removed.length > 0)
+        writeRegistry(registry, file);
+    return removed;
+}
+export function resolveCompany(dir, deps = {}) {
+    const folder = path.resolve(dir?.trim() || process.cwd());
+    let registry;
+    try {
+        registry = readRegistry(deps.file ?? registryFile());
+    }
+    catch (err) {
+        return { company: null, reason: err.message };
+    }
+    return resolveCompanyForDir(registry, folder);
+}
+/** Seed manifest-sourced entries; called by `hq install --global` (US-005). */
+export function seedRegistryFromHqRoot(hqRoot, deps = {}) {
+    const companies = readCompaniesManifestMap(hqRoot);
+    if (!companies) {
+        throw Object.assign(new Error(`No companies/manifest.yaml under ${hqRoot}`), {
+            expected: true,
+        });
+    }
+    const file = deps.file ?? registryFile();
+    const registry = readRegistry(file);
+    const result = seedFromManifest(registry, path.resolve(hqRoot), companies, deps.now?.() ?? new Date());
+    writeRegistry(registry, file);
+    return result;
+}
+function printTable(registry) {
+    const rows = Object.entries(registry.entries).sort(([a], [b]) => a.localeCompare(b));
+    if (rows.length === 0) {
+        console.log(chalk.dim(`No linked folders. (${registryFile(registryDir())})`));
+        return;
+    }
+    const width = Math.max(...rows.map(([k]) => k.length), 3);
+    console.log(`${"KEY".padEnd(width)}  ${"COMPANY".padEnd(20)}  ${"SOURCE".padEnd(8)}  LINKED AT`);
+    for (const [key, e] of rows) {
+        console.log(`${key.padEnd(width)}  ${e.company.padEnd(20)}  ${e.source.padEnd(8)}  ${e.linkedAt}`);
+    }
+}
+function fail(err) {
+    console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+    process.exitCode = 1;
+}
+export function registerLinkCommand(program) {
+    program
+        .command("link [company]")
+        .description("Link this folder (or its git remote) to an HQ company")
+        .option("--path <dir>", "Folder to link (default: current directory)")
+        .option("--list", "Print every linked folder")
+        .option("--json", "Print JSON output")
+        .addOption(new Option("--seed-manifest <hqRoot>", "Seed entries from an HQ companies/manifest.yaml").hideHelp())
+        .action(async (company, opts) => {
+        try {
+            requireAnywhereRuntime();
+            if (opts.list) {
+                const registry = readRegistry();
+                if (opts.json)
+                    console.log(JSON.stringify(registry.entries, null, 2));
+                else
+                    printTable(registry);
+                return;
+            }
+            if (opts.seedManifest) {
+                const result = seedRegistryFromHqRoot(opts.seedManifest);
+                if (opts.json)
+                    console.log(JSON.stringify(result, null, 2));
+                else
+                    console.log(`Seeded ${result.added.length} manifest entr${result.added.length === 1 ? "y" : "ies"}.`);
+                return;
+            }
+            if (!company) {
+                fail(new Error("Usage: hq link <company> [--path <dir>]  |  hq link --list"));
+                return;
+            }
+            const linked = await linkFolder(company, opts.path);
+            if (opts.json)
+                console.log(JSON.stringify(linked));
+            else
+                console.log(`Linked ${linked.key} → ${chalk.bold(linked.company)}`);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+export function registerUnlinkCommand(program) {
+    program
+        .command("unlink")
+        .description("Remove the HQ company link for this folder")
+        .option("--path <dir>", "Folder to unlink (default: current directory)")
+        .action((opts) => {
+        try {
+            requireAnywhereRuntime();
+            const removed = unlinkFolder(opts.path);
+            if (removed.length === 0)
+                console.log(chalk.dim("Nothing linked here."));
+            else
+                for (const key of removed)
+                    console.log(`Unlinked ${key}`);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+export function registerResolveCompanyCommand(program) {
+    program
+        .command("resolve-company")
+        .description("Print the HQ company linked to this folder (never guesses)")
+        .option("--path <dir>", "Folder to resolve (default: current directory)")
+        .option("--json", "Print JSON output")
+        .action((opts) => {
+        try {
+            requireAnywhereRuntime();
+        }
+        catch (err) {
+            fail(err);
+            return;
+        }
+        const result = resolveCompany(opts.path);
+        if (opts.json) {
+            console.log(JSON.stringify(result));
+            if (result.company === null)
+                process.exitCode = 1;
+            return;
+        }
+        if (result.company !== null)
+            console.log(`${result.company}\t${result.key}\t${result.source}`);
+        else {
+            console.error(result.reason);
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=link.js.map

package/dist/commands/mcp-status.d.ts

@@ -22,6 +22,12 @@ export interface RuntimeServerStatus {
     headerKeys?: string[];
     /** Env KEYS present on this runtime's def (values are NEVER captured). */
     envKeys?: string[];
+    /**
+     * Whether the def can actually launch: always true for http/sse; for stdio the
+     * command is an absolute path that exists and every absolute-path arg exists
+     * (policy hq-mcp-absolute-paths). Undefined when not present.
+     */
+    healthy?: boolean;
 }
 /** A single HQ-owned MCP server's cross-runtime status. */
 export interface McpServerStatus {

package/dist/commands/mcp-status.js

@@ -22,6 +22,8 @@
  * commander; {@link registerMcpCommand} wires the `hq mcp status` command group.
  */
 import * as fs from 'fs';
+import * as path from 'path';
+import { anywhereRuntimeEnabled } from './anywhere-runtime-flag.js';
 import { HQ_PACK_PROVENANCE_KEY, SECRET_REDACTION, backupRoot, claudeConfigFormat, claudeConfigPath, codexConfigFormat, codexConfigPath, CODEX_MCP_SERVERS_KEY, ConfigParseError, isCodexInstalled, readConfigDoc, resolveEnv, } from './mcp-registration.js';
 // ---------------------------------------------------------------------------
 // Pure status computation.
@@ -140,7 +142,7 @@ function scanCodex(env) {
     return { installed: true, parses, configPath, hqServers };
 }
 /** Build the per-runtime, per-server status from a scan (or its absence). */
-function runtimeServerStatus(scan, name) {
+function runtimeServerStatus(scan, name, checkHealth) {
     if (!scan.installed)
         return { presence: 'not-installed' };
     if (!scan.parses)
@@ -154,8 +156,20 @@ function runtimeServerStatus(scan, name) {
         target: targetOf(found.def),
         headerKeys: headerKeysOf(found.def),
         envKeys: envKeysOf(found.def),
+        ...(checkHealth ? { healthy: isLaunchable(found.def) } : {}),
     };
 }
+/** True when a def can launch (see {@link RuntimeServerStatus.healthy}). */
+function isLaunchable(def) {
+    if (transportOf(def) !== 'stdio')
+        return true;
+    const command = def.command;
+    if (typeof command !== 'string' || !path.isAbsolute(command) || !fs.existsSync(command)) {
+        return false;
+    }
+    const args = Array.isArray(def.args) ? def.args : [];
+    return args.every((a) => typeof a !== 'string' || !path.isAbsolute(a) || fs.existsSync(a));
+}
 /** List the most-recent backup dir names under `backupRoot` (newest first, capped). */
 function recentBackups(env) {
     const root = backupRoot(env);
@@ -184,14 +198,15 @@ function recentBackups(env) {
  * rather than throwing. Header VALUES are never read into the report.
  */
 export function computeMcpStatus(env) {
+    const checkHealth = anywhereRuntimeEnabled();
     const claudeScan = scanClaude(env);
     const codexScan = scanCodex(env);
     // Union of every HQ-owned server name across both runtimes.
     const names = new Set([...claudeScan.hqServers.keys(), ...codexScan.hqServers.keys()]);
     const servers = [];
     for (const name of [...names].sort()) {
-        const claude = runtimeServerStatus(claudeScan, name);
-        const codex = runtimeServerStatus(codexScan, name);
+        const claude = runtimeServerStatus(claudeScan, name, checkHealth);
+        const codex = runtimeServerStatus(codexScan, name, checkHealth);
         // Prefer whichever runtime has the def for the top-level transport/target.
         const claudeFound = claudeScan.hqServers.get(name);
         const codexFound = codexScan.hqServers.get(name);
@@ -258,7 +273,9 @@ export function computeMcpStatus(env) {
 function renderRuntimeLine(label, st) {
     switch (st.presence) {
         case 'present': {
-            const parts = [`present`];
+            const parts = st.healthy === undefined
+                ? ['present']
+                : [st.healthy ? 'present (healthy)' : 'present (UNHEALTHY: command not launchable)'];
             if (st.headerKeys && st.headerKeys.length > 0) {
                 parts.push(`headers: ${st.headerKeys.map((k) => `${k}=${SECRET_REDACTION}`).join(', ')}`);
             }

package/dist/commands/pkg-install.js

@@ -36,14 +36,33 @@ function assertApiKeyCanAuthorizeInstall(source) {
 }
 export function registerPackageInstallCommand(parent) {
     parent
-        .command('install <source>')
+        .command('install [source]')
         .description('Install a package. Sources: bare slug (registry, Cognito-gated), ' +
         '@scope/name[@ver] (npm pack), git URL[#ref], or local path.')
         .option('--company <co>', 'Scope package secret authorization to a specific company')
         .option('--allow-hooks', 'Skip the hooks confirmation prompt (content-pack flow)')
         .option('--allow-mcp', 'Skip the MCP server confirmation prompt (content-pack flow)')
         .option('--branch', 'Follow a ref instead of SHA-pinning (git content-pack flow)')
+        .option('--global', 'Install HQ into an agent runtime at user scope (requires the hq-anywhere-runtime flag)')
+        .option('--runtime <runtime>', 'Runtime for --global (claude | codex)', 'claude')
+        .option('--dry-run', 'With --global: print every file and config diff without writing')
+        .option('--hq-root <dir>', 'With --global: HQ checkout to install from (default: walk up from cwd)')
         .action(async (source, opts) => {
+        if (opts.global) {
+            if (source) {
+                console.error("error: package source cannot be used with --global");
+                process.exitCode = 1;
+                return;
+            }
+            const { runInstallGlobal } = await import('./install-global.js');
+            runInstallGlobal(opts);
+            return;
+        }
+        if (!source) {
+            console.error("error: missing required argument 'source'");
+            process.exitCode = 1;
+            return;
+        }
         try {
             // Gate the top-level `hq install` entrypoint only — `installPack`
             // itself is also called by `hq packs update` (packs.ts), which must

package/dist/commands/update.d.ts

@@ -3,5 +3,24 @@
  * Updates lock for specific module
  */
 import { Command } from 'commander';
+import { type ConvergenceDeps } from "../lib/daemon/convergence.js";
+export interface RestartAndVerifyDeps extends ConvergenceDeps {
+    restart?: () => {
+        attempted: boolean;
+        restarted: boolean;
+        message?: string;
+    };
+    sendRestartRequest?: () => void;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    installedVersion?: () => string | null;
+    log?: (line: string) => void;
+}
+/**
+ * Restart the daemon after an update and verify it converged on the installed
+ * hq-cli (policy hq-self-updater-must-verify-convergence-after-install).
+ * Returns false when it did not; the caller must report that as a failure.
+ */
+export declare function restartAndVerifyDaemon(hqRoot: string, deps?: RestartAndVerifyDeps): Promise<boolean>;
 export declare function registerUpdateCommand(program: Command): void;
 //# sourceMappingURL=update.d.ts.map

package/dist/commands/update.js

@@ -3,9 +3,56 @@
  * Updates lock for specific module
  */
 import * as path from 'path';
+import * as os from "node:os";
 import { findHqRoot, readManifest, readLock, writeLock, getModulesDir } from '../utils/manifest.js';
 import { fetchRepo, pullRepo, getCurrentCommit, isRepo } from '../utils/git.js';
-import { restartDaemonServiceIfInstalled } from "../lib/mesh/live/daemon/install.js";
+import { daemonPaths } from "../lib/daemon/paths.js";
+import { writeControlRequest } from "../lib/daemon/requests.js";
+import { hqdSocketPath } from "../lib/daemon/protocol.js";
+import { describeNonConvergence, installedCliVersion, pingHqdVersion, verifyDaemonConvergence, } from "../lib/daemon/convergence.js";
+import { anywhereRuntimeEnabled } from "./anywhere-runtime-flag.js";
+/**
+ * Restart the daemon after an update and verify it converged on the installed
+ * hq-cli (policy hq-self-updater-must-verify-convergence-after-install).
+ * Returns false when it did not; the caller must report that as a failure.
+ */
+export async function restartAndVerifyDaemon(hqRoot, deps = {}) {
+    if (!anywhereRuntimeEnabled())
+        return true;
+    const log = deps.log ?? ((line) => console.log(line));
+    const env = deps.env ?? process.env;
+    const home = deps.home ?? os.homedir();
+    let restart;
+    if (deps.restart)
+        restart = deps.restart();
+    else {
+        try {
+            await (deps.ping ?? (() => pingHqdVersion(hqdSocketPath(home, env))))();
+            (deps.sendRestartRequest ?? (() => writeControlRequest(daemonPaths(home, env).requestsDir, { action: "restart-daemon" })))();
+            restart = { attempted: true, restarted: true };
+        }
+        catch (err) {
+            restart = { attempted: false, restarted: false, message: `hqd is not running; no restart request was sent (${err instanceof Error ? err.message : String(err)})` };
+        }
+    }
+    if (restart.message)
+        log(restart.message);
+    // No installed daemon: nothing is running old code.
+    if (!restart.attempted)
+        return true;
+    const expected = (deps.installedVersion ?? installedCliVersion)();
+    if (!expected) {
+        log("Daemon convergence: could not read the installed hq-cli version (hq --version failed). Run: hq doctor --only anywhere");
+        return false;
+    }
+    const result = await verifyDaemonConvergence(expected, deps);
+    if (!result.converged) {
+        log(describeNonConvergence(result));
+        return false;
+    }
+    log(`Daemon converged: hqd runs hq-cli ${expected}.`);
+    return true;
+}
 export function registerUpdateCommand(program) {
     program
         .command('update [module-name]')
@@ -50,12 +97,11 @@ export function registerUpdateCommand(program) {
                 }
             }
             writeLock(hqRoot, lock);
-            // An installed daemon is a separate Node process. Refresh it
-            // best-effort after a successful update without making the update fail.
-            const restart = restartDaemonServiceIfInstalled({ hqRoot });
-            if (restart.message)
-                console.log(restart.message);
             console.log('\nLock file updated.');
+            // An installed daemon is a separate Node process. Restart it and
+            // verify it runs the installed hq-cli; a mismatch fails the command.
+            if (!await restartAndVerifyDaemon(hqRoot))
+                process.exitCode = 1;
         }
         catch (error) {
             console.error('Error:', error instanceof Error ? error.message : error);

package/dist/fast-core.d.ts

@@ -6,11 +6,12 @@
  * entries use the bundled-script runner; native entries import their one handler
  * module. The registration in `core.ts` remains the complete fallback path.
  */
+import { parseFastCore } from "./fast-scaffold.js";
 export declare function readStdinIfPiped(stream: NodeJS.ReadStream): 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[]): Promise<void>;
+export declare function runFastCore(argv: readonly string[], parsed?: ReturnType<typeof parseFastCore>): Promise<void>;
 //# sourceMappingURL=fast-core.d.ts.map

package/dist/fast-core.js

@@ -6,10 +6,7 @@
  * entries use the bundled-script runner; native entries import their one handler
  * module. The registration in `core.ts` remains the complete fallback path.
  */
-import { resolveLiveRoot } from "./utils/hq-roots.js";
-import { runBundledScript } from "./utils/run-bundled-script.js";
 import { parseFastCore } from "./fast-scaffold.js";
-import { CORE_RRR_WORKTREE_SCOPE_FIX_FLAG } from "./commands/core-rrr-worktree-scope-fix-flag.js";
 export async function readStdinIfPiped(stream) {
     if (stream.isTTY)
         return "";
@@ -23,8 +20,7 @@ export async function readStdinIfPiped(stream) {
  * Only call when {@link isFastCoreRequest} is true; a non-match returns without
  * doing anything.
  */
-export async function runFastCore(argv) {
-    const parsed = parseFastCore(argv);
+export async function runFastCore(argv, parsed = parseFastCore(argv)) {
     if (!parsed)
         return;
     const entry = parsed.entry;
@@ -41,9 +37,14 @@ export async function runFastCore(argv) {
         return;
     }
     const useShell = entry.kind === "native" && Boolean(entry.familyFlagKey) && !familyEnabled;
-    const worktreeScopeFixEnabled = entry.name === "repo-run-registry"
-        ? await (await import("./native-fast-route.js")).fastFlagEnabled(CORE_RRR_WORKTREE_SCOPE_FIX_FLAG, process.env, { numericEnvironmentOverride: false })
-        : undefined;
+    let worktreeScopeFixEnabled;
+    if (entry.name === "repo-run-registry") {
+        const [{ CORE_RRR_WORKTREE_SCOPE_FIX_FLAG }, { fastFlagEnabled }] = await Promise.all([
+            import("./commands/core-rrr-worktree-scope-fix-flag.js"),
+            import("./native-fast-route.js"),
+        ]);
+        worktreeScopeFixEnabled = await fastFlagEnabled(CORE_RRR_WORKTREE_SCOPE_FIX_FLAG, process.env, { numericEnvironmentOverride: false });
+    }
     const shouldInjectRoot = useShell
         ? entry.shellHqRoot === "live" || (entry.shellHqRoot === "reconcile-default" &&
             !parsed.args.includes("--hq-root") && !parsed.args.includes("--help") && !parsed.args.includes("-h"))
@@ -56,6 +57,7 @@ export async function runFastCore(argv) {
     // its expected-user-error formatting remains authoritative.
     let hqRoot;
     if (shouldInjectRoot) {
+        const { resolveLiveRoot } = await import("./utils/hq-roots.js");
         try {
             hqRoot = resolveLiveRoot(parsed.hqRootArg ? { hqRoot: parsed.hqRootArg } : {});
         }
@@ -109,6 +111,8 @@ export async function runFastCore(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 { code } = runBundledScript({
         asset,
         args: parsed.args,

package/dist/index.js

@@ -18,7 +18,9 @@ import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.
 // so runCli's finally still finalizes release health and flushes Sentry.
 installProcessRejectionBoundary();
 function dispatchCliEntry() {
-    if (isVersionRequest(process.argv)) {
+    const versionRequest = isVersionRequest(process.argv);
+    const parsedFastCore = versionRequest ? null : parseFastCore(process.argv);
+    if (versionRequest) {
         // Bare `--version` is the CLI semver only (the contract field updaters
         // compare). `hq version` and `--json` print the labelled HQ/CLI report.
         // Lazy so this path still skips the command graph.
@@ -36,22 +38,22 @@ function dispatchCliEntry() {
             });
         }
     }
-    else if (parseFastCore(process.argv)?.entry.kind === "native" &&
+    else if (parsedFastCore?.entry.kind === "native" &&
         (process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "true" ||
             process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "1")) {
         // 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));
+        void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv, parsedFastCore));
     }
-    else if (parseFastCore(process.argv)?.entry.kind === "native") {
+    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);
+                await runFastCore(process.argv, parsedFastCore);
             }
             else {
                 const { runCli } = await import("./main.js");
@@ -75,11 +77,11 @@ function dispatchCliEntry() {
             });
         });
     }
-    else if (isFastCoreRequest(process.argv)) {
+    else if (parsedFastCore) {
         // 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));
+        void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv, parsedFastCore));
     }
     else {
         // Keep the command lifecycle detached from module evaluation, as it was

package/dist/lib/core-utils/timeout-guard-native-flags.d.ts

@@ -0,0 +1,6 @@
+/** Flag snapshot reader loaded only when the timeout guard would block. */
+import type { FlagReader } from "../flag-registry.js";
+import { type PersistedFlagSnapshot } from "../flag-snapshot-file.js";
+export declare function createNativeSnapshotFlagReader(persistedSnapshot: PersistedFlagSnapshot | null, companyIdentifiers: readonly string[], env: NodeJS.ProcessEnv): FlagReader;
+export declare function snapshotFlagReader(env: NodeJS.ProcessEnv): FlagReader;
+//# sourceMappingURL=timeout-guard-native-flags.d.ts.map

package/dist/lib/core-utils/timeout-guard-native-flags.js

@@ -0,0 +1,30 @@
+/** Flag snapshot reader loaded only when the timeout guard would block. */
+import { readLocalOverride, resolveFlag, } from "@indigoai-us/hq-flags-client";
+import { resolveProcessFlagCompanyContext } from "../process-flag-company-context.js";
+import { readFlagSnapshotFile, } from "../flag-snapshot-file.js";
+export function createNativeSnapshotFlagReader(persistedSnapshot, companyIdentifiers, env) {
+    const snapshot = persistedSnapshot
+        ? { version: 0, flags: persistedSnapshot.flags }
+        : null;
+    return {
+        isEnabled(flagKey, lookup = {}) {
+            if (snapshot) {
+                return resolveFlag({
+                    flagKey,
+                    env,
+                    snapshot,
+                    companyIdentifiers,
+                    lookup,
+                }).value;
+            }
+            return readLocalOverride(flagKey, env) ?? (lookup.fallback ?? false);
+        },
+    };
+}
+export function snapshotFlagReader(env) {
+    const company = resolveProcessFlagCompanyContext(env);
+    const persistedSnapshot = company.companyUid ? readFlagSnapshotFile(company.companyUid, { env }) : null;
+    const companyIdentifiers = [company.companyUid, company.companySlug].filter((value) => Boolean(value));
+    return createNativeSnapshotFlagReader(persistedSnapshot, companyIdentifiers, env);
+}
+//# sourceMappingURL=timeout-guard-native-flags.js.map

package/dist/lib/core-utils/timeout-guard-native.d.ts

@@ -1,7 +1,4 @@
 /** Native fast-route adapter for the shared timeout-guard command. */
-import type { FlagReader } from "../flag-registry.js";
-import { type PersistedFlagSnapshot } from "../flag-snapshot-file.js";
 import { type TimeoutGuardDeps } from "./timeout-guard.js";
-export declare function createNativeSnapshotFlagReader(persistedSnapshot: PersistedFlagSnapshot | null, companyIdentifiers: readonly string[], env: NodeJS.ProcessEnv): FlagReader;
 export declare function runTimeoutGuardFast(_argv: readonly string[], stdin: string, _cwd: string, _hqRoot: string | undefined, dependencies?: TimeoutGuardDeps): Promise<number>;
 //# sourceMappingURL=timeout-guard-native.d.ts.map

package/dist/lib/core-utils/timeout-guard-native.js

@@ -1,40 +1,14 @@
 /** Native fast-route adapter for the shared timeout-guard command. */
-import { readLocalOverride, resolveFlag, } from "@indigoai-us/hq-flags-client";
-import { resolveProcessFlagCompanyContext } from "../process-flag-company-context.js";
-import { readFlagSnapshotFile, } from "../flag-snapshot-file.js";
 import { timeoutGuardCommand } from "./timeout-guard.js";
-export function createNativeSnapshotFlagReader(persistedSnapshot, companyIdentifiers, env) {
-    const snapshot = persistedSnapshot
-        ? { version: 0, flags: persistedSnapshot.flags }
-        : null;
-    return {
-        isEnabled(flagKey, lookup = {}) {
-            if (snapshot) {
-                return resolveFlag({
-                    flagKey,
-                    env,
-                    snapshot,
-                    companyIdentifiers,
-                    lookup,
-                }).value;
-            }
-            return readLocalOverride(flagKey, env) ?? (lookup.fallback ?? false);
-        },
-    };
-}
-function snapshotFlagReader(companyUid, companySlug, env) {
-    const persistedSnapshot = companyUid ? readFlagSnapshotFile(companyUid, { env }) : null;
-    const companyIdentifiers = [companyUid, companySlug].filter((value) => Boolean(value));
-    return createNativeSnapshotFlagReader(persistedSnapshot, companyIdentifiers, env);
-}
 export async function runTimeoutGuardFast(_argv, stdin, _cwd, _hqRoot, dependencies = {}) {
     const env = dependencies.env ?? process.env;
-    const company = resolveProcessFlagCompanyContext(env);
-    const flagReader = dependencies.flagReader ?? snapshotFlagReader(company.companyUid, company.companySlug, env);
     return timeoutGuardCommand(stdin, {
         ...dependencies,
         env,
-        flagReader,
+        getFlagReader: dependencies.getFlagReader ?? (async () => {
+            const { snapshotFlagReader } = await import("./timeout-guard-native-flags.js");
+            return snapshotFlagReader(env);
+        }),
     });
 }
 //# sourceMappingURL=timeout-guard-native.js.map

package/dist/lib/core-utils/timeout-guard.d.ts

@@ -49,6 +49,8 @@ export declare function evaluateTimeoutGuard(input: TimeoutGuardInput): GuardVer
 export interface TimeoutGuardDeps {
     /** Resolve the current HQ user email for the rollout gate. Default: cached id token. */
     getEmail?: () => string | undefined;
+    /** Resolve the flag reader only after an input would otherwise be blocked. */
+    getFlagReader?: () => Promise<FlagReader>;
     env?: NodeJS.ProcessEnv;
     stderr?: NodeJS.WritableStream;
     /** Test seam: held registry snapshot reader. */