@indigoai-us/hq-cli 5.345.148 → 5.345.149

package/dist/commands/install-global.js

@@ -1,3 +1,4 @@
+import { hookTargetFor } from '../lib/install/hook-target.js';
 /**
  * `hq install --global --runtime claude` / `hq uninstall --global --runtime claude`
  * (hq-anywhere-runtime US-005).
@@ -25,34 +26,11 @@ import { readRegistry, registryDir, registryFile, writeRegistry } from '../lib/r
 import { readCompaniesManifestMap } from '../lib/work-context/repo-remote.js';
 import { resolveDefaultHqRoot } from '../utils/hq-root-resolver.js';
 import { trustCodexUserHooks } from '../utils/hook-trust.js';
-import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from '../lib/daemon/install.js';
-import { readDaemonConfig } from '../lib/daemon/config.js';
-import { daemonPaths } from '../lib/daemon/paths.js';
 import { assertProviderWrappersInstallable, installProviderWrappers, providerWrapperInstallPaths, removeProviderWrappers } from '../lib/install/provider-wrappers.js';
-import { checkShimOnPath, shimPathWarning } from '../lib/windows/user-path.js';
+import { checkShimOnPath, ensureShimOnUserPath, shimPathWarning } from '../lib/windows/user-path.js';
 import { addAgentsMdBlock, addCodexHooks, classifyLegacySkills, codexAdapterPath, codexCharterSource, codexHookTrustKeys, codexTargets, hasAllCodexHooks, HQ_OWNED_MARKER, LEGACY_BACKUP_NAME, LEGACY_SKILLS_NAME, removeAgentsMdBlock, removeCodexHooks, } from '../lib/install/codex-targets.js';
 import { addClaudeMdBlock, addHqHooks, charterPath, claudeTargets, hasAllHqHooks, HQ_ANYWHERE_PACK, HQ_MCP_SERVER_NAME, hqSkillsSource, lineDiff, masterHookPath, shimPath, MCP_SUBPROCESS_PATH, removeClaudeMdBlock, removeHqHooks, SKILL_LINK_PREFIX, } from '../lib/install/claude-targets.js';
-/** True when an hq daemon unit (launchd plist or systemd unit) exists. */
-export function isDaemonInstalled(home, platform = process.platform, queryTask = (task) => spawnSync('schtasks.exe', ['/Query', '/TN', task], { encoding: 'utf8', windowsHide: true }).status === 0) {
-    if (platform === 'win32')
-        return queryTask(DAEMON_WINDOWS_TASK);
-    const candidates = platform === 'darwin'
-        ? [path.join(home, 'Library', 'LaunchAgents', `${DAEMON_LAUNCHD_LABEL}.plist`)]
-        : platform === 'linux'
-            ? [path.join(home, '.config', 'systemd', 'user', DAEMON_SYSTEMD_UNIT), path.join(SYSTEM_UNIT_DIR, DAEMON_SYSTEMD_UNIT)]
-            : [];
-    return candidates.some((p) => fs.existsSync(p));
-}
-/**
- * US-010: with hqd installed (and the checkout shipping the shim), hooks go to
- * the hqd shim; otherwise to master-hook.sh / the Codex adapter.
- */
-export function hookTargetFor(hqRoot, home, daemonInstalled, env = process.env) {
-    const installed = daemonInstalled ?? isDaemonInstalled(home);
-    const configuredRoot = readDaemonConfig(daemonPaths(home, env).configPath).hqRoot;
-    const daemonMatchesRoot = configuredRoot !== undefined && realpathOrSelf(configuredRoot) === realpathOrSelf(hqRoot);
-    return installed && daemonMatchesRoot && fs.existsSync(shimPath(hqRoot)) ? 'shim' : 'master';
-}
+export { hookTargetFor, isDaemonInstalled } from '../lib/install/hook-target.js';
 const HQ_PACKAGES_MARKETPLACE_REPOSITORY = 'indigoai-us/hq-packages';
 /** Resolve local overrides first, then the published HQ marketplace. */
 export function resolveClaudePluginSource(explicitDir, env = process.env, repository = HQ_PACKAGES_MARKETPLACE_REPOSITORY) {
@@ -615,7 +593,7 @@ export function installGlobalClaude(opts) {
     if (pluginSource)
         log(`  plugin: ${pluginSource.pluginId} installed from ${pluginSource.sourceDir}; direct hooks and MCP entries removed`);
     else {
-        log(`  hooks: ${hookTarget === 'shim' ? 'hqd-hook-shim.sh' : 'master-hook.sh'} registered in ${t.settingsJson}`);
+        log(`  hooks: ${typeof hookTarget === 'object' ? hookTarget.engine : hookTarget === 'shim' ? 'hqd-hook-shim.sh' : 'master-hook.sh'} registered in ${t.settingsJson}`);
         log(`  MCP: "${HQ_MCP_SERVER_NAME}" registered in ${t.claudeJson}`);
     }
     log(`  registry: ${seeded.length} manifest entr${seeded.length === 1 ? 'y' : 'ies'} seeded`);
@@ -994,7 +972,7 @@ export function installGlobalCodex(opts) {
     log(`  skills linked: ${skills.link.length} new, ${skills.already.length} already present, ${skills.skipped.length} skipped`);
     reportSkillCopies(linkKinds, log);
     reportSkippedSkills(skills, log, false);
-    log(`  hooks: ${hookTarget === 'shim' ? shimPath(hqRoot) : codexAdapterPath(hqRoot)} registered in ${t.hooksJson}`);
+    log(`  hooks: ${typeof hookTarget === 'object' ? hookTarget.engine : hookTarget === 'shim' ? shimPath(hqRoot) : codexAdapterPath(hqRoot)} registered in ${t.hooksJson}`);
     log(`  MCP: "${HQ_MCP_SERVER_NAME}" registered in ${t.configToml}`);
     return touched;
 }
@@ -1213,6 +1191,12 @@ export async function runInstallGlobal(opts) {
     if (runtime === 'codex' && !opts.dryRun)
         await trustInstalledCodexHooks(hqRoot, opts);
     if (!opts.dryRun) {
+        try {
+            ensureShimOnUserPath({ env, entry: process.argv[1] });
+        }
+        catch {
+            // The warning below is the fallback when the user Path cannot be updated.
+        }
         const shimPath = (opts.shimPathCheck ?? (() => checkShimOnPath({ env })))();
         if (shimPath)
             for (const line of shimPathWarning(shimPath))

package/dist/commands/library-add.d.ts

@@ -1,5 +1,5 @@
 import { Readable } from "node:stream";
-import { type CloudAssetMediaKind } from "@indigoai-us/hq-cloud";
+import { type CloudAssetMediaKind, type PullScope, type PullScopeClient } from "@indigoai-us/hq-cloud";
 import type { LibraryCaptionNote, LibraryCaptionRequest } from "./library-caption.js";
 export interface LibraryCompany {
     uid: string;
@@ -37,6 +37,13 @@ export interface LibraryAddDeps {
      * a caption failure never fails the upload. Absent = no captioning.
      */
     caption?: (request: LibraryCaptionRequest) => Promise<LibraryCaptionNote>;
+    /**
+     * The membership's sync scope for the company. Throws when it cannot be
+     * read. Absent = the scope is not checked and nothing is pinned.
+     */
+    syncScope?: (company: LibraryCompany) => Promise<Pick<PullScope, "syncMode" | "prefixSet">>;
+    /** `hq files get`'s pin writer (`.hq/pins.json`). */
+    addPin?: (hqRoot: string, companySlug: string, prefix: string) => void;
 }
 export interface LibraryAddOptions {
     company?: string;
@@ -60,9 +67,19 @@ export interface LibraryAddItem {
     /** AI caption outcome, set when captioning ran for this item. */
     caption?: LibraryCaptionNote;
 }
+export interface LibrarySyncScopeNote {
+    status: "in-scope" | "pinned" | "not-pinned";
+    /** Company-relative pins written (`pinned`) or still needed (`not-pinned`). */
+    pins: string[];
+    /** Set when not pinned and `hq files get` can pin by hand (the library folder). */
+    command?: string;
+    reason?: string;
+}
 export interface LibraryAddResult {
     company: string;
     items: LibraryAddItem[];
+    /** Set when at least one placeholder was written and the scope was checked. */
+    syncScope?: LibrarySyncScopeNote;
 }
 export declare function contentTypeFor(name: string, served?: string): string;
 export declare function mediaKindFor(contentType: string): CloudAssetMediaKind;
@@ -89,6 +106,19 @@ export declare function offloadTimestamp(now: Date): string;
  * only that source.
  */
 export declare function runLibraryAdd(inputs: readonly string[], options: LibraryAddOptions, deps: LibraryAddDeps): Promise<LibraryAddResult>;
+/**
+ * A `shared` or `custom` sync pushes only paths inside the membership's
+ * prefix set (explicit grants plus pins), so a placeholder written outside it
+ * never reaches the vault. Pin it with `hq files get`'s pin writer: the
+ * default library folder as a whole, and for any other `--to` folder only the
+ * written placeholders, so the rest of that folder stays out of sync.
+ */
+export declare function ensureLibraryInSyncScope(company: LibraryCompany, dirRel: string, placeholderPaths: readonly string[], deps: Pick<LibraryAddDeps, "hqRoot" | "syncScope" | "addPin">): Promise<LibrarySyncScopeNote | undefined>;
+/**
+ * {@link resolvePullScope} answers `all` when any call fails. Report the
+ * failure instead, so a failed lookup is not mistaken for full sync.
+ */
+export declare function resolveLibrarySyncScope(client: Required<PullScopeClient>, company: LibraryCompany, hqRoot: string): Promise<PullScope>;
 export interface LibraryTagResult {
     placeholderPath: string;
     tags: string[];

package/dist/commands/library-add.js

@@ -28,7 +28,7 @@ import http from "node:http";
 import https from "node:https";
 import path from "node:path";
 import { Readable } from "node:stream";
-import { formatCloudAssetBlock, formatCloudPlaceholder, parseCloudPlaceholder, } from "@indigoai-us/hq-cloud";
+import { formatCloudAssetBlock, formatCloudPlaceholder, isCoveredByAny, parseCloudPlaceholder, resolvePullScope, } from "@indigoai-us/hq-cloud";
 import { PLACEHOLDER_SUFFIX, companyOffloadKey, containedPath, durablePlaceholderFs, renderPointer, resolvePlaceholder, } from "./storage-offload.js";
 import { formatPlanGateError, formatUpgradeRefusal, planGateErrorFromResponse, } from "../utils/plan-gate-error.js";
 /** Metadata key hq-pro binds to `checksumSha256` (sync's content hash). */
@@ -321,7 +321,74 @@ export async function runLibraryAdd(inputs, options, deps) {
                 .catch((err) => ({ status: "failed", note: err.message }));
         }
     }
-    return { company: slug, items };
+    const written = items.flatMap((item) => (item.ok && item.placeholderPath ? [item.placeholderPath] : []));
+    if (written.length === 0)
+        return { company: slug, items };
+    const syncScope = await ensureLibraryInSyncScope(company, dirRel, written, deps);
+    return { company: slug, items, ...(syncScope ? { syncScope } : {}) };
+}
+const LIBRARY_FOLDER = "library/";
+/**
+ * A `shared` or `custom` sync pushes only paths inside the membership's
+ * prefix set (explicit grants plus pins), so a placeholder written outside it
+ * never reaches the vault. Pin it with `hq files get`'s pin writer: the
+ * default library folder as a whole, and for any other `--to` folder only the
+ * written placeholders, so the rest of that folder stays out of sync.
+ */
+export async function ensureLibraryInSyncScope(company, dirRel, placeholderPaths, deps) {
+    if (!deps.syncScope || !deps.addPin)
+        return undefined;
+    const companyRel = (rel) => rel.split("/").slice(2).join("/");
+    const isLibrary = `${companyRel(dirRel)}/` === LIBRARY_FOLDER;
+    const targets = isLibrary ? [LIBRARY_FOLDER] : placeholderPaths.map(companyRel);
+    const command = isLibrary ? `hq files get ${LIBRARY_FOLDER} --company ${company.slug}` : undefined;
+    let scope;
+    try {
+        scope = await deps.syncScope(company);
+    }
+    catch (err) {
+        return {
+            status: "not-pinned",
+            pins: targets,
+            ...(command ? { command } : {}),
+            reason: `could not read your sync scope: ${err.message}`,
+        };
+    }
+    const missing = scope.syncMode === "all" ? [] : targets.filter((t) => !isCoveredByAny(t, scope.prefixSet ?? []));
+    if (missing.length === 0)
+        return { status: "in-scope", pins: [] };
+    try {
+        for (const target of missing)
+            deps.addPin(deps.hqRoot, company.slug, target);
+    }
+    catch (err) {
+        return {
+            status: "not-pinned",
+            pins: missing,
+            ...(command ? { command } : {}),
+            reason: `could not write the pin: ${err.message}`,
+        };
+    }
+    return { status: "pinned", pins: missing };
+}
+/**
+ * {@link resolvePullScope} answers `all` when any call fails. Report the
+ * failure instead, so a failed lookup is not mistaken for full sync.
+ */
+export async function resolveLibrarySyncScope(client, company, hqRoot) {
+    let failure;
+    const watch = (call) => call.catch((err) => {
+        failure ??= err;
+        throw err;
+    });
+    const scope = await resolvePullScope({
+        listMyMemberships: () => watch(client.listMyMemberships()),
+        getMembershipSyncConfig: (id) => watch(client.getMembershipSyncConfig(id)),
+        listMyExplicitGrants: (uid) => watch(client.listMyExplicitGrants(uid)),
+    }, company.uid, company.slug, hqRoot);
+    if (failure !== undefined)
+        throw failure instanceof Error ? failure : new Error(String(failure));
+    return scope;
 }
 async function writeAssetPlaceholder(p, options, deps, dirAbs) {
     const ts = offloadTimestamp(deps.now());

package/dist/commands/library.js

@@ -35,7 +35,7 @@ import { findHqRoot } from "../utils/manifest.js";
 import { networkTransportErrorCode } from "../utils/network-transport-error.js";
 import { resolveVaultCredentialForCapability } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { defaultLibraryIo, runLibraryAdd, runLibraryTag, } from "./library-add.js";
+import { defaultLibraryIo, resolveLibrarySyncScope, runLibraryAdd, runLibraryTag, } from "./library-add.js";
 import { captionAddedAsset, extractCaptionFrames, runLibraryDescribe, runLocalClaude } from "./library-caption.js";
 import { LIBRARY_LINK_DEFAULT_MINUTES, LIBRARY_LINK_MAX_MINUTES, runLibraryLink } from "./library-link.js";
 /** Mirrors hq-pro's MAX_ASSET_SEARCH_TAGS / tag length bound. */
@@ -295,8 +295,39 @@ export function formatLibraryAddResult(result) {
             return `${line}\n  ${chalk.dim(`AI caption added (${item.caption.captionedBy}).`)}`;
         return `${line}\n  ${chalk.yellow(item.caption.note ?? "Captioning skipped.")}`;
     })
+        .concat(formatLibrarySyncScope(result))
         .join("\n");
 }
+function formatLibrarySyncScope({ company, syncScope }) {
+    if (!syncScope || syncScope.status === "in-scope")
+        return [];
+    const pins = syncScope.pins.map((pin) => `${company}:${pin}`).join(", ");
+    if (syncScope.status === "pinned") {
+        return [chalk.dim(`Pinned ${pins} so sync uploads these placeholders to the company vault.`)];
+    }
+    const fix = syncScope.command
+        ? `Pin the folder with: ${syncScope.command}`
+        : `Add ${syncScope.pins.join(", ")} under "${company}" in .hq/pins.json at the HQ root.`;
+    return [
+        chalk.yellow(`Warning: sync may not upload these placeholders (${syncScope.reason}). ` +
+            `Until it does, teammates and cloud search will not see them. ${fix}`),
+    ];
+}
+/** Sync scope wiring for `hq library add`; an API key has no sync tree to check. */
+async function librarySyncScopeDeps(credential, hqRoot) {
+    if (credential.kind !== "cognito")
+        return {};
+    const [{ VaultClient }, { buildVaultConfig }, { addPin }] = await Promise.all([
+        import("@indigoai-us/hq-cloud"),
+        import("../utils/cognito-session.js"),
+        import("./files-browse.js"),
+    ]);
+    const client = new VaultClient(buildVaultConfig(credential.token));
+    return {
+        syncScope: (company) => resolveLibrarySyncScope(client, company, hqRoot),
+        addPin,
+    };
+}
 /** GET a presigned URL. Errors never echo the URL, which carries a signature. */
 async function downloadPresigned(url) {
     const res = await fetch(url);
@@ -366,9 +397,11 @@ export function registerLibraryCommand(program) {
         .option("--json", "Print machine-readable JSON")
         .action(async (sources, options) => {
         try {
-            const { token } = await resolveVaultCredentialForCapability("files:write", "library add", {
+            const credential = await resolveVaultCredentialForCapability("files:write", "library add", {
                 interactive: true,
             });
+            const { token } = credential;
+            const hqRoot = findHqRoot();
             const result = await runLibraryAdd(sources, {
                 company: options.company,
                 to: options.to,
@@ -376,11 +409,12 @@ export function registerLibraryCommand(program) {
                 title: options.title,
                 note: options.note,
             }, {
-                hqRoot: findHqRoot(),
+                hqRoot,
                 now: () => new Date(),
                 resolveCompany: (slug) => libraryCompany(token, slug),
                 presign: (body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
                 ...defaultLibraryIo,
+                ...(await librarySyncScopeDeps(credential, hqRoot)),
                 ...(options.caption === false
                     ? {}
                     : {

package/dist/commands/reindex.js

@@ -1,3 +1,5 @@
+import { reconcileHookRegistrations } from '../lib/hook-engine/reconcile.js';
+import { trustCodexUserHooks } from '../utils/hook-trust.js';
 /**
  * hq reindex — surface namespaced skills and commands, clean up retired
  * personal-overlay mirror links, capture coding-harness session logs, regenerate
@@ -775,6 +777,23 @@ export function registerReindexCommand(program) {
             // means a sync/rescue holds the shared operation lock and may be
             // rewriting .claude/settings.json right now, and this is an unlocked
             // whole-file read-modify-write.
+            // Registration reconcile is best-effort: a failure leaves the current
+            // registrations in place and must not stop the rest of reindex.
+            try {
+                // A file that failed is left as it was; the keys of files that were
+                // rewritten are still trusted so Codex keeps running their hooks.
+                const { codexUserKeys, failures } = reconcileHookRegistrations(hqRoot);
+                for (const failure of failures)
+                    console.warn(`reindex: hook registration reconcile skipped ${failure}`);
+                if (codexUserKeys.length) {
+                    const trust = await trustCodexUserHooks(hqRoot, codexUserKeys);
+                    if (trust.status === 'failed')
+                        console.warn(`reindex: Codex hook trust needs repair: ${trust.reason}`);
+                }
+            }
+            catch (error) {
+                console.warn(`reindex: hook registration reconcile skipped: ${error.message}`);
+            }
             dropProjectDefaultModeForBypassUser(hqRoot);
             await trustHqRuntimeHooks(hqRoot, undefined, {
                 rootAliases: [literalHqRoot],

package/dist/hook-engine-path.js

@@ -11,14 +11,21 @@ export function hookEnginePathArgs(argv) {
 }
 export async function runHookEnginePath(args) {
     try {
-        if (args.some(arg => !['--repair', '--help', '-h'].includes(arg))) {
-            throw new Error('Usage: hq core hook-engine-path [--repair]');
+        if (args.some(arg => !['--repair', '--help', '-h', '--for-registration'].includes(arg))) {
+            throw new Error('Usage: hq core hook-engine-path [--repair] [--for-registration]');
         }
         if (args.includes('--help') || args.includes('-h')) {
-            console.log('Usage: hq core hook-engine-path [--repair]\nResolve and pin the installed native hook engine offline.');
+            console.log('Usage: hq core hook-engine-path [--repair] [--for-registration]\nResolve and pin the installed native hook engine offline.\n--for-registration prints a path only when the launcher flag is enabled.');
             return;
         }
         const { installHookEngine, hookEngineRequired, HOOK_ENGINE_REPAIR } = await import('./lib/hook-engine/resolve.js');
+        if (args.includes('--for-registration')) {
+            const { launcherEnabled } = await import('./lib/hook-engine/registration.js');
+            if (!launcherEnabled()) {
+                process.exitCode = 1;
+                return;
+            }
+        }
         const binary = installHookEngine({ repair: args.includes('--repair') });
         if (binary)
             console.log(binary);

package/dist/index.d.ts

@@ -3,6 +3,15 @@ import "./node-preflight.js";
 import "./node-network-compat-fast.js";
 import { isVersionRequest } from "./version-request.js";
 import { isFastCoreRequest } from "./fast-scaffold.js";
+/**
+ * Whether the install follow-up would read the registry or spawn the mesh
+ * daemon. False for fast routes' callers, and for commands that are not run
+ * from an npm install: the PATH repair needs the npm shim folder above
+ * node_modules, and the daemon step needs the installed package. Inlined so
+ * those routes do not load user-path.ts. Keep the skip rules aligned with
+ * install-followup.ts.
+ */
+export declare function installFollowupWouldDoWork(argv: readonly string[], env: NodeJS.ProcessEnv, platform: NodeJS.Platform): boolean;
 type PackageUseLeaseLoader = () => Promise<void>;
 type PackageUseUpdateProbe = () => Promise<boolean>;
 /** Resolves true once the command was re-run (exit code already set). */
@@ -18,6 +27,7 @@ declare function runCliEntry(entryUrl: string, dispatch: () => void, loadLease?:
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;
     isFastCoreRequest: typeof isFastCoreRequest;
+    installFollowupWouldDoWork: typeof installFollowupWouldDoWork;
     dispatchWithPackageUseLease: typeof dispatchWithPackageUseLease;
     waitForUpdateThenReexec: typeof waitForUpdateThenReexec;
     runCliEntry: typeof runCliEntry;

package/dist/index.js

@@ -156,6 +156,26 @@ async function runMonitorCheckFastWithRecovery(request) {
         return;
     await runMainWithInstallTreeRecovery();
 }
+/**
+ * Whether the install follow-up would read the registry or spawn the mesh
+ * daemon. False for fast routes' callers, and for commands that are not run
+ * from an npm install: the PATH repair needs the npm shim folder above
+ * node_modules, and the daemon step needs the installed package. Inlined so
+ * those routes do not load user-path.ts. Keep the skip rules aligned with
+ * install-followup.ts.
+ */
+export function installFollowupWouldDoWork(argv, env, platform) {
+    if (env.HQ_INSTALL_FOLLOWUP === "1" || env.HQ_STAGED_INSTALL === "1")
+        return false;
+    const args = argv.slice(2).filter((arg) => arg !== "--verbose");
+    if (args[0] === "mesh" && args[1] === "daemon")
+        return false;
+    if (args[0] === "daemon" && (args[1] === "run" || args[1] === "install"))
+        return false;
+    if (platform === "win32")
+        return /[/\\]node_modules[/\\]/i.test(argv[1] ?? "");
+    return /node_modules[/\\]@indigoai-us[/\\]hq-cli[/\\]/i.test(argv[1] ?? "");
+}
 function dispatchCliEntry() {
     // Before anything spawns: a background hq on Windows (no terminal) hides the
     // console window of every child it starts (feedback_351a40d5).
@@ -165,6 +185,19 @@ function dispatchCliEntry() {
         void runHookEnginePath(engineArgs);
         return;
     }
+    // cmd.exe code page 437 prints em dashes as mojibake. Pipes stay UTF-8.
+    // Loaded only on Windows so Linux fast routes do not pay for the module.
+    if (process.platform === "win32") {
+        void import("./lib/windows/console-encoding.js").then(({ installWindowsConsoleEncoding }) => {
+            installWindowsConsoleEncoding();
+        }).catch(() => undefined).then(() => {
+            dispatchCliRoutes();
+        });
+        return;
+    }
+    dispatchCliRoutes();
+}
+function dispatchCliRoutes() {
     if (process.platform === "win32" && coreCommandHasPathOperands(process.argv)) {
         // Keep cygpath off non-Windows and non-path command routes.
         process.argv = normalizeCorePathOperands(process.argv, "win32", cygpathMixedPath);
@@ -172,6 +205,37 @@ function dispatchCliEntry() {
     const versionRequest = isVersionRequest(process.argv);
     const helpRequest = !versionRequest && isCommandHelpRequest(process.argv);
     const parsedFastCore = versionRequest || helpRequest ? null : parseFastCore(process.argv);
+    const monitorRequest = versionRequest || helpRequest ? null : parseMonitorCheckFastRequest(process.argv);
+    const secretsRequest = versionRequest || helpRequest || monitorRequest || parsedFastCore
+        ? null
+        : parseSecretsEnvFastRequest(process.argv);
+    const mcpRequest = !versionRequest &&
+        !helpRequest &&
+        !monitorRequest &&
+        !parsedFastCore &&
+        !secretsRequest &&
+        isMcpServeRequest(process.argv);
+    // `--version`, hook, MCP, and secrets fast routes must not pay for PATH or
+    // daemon work, so they never start PowerShell or reg.exe. The module stays
+    // unloaded when there is nothing to do, so a Linux fast route does not
+    // import it.
+    if (!versionRequest && !monitorRequest && !parsedFastCore && !secretsRequest && !mcpRequest
+        && installFollowupWouldDoWork(process.argv, process.env, process.platform)) {
+        void import("./lib/windows/install-followup.js").then(({ runWindowsInstallFollowup }) => {
+            try {
+                runWindowsInstallFollowup({ argv: process.argv });
+            }
+            catch {
+                // Install repair must not turn into a failed command.
+            }
+        }).catch(() => undefined).then(() => {
+            dispatchCliCommand(versionRequest, helpRequest, parsedFastCore, monitorRequest, secretsRequest, mcpRequest);
+        });
+        return;
+    }
+    dispatchCliCommand(versionRequest, helpRequest, parsedFastCore, monitorRequest, secretsRequest, mcpRequest);
+}
+function dispatchCliCommand(versionRequest, helpRequest, parsedFastCore, monitorRequest, secretsRequest, mcpRequest) {
     if (versionRequest) {
         // Bare `--version` is the CLI semver only (the contract field updaters
         // compare). `hq version` and `--json` print the labelled HQ/CLI report.
@@ -202,11 +266,11 @@ function dispatchCliEntry() {
             await runMainWithInstallTreeRecovery();
         });
     }
-    else if (parseMonitorCheckFastRequest(process.argv)) {
+    else if (monitorRequest) {
         // The Stop hook runs this every turn in every session. Answer the common
         // no-active-lane case from the lane-record directory alone; anything the
         // fast route cannot prove falls back to the full command graph.
-        void runMonitorCheckFastWithRecovery(parseMonitorCheckFastRequest(process.argv));
+        void runMonitorCheckFastWithRecovery(monitorRequest);
     }
     else if (parsedFastCore?.entry.kind === "native" &&
         (process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "true" ||
@@ -222,8 +286,8 @@ function dispatchCliEntry() {
         // existing full-graph route.
         void runNativeFastRouteWithRecovery(parsedFastCore);
     }
-    else if (parseSecretsEnvFastRequest(process.argv)) {
-        const request = parseSecretsEnvFastRequest(process.argv);
+    else if (secretsRequest) {
+        const request = secretsRequest;
         void import("./secrets-env-fast-route.js").then(async (route) => {
             await route.dispatchSecretsEnvFastRequest(request, {
                 isEnabled: () => route.secretsEnvFastRouteEnabled(request),
@@ -237,7 +301,7 @@ function dispatchCliEntry() {
             });
         });
     }
-    else if (isMcpServeRequest(process.argv)) {
+    else if (mcpRequest) {
         // Keep the minimal startup route; runMcpServe applies the hq-flags gate.
         void import("./commands/mcp-serve.js").then(({ runMcpServe }) => runMcpServe());
     }
@@ -373,6 +437,7 @@ void runCliEntry(import.meta.url, dispatchCliEntry);
 export const __test__ = {
     isVersionRequest,
     isFastCoreRequest,
+    installFollowupWouldDoWork,
     dispatchWithPackageUseLease,
     waitForUpdateThenReexec,
     runCliEntry,

package/dist/lazy-commands.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { COMMAND_CATALOG } from "./command-catalog.generated.js";
+import { installUnknownCommandSuggestions } from "./unknown-command.js";
 const commandCatalog = COMMAND_CATALOG;
 /**
  * One entry for every root, including groups that are assembled by several
@@ -105,6 +106,7 @@ export function findRuntimeHqRoot(start, parentOf = dirname, isRoot = (directory
 export function registerCommandCatalog(program) {
     for (const command of commandCatalog)
         program.addCommand(commandDefinition(command));
+    installUnknownCommandSuggestions(program);
 }
 function commandForToken(token) {
     return commandCatalog.find((candidate) => candidate.name === token || candidate.aliases.includes(token));

package/dist/lib/billing/usage-cost.d.ts

@@ -201,14 +201,44 @@ export interface UsageReport {
     freeItems: string;
     drivers: Driver[];
     noSyncGuideUrl: string;
+    /** Set by `hq billing usage`: the account is on usage pricing, so meters are priced. */
+    onUsagePricing?: true;
     readOnly: true;
 }
+/** One meter's reading with no price attached. */
+export interface MeterReadingRow {
+    key: UsageMeterKey;
+    displayName: string;
+    /** In billed units (GB for storage). Null unless measured. */
+    value: number | null;
+    state: MeterState;
+}
+/**
+ * The report for an account that is not on usage pricing (a flat plan, or the
+ * server did not say). Readings only: no rates, no cost, no projected bill.
+ */
+export interface UsageReadingsReport {
+    scope: UsageScope;
+    source: MonthUsage["source"];
+    /** False: flat plan, meters are not billed. Null: HQ did not say. */
+    onUsagePricing: false | null;
+    period: MonthUsage["period"];
+    meters: MeterReadingRow[];
+    storage?: StorageSplit;
+    /** The one line that says why no cost is shown. */
+    notice: string;
+    readOnly: true;
+}
+export type BillingUsageReport = UsageReport | UsageReadingsReport;
+export declare function isReadingsReport(r: BillingUsageReport): r is UsageReadingsReport;
+/** Readings for an account not on usage pricing. Never prices a meter. */
+export declare function buildReadingsReport(usage: MonthUsage, onUsagePricing: false | null): UsageReadingsReport;
 export declare function buildReport(usage: MonthUsage, rates: {
     rates: readonly UsageMeterRate[];
     allowanceUsd: number;
     source: "published" | "bundled";
     card?: UsageCard;
 }): UsageReport;
-export declare function formatReport(r: UsageReport): string;
+export declare function formatReport(r: BillingUsageReport): string;
 export {};
 //# sourceMappingURL=usage-cost.d.ts.map

package/dist/lib/billing/usage-cost.js

@@ -362,6 +362,38 @@ export function findDrivers(usage, bill) {
 // ── Report ──────────────────────────────────────────────────────────────────
 /** The self-hosted / no-sync guide the usage card links (feed `signup.selfHosted.url`). */
 export const NO_SYNC_GUIDE_URL = SELF_HOSTED_GUIDE_URL;
+export function isReadingsReport(r) {
+    return !("bill" in r);
+}
+function readingsNotice(scope, onUsagePricing) {
+    if (onUsagePricing === false) {
+        return scope.kind === "company"
+            ? `${scope.companySlug} is on a flat plan, so usage meters are not billed.`
+            : "Your personal account is on a flat plan, so usage meters are not billed.";
+    }
+    const who = scope.kind === "company" ? scope.companySlug : "your personal account";
+    return `HQ did not say whether ${who} is on usage pricing, so no costs are shown.`;
+}
+/** Readings for an account not on usage pricing. Never prices a meter. */
+export function buildReadingsReport(usage, onUsagePricing) {
+    const byKey = new Map(usage.meters.map((m) => [m.key, m]));
+    const meters = BUNDLED_USAGE_METER_RATES.map((rate) => {
+        const reading = byKey.get(rate.key);
+        return reading && reading.state === "measured" && reading.value !== null
+            ? { key: rate.key, displayName: rate.displayName, value: reading.value, state: "measured" }
+            : { key: rate.key, displayName: rate.displayName, value: null, state: reading?.state ?? "not-available" };
+    });
+    return {
+        scope: usage.scope,
+        source: usage.source,
+        onUsagePricing,
+        period: usage.period,
+        meters,
+        ...(usage.storage ? { storage: usage.storage } : {}),
+        notice: readingsNotice(usage.scope, onUsagePricing),
+        readOnly: true,
+    };
+}
 export function buildReport(usage, rates) {
     const bill = computeBill(usage, rates.rates, rates.allowanceUsd);
     return {
@@ -394,7 +426,21 @@ function valueText(m) {
         return `${Math.round(m.value)} vault${Math.round(m.value) === 1 ? "" : "s"}`;
     return `${Math.round(m.value)}`;
 }
+function formatReadingsReport(r) {
+    const who = r.scope.kind === "company" ? r.scope.companySlug : "your personal HQ";
+    const lines = [];
+    lines.push(`Usage for ${who}, ${r.period.start.slice(0, 7)} (as of ${r.period.asOf.slice(0, 10)})`);
+    lines.push("");
+    const nameW = Math.max(...r.meters.map((m) => m.displayName.length));
+    for (const m of r.meters)
+        lines.push(`  ${m.displayName.padEnd(nameW)}  ${valueText(m)}`);
+    lines.push("");
+    lines.push(r.notice);
+    return lines.join("\n");
+}
 export function formatReport(r) {
+    if (isReadingsReport(r))
+        return formatReadingsReport(r);
     const who = r.scope.kind === "company" ? r.scope.companySlug : "your personal HQ";
     const month = r.period.start.slice(0, 7);
     const lines = [];

package/dist/lib/db/local.d.ts

@@ -4,9 +4,9 @@
  * File lives at ~/.hq/db/{company}/vault.db with WAL journal mode.
  * Never returns or logs remote connection strings.
  */
-import Database from "better-sqlite3";
+import type BetterSqlite3 from "better-sqlite3";
 import { type LocalDbPathEnv } from "./paths.js";
-export type LocalDb = Database.Database;
+export type LocalDb = BetterSqlite3.Database;
 export interface OpenLocalDbOptions extends LocalDbPathEnv {
     /** When true, do not create the file if missing (throws). Default false. */
     readonly?: boolean;

package/dist/lib/db/local.js

@@ -5,7 +5,7 @@
  * Never returns or logs remote connection strings.
  */
 import fs from "node:fs";
-import Database from "better-sqlite3";
+import { loadBetterSqlite3 } from "./sqlite-binding.js";
 import { ensureLocalDbDir, resolveLocalDbPath, } from "./paths.js";
 const MIGRATIONS_TABLE = "hq_schema_migrations";
 /**
@@ -33,7 +33,7 @@ export function openLocalDb(companySlug, opts) {
         }
         ensureLocalDbDir(companySlug, opts);
     }
-    const db = new Database(dbPath);
+    const db = new (loadBetterSqlite3())(dbPath);
     // WAL for concurrent readers; safe for agent/CLI workloads.
     db.pragma("journal_mode = WAL");
     db.pragma("foreign_keys = ON");