@indigoai-us/hq-cli 5.107.0 → 5.108.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [5.108.0] — 2026-09-03
+
+### Fixed
+
+- Every `hq` command was reading the whole local sync database before it ran,
+  to pull a single timestamp out of it for the client-health heartbeat. On a
+  machine whose sync store had grown large this cost around 21 seconds of CPU
+  per command — including every `hq secrets` fetch — and the 1.2-second bound
+  the heartbeat claims could not stop it, because the work is synchronous and
+  the timer cannot fire while it runs. The timestamp is now observed at most
+  once every 15 minutes, once per machine rather than once per process, and
+  sync commands still refresh it every time. Measured on an affected machine, a
+  credential fetch went from ~22.6 s to ~1.4 s.
+
+## [5.107.1] — 2026-09-03
+
 ## [5.107.0] — 2026-09-03
 
 ### Added

package/dist/commands/cloud.js

@@ -17,7 +17,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { share, sync, getStateDir, listJournals, loadCachedTokens, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
-import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
+import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintPresentationLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
 import { beginSyncHealthReport, } from "../utils/client-health.js";
 /**
  * Terminal-failure signal for the sync fanout runners. The runners
@@ -283,10 +283,13 @@ export async function pullAll(options, deps) {
         const nudgeExceedsSize = resolvedMode === "all" &&
             entry.companyUid !== undefined &&
             narrowNudgeExceedsSize(options.hqRoot, entry.slug);
-        if (resolvedMode === "all" &&
+        const strictRefusal = resolvedMode === "all" &&
             nudgeExceedsSize &&
             isStrictRefusal(resolvedMode, narrowHintLevel) &&
-            !options.modeAllOverride &&
+            !options.modeAllOverride;
+        const bannerLevel = resolveNarrowHintPresentationLevel(narrowHintLevel, strictRefusal);
+        if (strictRefusal &&
+            resolvedMode === "all" &&
             entry.companyUid) {
             // Emit the strict-level banner once, then mark the leg as errored
             // without invoking sync(). The operator either narrows the
@@ -295,7 +298,7 @@ export async function pullAll(options, deps) {
             emitNarrowHint({
                 companyUid: entry.companyUid,
                 syncMode: resolvedMode,
-                level: narrowHintLevel,
+                level: bannerLevel,
             });
             const message = "Refusing to pull all-mode membership in strict mode. " +
                 "Run `hq sync narrow --apply` to migrate, or re-run with --mode-all.";
@@ -316,7 +319,7 @@ export async function pullAll(options, deps) {
                 emitNarrowHint({
                     companyUid: entry.companyUid,
                     syncMode: resolvedMode,
-                    level: narrowHintLevel,
+                    level: bannerLevel,
                 });
             }
         }
@@ -891,19 +894,22 @@ export function registerCloudCommands(program) {
             const nudgeExceedsSize = resolvedMode === "all" &&
                 resolvedCompanyUid !== undefined &&
                 narrowNudgeExceedsSize(options.hqRoot, options.company);
+            const strictRefusal = resolvedMode === "all" &&
+                nudgeExceedsSize &&
+                isStrictRefusal(resolvedMode, narrowHintLevel) &&
+                options.modeAll !== true;
+            const bannerLevel = resolveNarrowHintPresentationLevel(narrowHintLevel, strictRefusal);
             // Strict-mode refusal: matches runPullAll + runNowSingle behavior.
             // Default banner level is 'hint' which never triggers refusal —
             // wired now so a future release can flip the default to 'strict'
             // (still size-gated) without re-touching this command.
-            if (resolvedMode === "all" &&
-                nudgeExceedsSize &&
-                isStrictRefusal(resolvedMode, narrowHintLevel) &&
-                options.modeAll !== true &&
+            if (strictRefusal &&
+                resolvedMode === "all" &&
                 resolvedCompanyUid) {
                 emitNarrowHint({
                     companyUid: resolvedCompanyUid,
                     syncMode: resolvedMode,
-                    level: narrowHintLevel,
+                    level: bannerLevel,
                 });
                 console.error(chalk.red("\n✗ Pull refused: strict narrow-hint mode is on and this " +
                     "company's local folder has grown large. Run `hq sync narrow --apply` " +
@@ -941,7 +947,7 @@ export function registerCloudCommands(program) {
                 emitNarrowHint({
                     companyUid: resolvedCompanyUid,
                     syncMode: resolvedMode,
-                    level: narrowHintLevel,
+                    level: bannerLevel,
                 });
             }
             await syncHealth.succeeded();
@@ -1406,15 +1412,18 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         const nudgeExceedsSize = resolvedMode === "all" &&
             resolvedCompanyUid !== undefined &&
             narrowNudgeExceedsSize(hqRoot, targetCompany);
-        if (resolvedMode === "all" &&
+        const strictRefusal = resolvedMode === "all" &&
             nudgeExceedsSize &&
             isStrictRefusal(resolvedMode, narrowHintLevel) &&
-            !modeAllOverride &&
+            !modeAllOverride;
+        const bannerLevel = resolveNarrowHintPresentationLevel(narrowHintLevel, strictRefusal);
+        if (strictRefusal &&
+            resolvedMode === "all" &&
             resolvedCompanyUid) {
             emitNarrowHint({
                 companyUid: resolvedCompanyUid,
                 syncMode: resolvedMode,
-                level: narrowHintLevel,
+                level: bannerLevel,
             });
             console.error(chalk.red("\n✗ Sync now refused: strict narrow-hint mode is on and this " +
                 "company's local folder has grown large. Run `hq sync narrow --apply` " +
@@ -1468,7 +1477,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             emitNarrowHint({
                 companyUid: resolvedCompanyUid,
                 syncMode: resolvedMode,
-                level: narrowHintLevel,
+                level: bannerLevel,
             });
         }
         console.log(chalk.green("\n✓ Sync now complete"));

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

@@ -52,6 +52,7 @@
  * first-class skip), and {@link registerMcpServers} is the pack-install routing
  * seam over it.
  */
+import { type FlagReader } from '../lib/flag-registry.js';
 /** Base for every MCP-registration error; carries a stable machine-checkable `code`. */
 export declare abstract class McpRegistrationError extends Error {
     abstract readonly code: string;
@@ -595,6 +596,10 @@ export declare function registerServer(opts: RegisterServerOptions): RegisterSer
  * when neither a url nor a command is present.
  */
 export declare function manifestTarget(manifest: McpManifest): string;
+/** Resolve the gate once at the start of an MCP registration operation. */
+export declare function isMcpRegistrationEnabled(flagReader?: FlagReader): boolean;
+/** Freeze a registration decision so multi-server work cannot split on refresh. */
+export declare function captureMcpRegistrationDecision(flagReader?: FlagReader): FlagReader;
 /**
  * Register one pack's MCP servers into the shared agent configs (the public seam
  * `pack-install` routes `wire:'merge'` keys to). For each declared server name it
@@ -609,6 +614,7 @@ export declare function manifestTarget(manifest: McpManifest): string;
  * @param names   the bare server names from `contributes.mcp`
  * @param options manifest loader + secret resolver + injectable env (all optional;
  *                without a loader this throws, since US-007 has no payload-dir context)
+ *
  * @returns one {@link RegisterServerResult} per server, in `names` order
  */
 export declare function registerMcpServers(pkg: string, names: string[], options?: {
@@ -621,6 +627,8 @@ export declare function registerMcpServers(pkg: string, names: string[], options
     /** Lock tuning + backup stamp passthrough (tests). */
     lock?: AcquireLockOptions;
     stamp?: string;
+    /** Test seam: held registry snapshot reader. */
+    flagReader?: FlagReader;
 }): RegisterServerResult[];
 /** smol-toml's value-table type (its `parse` return + `stringify` input). */
 type TomlTable = Record<string, unknown>;

package/dist/commands/mcp-registration.js

@@ -57,6 +57,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { resolveFlagGate, resolveProcessFlagGate, } from '../lib/flag-registry.js';
 // ---------------------------------------------------------------------------
 // Named error classes (no bare catch-all anywhere in this module).
 //
@@ -1225,6 +1226,29 @@ export function manifestTarget(manifest) {
     }
     return manifest.url ?? '';
 }
+/** Registry vocabulary for the legacy MCP operator kill switch. */
+const MCP_REGISTRATION_LOOKUP = {
+    globalEnvVar: 'HQ_DISABLE_MCP_REGISTRATION',
+    globalValueSemantics: {
+        onValues: [],
+        offValues: ['1'],
+        unrecognizedValue: true,
+        unsetValue: true,
+    },
+    fallback: true,
+};
+const mcpRegistrationLegacyFallback = () => process.env.HQ_DISABLE_MCP_REGISTRATION !== '1';
+/** Resolve the gate once at the start of an MCP registration operation. */
+export function isMcpRegistrationEnabled(flagReader) {
+    return flagReader
+        ? resolveFlagGate(flagReader, 'cli.mcp-registration', MCP_REGISTRATION_LOOKUP, mcpRegistrationLegacyFallback)
+        : resolveProcessFlagGate('cli.mcp-registration', MCP_REGISTRATION_LOOKUP, mcpRegistrationLegacyFallback);
+}
+/** Freeze a registration decision so multi-server work cannot split on refresh. */
+export function captureMcpRegistrationDecision(flagReader) {
+    const enabled = isMcpRegistrationEnabled(flagReader);
+    return { isEnabled: () => enabled };
+}
 /**
  * Register one pack's MCP servers into the shared agent configs (the public seam
  * `pack-install` routes `wire:'merge'` keys to). For each declared server name it
@@ -1239,6 +1263,7 @@ export function manifestTarget(manifest) {
  * @param names   the bare server names from `contributes.mcp`
  * @param options manifest loader + secret resolver + injectable env (all optional;
  *                without a loader this throws, since US-007 has no payload-dir context)
+ *
  * @returns one {@link RegisterServerResult} per server, in `names` order
  */
 export function registerMcpServers(pkg, names, options) {
@@ -1250,14 +1275,14 @@ export function registerMcpServers(pkg, names, options) {
     // ORDERING: this is checked FIRST, BEFORE the loadManifest programmer-error guard
     // below. The kill-switch is a USER/OPERATOR condition; the missing-loadManifest
     // throw is a PROGRAMMER error. An operator who set the kill-switch must never hit a
-    // spurious McpManifestError, so the operator path wins. We read process.env directly
-    // (not options.env — that's the SafeWriteEnv home-path injector, NOT process env);
-    // tests set/unset process.env.HQ_DISABLE_MCP_REGISTRATION around the call.
+    // spurious McpManifestError, so the operator path wins. Its legacy environment
+    // predicate remains the outage fallback; `options.env` is the SafeWriteEnv
+    // home-path injector, not process env.
     //
     // Returns an empty RegisterServerResult[] (`[]`) — the correct "no servers
     // registered" semantic — so callers (pack-install) consume it gracefully. The skip
     // NOTICE is emitted exactly once per registerMcpServers call.
-    if (process.env.HQ_DISABLE_MCP_REGISTRATION === '1') {
+    if (!isMcpRegistrationEnabled(options?.flagReader)) {
         process.stderr.write('MCP registration skipped (HQ_DISABLE_MCP_REGISTRATION=1)\n');
         return [];
     }

package/dist/commands/pack-install.js

@@ -52,7 +52,7 @@ import { safeExtractTarball } from './safe-extract.js';
 import { getCompanyUid, vaultApiFetch, vaultApiFetchPublic, } from '../utils/vault-api.js';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
 import { formatApiKeyCapabilityDenial, peekHqApiKey, } from '../utils/resolve-vault-credential.js';
-import { redactSecrets, SECRET_REDACTION, registerMcpServers, McpManifestError, } from './mcp-registration.js';
+import { redactSecrets, SECRET_REDACTION, captureMcpRegistrationDecision, registerMcpServers, McpManifestError, } from './mcp-registration.js';
 import { listSecretCacheScopes } from '../utils/secrets-cache.js';
 import { loadRevealedSecrets } from './secrets.js';
 const PACK_UPDATE_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
@@ -1492,13 +1492,21 @@ async function wireMcpServers(pkg, destDir, company) {
     const loadManifest = (name) => loadMcpManifestFrom(destDir, name);
     const registered = [];
     const skipped = [];
+    // A refresh may arrive while secret resolution awaits. Freeze the gate before
+    // the loop so an install never writes only an arbitrary prefix of a pack.
+    const flagReader = captureMcpRegistrationDecision();
     for (const name of pkg.contributes.mcp ?? []) {
         try {
             const resolveSecret = await makeInstallSecretResolver(collectManifestSecretNames(loadManifest(name)), company);
             // Per-server call: registerMcpServers throws on the FIRST unresolvable
             // secret, so calling it one name at a time lets us catch + continue.
-            registerMcpServers(pkg.name, [name], { loadManifest, resolveSecret });
-            registered.push(name);
+            const results = registerMcpServers(pkg.name, [name], {
+                loadManifest,
+                resolveSecret,
+                flagReader,
+            });
+            if (results.length > 0)
+                registered.push(name);
         }
         catch (e) {
             const isUnresolvableSecret = e instanceof McpManifestError && /cannot resolve \$\{secret:/.test(e.message);

package/dist/commands/reindex.d.ts

@@ -11,5 +11,20 @@ export declare function removeStaleHqWorktrees(hqRoot: string, now?: number, dea
  * malformed configurations remain untouched and receive recovery guidance.
  */
 export declare function repairExtremeHookDrift(hqRoot: string, allowRepair?: boolean): void;
+/**
+ * Stop the generated project settings from silently downgrading an operator who
+ * chose Bypass mode globally.
+ *
+ * Claude Code resolves `permissions.defaultMode` project-over-user, so ANY value
+ * in the HQ root's `.claude/settings.json` — including HQ's own shipped "plan" —
+ * outranks `bypassPermissions` in `~/.claude/settings.json`. The operator sets
+ * bypass once at user scope and then every HQ session boots in some other mode
+ * with no indication why. When that user-scope choice is present, drop the
+ * project key so their own mode is what actually applies.
+ *
+ * `.claude/settings.local.json` is the operator's deliberate per-machine layer
+ * and outranks both scopes; it is never touched.
+ */
+export declare function dropProjectDefaultModeForBypassUser(hqRoot: string): void;
 export declare function registerReindexCommand(program: Command): void;
 //# sourceMappingURL=reindex.d.ts.map

package/dist/commands/reindex.js

@@ -25,6 +25,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import * as yaml from 'js-yaml';
 import { reindex, rescue } from '@indigoai-us/hq-cloud';
@@ -32,6 +33,7 @@ import { trustHqRuntimeHooks } from '../utils/hook-trust.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { guardLargeFiles } from '../utils/large-file-guard.js';
 const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse'];
+const BYPASS_MODE = 'bypassPermissions';
 const HOOK_CHECK_RELATIVE_PATH = path.join('core', 'scripts', 'check-hq-hooks.sh');
 const WORKTREE_STALE_AFTER_MS = 12 * 60 * 60 * 1_000;
 const WORKTREE_GIT_TIMEOUT_MS = 2_000;
@@ -470,6 +472,119 @@ export function repairExtremeHookDrift(hqRoot, allowRepair = true) {
         printHookHealthWarning(hqRoot, 'hook configuration repair could not run');
     }
 }
+/**
+ * Resolve the user-scope Claude settings file — CLAUDE_CONFIG_DIR when the
+ * operator relocated their Claude config, otherwise ~/.claude/settings.json.
+ */
+function userClaudeSettingsPath() {
+    const configDir = process.env.CLAUDE_CONFIG_DIR?.trim();
+    if (configDir)
+        return path.join(path.resolve(configDir), 'settings.json');
+    const home = process.env.HOME?.trim() || os.homedir();
+    if (!home)
+        return undefined;
+    return path.join(home, '.claude', 'settings.json');
+}
+/** Parse a settings file into a plain object, or undefined when it is absent or malformed. */
+function readSettingsObject(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        // Absent (or unreadable) user/project settings simply means there is no
+        // override to reconcile. Hook health reports a broken project file already.
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function permissionsObject(settings) {
+    const permissions = settings?.permissions;
+    if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions))
+        return undefined;
+    return permissions;
+}
+function declaredDefaultMode(settings) {
+    const mode = permissionsObject(settings)?.defaultMode;
+    return typeof mode === 'string' ? mode : undefined;
+}
+/**
+ * Replace a file through a same-directory temporary file and a rename, so a
+ * failed or interrupted write can never leave a truncated `.claude/settings.json`
+ * behind — that file carries every hook registration HQ depends on.
+ */
+function writeFileAtomically(target, contents) {
+    const temporary = path.join(path.dirname(target), `.${path.basename(target)}.reindex-${process.pid}.tmp`);
+    try {
+        fs.writeFileSync(temporary, contents);
+        // Keep whatever mode the operator had on the original; a fresh temp file
+        // would otherwise hand back umask defaults on every rewrite.
+        try {
+            fs.chmodSync(temporary, fs.statSync(target).mode & 0o777);
+        }
+        catch {
+            // A missing or unstattable original just means the default mode applies.
+        }
+        fs.renameSync(temporary, target);
+    }
+    catch (err) {
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch {
+            // Best-effort cleanup; the original file is still intact either way.
+        }
+        throw err;
+    }
+}
+/**
+ * Stop the generated project settings from silently downgrading an operator who
+ * chose Bypass mode globally.
+ *
+ * Claude Code resolves `permissions.defaultMode` project-over-user, so ANY value
+ * in the HQ root's `.claude/settings.json` — including HQ's own shipped "plan" —
+ * outranks `bypassPermissions` in `~/.claude/settings.json`. The operator sets
+ * bypass once at user scope and then every HQ session boots in some other mode
+ * with no indication why. When that user-scope choice is present, drop the
+ * project key so their own mode is what actually applies.
+ *
+ * `.claude/settings.local.json` is the operator's deliberate per-machine layer
+ * and outranks both scopes; it is never touched.
+ */
+export function dropProjectDefaultModeForBypassUser(hqRoot) {
+    // As with the hook repair: `hq reindex` can run from an arbitrary directory,
+    // and only a real HQ root's settings are ours to rewrite.
+    if (!isHqRoot(hqRoot))
+        return;
+    const userSettingsPath = userClaudeSettingsPath();
+    if (!userSettingsPath)
+        return;
+    if (declaredDefaultMode(readSettingsObject(userSettingsPath)) !== BYPASS_MODE)
+        return;
+    const settingsPath = path.join(hqRoot, '.claude', 'settings.json');
+    const settings = readSettingsObject(settingsPath);
+    const permissions = permissionsObject(settings);
+    const projectMode = declaredDefaultMode(settings);
+    if (!settings || !permissions || projectMode === undefined || projectMode === BYPASS_MODE)
+        return;
+    delete permissions.defaultMode;
+    try {
+        writeFileAtomically(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    }
+    catch (err) {
+        console.warn(`reindex: could not drop permissions.defaultMode "${projectMode}" from ${settingsPath} — ${err instanceof Error ? err.message : String(err)}\nHQ sessions will keep booting in "${projectMode}" instead of the bypassPermissions mode set in ${userSettingsPath}.`);
+        return;
+    }
+    console.log(`reindex: dropped permissions.defaultMode "${projectMode}" from .claude/settings.json — ${userSettingsPath} sets ${BYPASS_MODE}`);
+}
 /**
  * Keep files above GitHub's 100MB limit out of the HQ repo, and say so.
  *
@@ -528,6 +643,11 @@ export function registerReindexCommand(program) {
         const { status } = reindex({ repoRoot: opts.repoRoot });
         repairExtremeHookDrift(hqRoot, status === 0);
         if (status === 0) {
+            // Only safe once reindex actually ran: a refused --from-hook reindex
+            // 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.
+            dropProjectDefaultModeForBypassUser(hqRoot);
             await trustHqRuntimeHooks(hqRoot, undefined, {
                 rootAliases: [literalHqRoot],
                 // A lifecycle hook must never block the agent waiting on another HQ

package/dist/commands/secrets.d.ts

@@ -28,6 +28,7 @@ export interface SecretMetadata {
 export interface SecretLoadSuccessRow extends SecretMetadata {
     name: string;
     value?: string;
+    version?: number;
 }
 export interface SecretLoadResponse {
     secrets: SecretLoadSuccessRow[];

package/dist/commands/secrets.js

@@ -4,7 +4,7 @@ import { spawn } from "node:child_process";
 import { writeSync } from "node:fs";
 import * as nodePath from "node:path";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { DEFAULT_SECRETS_CACHE_TTL_MS, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
+import { DEFAULT_SECRETS_CACHE_TTL_MS, hasCacheEntry, readCache, writeCache, removeCacheEntry, clearAllCache, } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
@@ -545,7 +545,12 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
     }
     const resolved = new Map();
     const requested = [...new Set(keys)];
+    const cachedCandidates = new Set(requested.filter((name) => hasCacheEntry(companyUid, name)));
     try {
+        // The batch endpoint is the only non-capturing authorization path that also
+        // evaluates the supplied usage metadata. It covers warm and cold names in
+        // bounded requests, then a warm name may use its locally authenticated
+        // plaintext only when the returned version and current policy TTL agree.
         for (let i = 0; i < requested.length; i += MAX_BATCH_NAMES) {
             const chunk = requested.slice(i, i + MAX_BATCH_NAMES);
             const chunkNames = new Set(chunk);
@@ -572,6 +577,9 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
                     typeof body.code === "string") {
                     throw new Error(message);
                 }
+                if (res.status === 403) {
+                    throw new Error(`Failed to fetch secret '${chunk[0]}': No read permission`);
+                }
                 throw new Error(`Failed to batch-load secrets: ${message}`);
             }
             const data = (await res.json());
@@ -601,8 +609,26 @@ export async function loadRevealedSecrets(token, companyUid, keys, usage) {
                     continue;
                 }
                 const cacheTtlMs = normalizeCacheTtlMs(s);
+                const cached = cachedCandidates.has(s.name) &&
+                    cacheTtlMs > 0 &&
+                    typeof s.version === "number" &&
+                    Number.isSafeInteger(s.version) &&
+                    s.version > 0
+                    ? readCache(companyUid, s.name, s.version, cacheTtlMs)
+                    : null;
+                if (cached !== null) {
+                    resolved.set(s.name, cached);
+                    continue;
+                }
                 if (cacheTtlMs > 0) {
-                    writeCache(companyUid, s.name, s.value, cacheTtlMs);
+                    if (typeof s.version === "number" &&
+                        Number.isSafeInteger(s.version) &&
+                        s.version > 0) {
+                        writeCache(companyUid, s.name, s.value, cacheTtlMs, s.version);
+                    }
+                    else {
+                        writeCache(companyUid, s.name, s.value, cacheTtlMs);
+                    }
                 }
                 else {
                     removeCacheEntry(companyUid, s.name);

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

@@ -20,6 +20,7 @@
  *
  * Exit codes: 0 = allow, 2 = block.
  */
+import { type FlagReader } from "../flag-registry.js";
 /**
  * Worst-case inner deadline (seconds) declared in a command: a `timeout` /
  * `gtimeout` prefix (matched by executable BASENAME, so `/usr/bin/timeout`
@@ -50,9 +51,11 @@ export interface TimeoutGuardDeps {
     getEmail?: () => string | undefined;
     env?: NodeJS.ProcessEnv;
     stderr?: NodeJS.WritableStream;
+    /** Test seam: held registry snapshot reader. */
+    flagReader?: FlagReader;
 }
 /** Whether the guard is active for this identity (rollout gate). */
-export declare function isGatedUser(email: string | undefined): boolean;
+export declare function isGatedUser(email: string | undefined, flagReader?: FlagReader): boolean;
 /**
  * Command entry: read the PreToolUse JSON, apply the gate + short-circuits, and
  * return the exit code (0 allow / 2 block). Never throws — a parse failure or a

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

@@ -22,6 +22,7 @@
  */
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { peekIdToken } from "../../utils/id-token.js";
+import { resolveFlagGate, resolveProcessFlagGate, } from "../flag-registry.js";
 // Observed Claude Code Bash-tool bounds. The tool `timeout` (ms) raises the
 // deadline up to the max; with none declared the default applies.
 const HARNESS_DEFAULT_MS = 120_000; // 2 min
@@ -165,8 +166,16 @@ function defaultEmail() {
     }
 }
 /** Whether the guard is active for this identity (rollout gate). */
-export function isGatedUser(email) {
-    return typeof email === "string" && email.toLowerCase().endsWith(GATE_DOMAIN);
+export function isGatedUser(email, flagReader) {
+    const legacyFallback = () => typeof email === "string" && email.toLowerCase().endsWith(GATE_DOMAIN);
+    const lookup = {
+        defaultEmailDomains: ["getindigo.ai"],
+        personEmail: email,
+        fallback: legacyFallback(),
+    };
+    return flagReader
+        ? resolveFlagGate(flagReader, "cli.foreground-timeout-guard", lookup, legacyFallback)
+        : resolveProcessFlagGate("cli.foreground-timeout-guard", lookup, legacyFallback);
 }
 /**
  * Command entry: read the PreToolUse JSON, apply the gate + short-circuits, and
@@ -194,7 +203,7 @@ export function timeoutGuardCommand(stdin, deps = {}) {
         return 0;
     // Rollout gate: only act for @getindigo.ai identities.
     const getEmail = deps.getEmail ?? defaultEmail;
-    if (!isGatedUser(getEmail()))
+    if (!isGatedUser(getEmail(), deps.flagReader))
         return 0;
     const runInBackground = ti.run_in_background === true;
     const toolTimeoutMs = typeof ti.timeout === "number" ? ti.timeout : undefined;

package/dist/lib/flag-registry-worker.d.ts

@@ -0,0 +1,3 @@
+/** One unref'd registry refresh for the short-lived Node CLI process. */
+export {};
+//# sourceMappingURL=flag-registry-worker.d.ts.map

package/dist/lib/flag-registry-worker.js

@@ -0,0 +1,26 @@
+/** One unref'd registry refresh for the short-lived Node CLI process. */
+import { parentPort, workerData } from "node:worker_threads";
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { createFlagClient } from "@indigoai-us/hq-flags-client";
+const endpoint = workerData.endpoint;
+async function refresh() {
+    if (!parentPort || typeof endpoint !== "string" || endpoint.trim() === "")
+        return;
+    try {
+        const client = createFlagClient({
+            endpoint,
+            getToken: () => loadCachedTokens()?.idToken ?? "",
+            refreshIntervalMs: 0,
+            onError: () => { },
+        });
+        await client.ready();
+        const snapshot = client.snapshot();
+        if (snapshot)
+            parentPort.postMessage(snapshot);
+    }
+    catch {
+        // The parent is deliberately fail-open and has the legacy fallback.
+    }
+}
+void refresh();
+//# sourceMappingURL=flag-registry-worker.js.map

package/dist/lib/flag-registry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Process-wide, fail-open bridge to the HQ flag registry.
+ *
+ * Command gates read an in-memory snapshot synchronously. The first refresh is
+ * isolated in an unref'd worker because an unawaited Node fetch can otherwise
+ * keep a short-lived, offline CLI alive until the client's network deadline.
+ */
+import { type WorkerOptions } from "node:worker_threads";
+import { type FlagClient, type FlagLookupOptions } from "@indigoai-us/hq-flags-client";
+/** Dedicated endpoint configuration; this is intentionally not HQ_PRO_API_URL. */
+export declare const FLAG_REGISTRY_ENDPOINT_ENV = "HQ_FLAGS_API_URL";
+/** The synchronous capability that command gate call sites need. */
+export type FlagReader = Pick<FlagClient, "isEnabled">;
+interface WorkerLike {
+    on(event: "message", listener: (value: unknown) => void): unknown;
+    on(event: "error", listener: () => void): unknown;
+    unref(): void;
+}
+export interface FlagRegistryDependencies {
+    endpoint?: string;
+    createWorker?: (filename: URL, options: WorkerOptions) => WorkerLike;
+}
+/**
+ * Begin one registry refresh without awaiting it or retaining the CLI process.
+ *
+ * The worker owns cached-token I/O, token use, and the potentially slow fetch.
+ * Its response is accepted only after the client has validated it as a flag
+ * snapshot. Consequently, every command path is an immediate in-memory read:
+ * a missing, unauthenticated, slow, or offline worker leaves `heldSnapshot`
+ * null and the caller's exact legacy fallback decides the gate.
+ */
+export declare function kickFlagRegistryReadiness(dependencies?: FlagRegistryDependencies): FlagReader | null;
+/**
+ * Evaluate a registry-backed gate without changing its outage default.
+ * `isEnabled` itself is synchronous and snapshot-only; any reader failure
+ * falls through to the exact legacy predicate owned by the caller.
+ */
+export declare function resolveFlagGate(reader: FlagReader | null | undefined, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean): boolean;
+/** Resolve a process gate against the shared snapshot reader, when configured. */
+export declare function resolveProcessFlagGate(flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean): boolean;
+/** Test-only reset for process-global readiness state. */
+export declare function _resetFlagRegistryForTests(): void;
+export {};
+//# sourceMappingURL=flag-registry.d.ts.map