@indigoai-us/hq-cli 5.275.0 → 5.276.0

package/dist/lib/checkpoint-ontology/queued-touches.js

@@ -0,0 +1,193 @@
+/**
+ * Company files touched by checkpoints that were queued behind a busy sibling.
+ *
+ * `hq core checkpoint` queues its payload when a sibling is already running,
+ * and the next run claims the queue. That run renders the ontology step only
+ * for its own payload's company, and the ontology plan records any changed
+ * file the run's own payload did not touch as seen. Without this file, the
+ * files a queued company checkpoint touched never reach the ontology (CO-59).
+ *
+ * The checkpoint parent performs no network I/O, so it cannot read the
+ * `checkpoint.ontology.queued-touches` flag. It always records the touches in
+ * the company's local, unsynced state directory; the ontology plan consumes
+ * them only while the flag is on. The file is capped so it stays small while
+ * the flag is off.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { assertSafeTarget, resolveOntologyCompany, safeWriteFile, WriteBoundsError, } from "./company.js";
+export const QUEUED_TOUCHES_FILE = "queued-touches.jsonl";
+export const QUEUED_TOUCHES_CLAIM_FILE = "queued-touches-claimed.jsonl";
+export const QUEUED_TOUCHES_BORROWED_FILE = "queued-touches-borrowed-at";
+export const MAX_QUEUED_TOUCHES = 200;
+function ontologyStateBase(hqRoot) {
+    return path.join(hqRoot, "workspace", "checkpoints", "ontology");
+}
+function companyStateDir(hqRoot, slug) {
+    return path.join(ontologyStateBase(hqRoot), slug);
+}
+export function queuedTouchesPath(hqRoot, slug) {
+    return path.join(companyStateDir(hqRoot, slug), QUEUED_TOUCHES_FILE);
+}
+/**
+ * Record the files a queued checkpoint touched inside its company. Files
+ * outside `companies/<slug>/` are dropped. Returns the number of files
+ * recorded; 0 when the company is not a manifest company or nothing is inside
+ * it. The queue keeps its newest {@link MAX_QUEUED_TOUCHES} lines.
+ */
+export function recordQueuedTouches(hqRoot, slug, files, now) {
+    if (!slug)
+        return 0;
+    const resolution = resolveOntologyCompany(hqRoot, slug);
+    if (!resolution.ok)
+        return 0;
+    const inside = files.filter((file) => {
+        if (typeof file !== "string" || !file.trim())
+            return false;
+        const rel = path.relative(resolution.company.dir, path.resolve(hqRoot, file.trim()));
+        return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+    });
+    if (inside.length === 0)
+        return 0;
+    const target = queuedTouchesPath(hqRoot, slug);
+    try {
+        assertSafeTarget(hqRoot, [companyStateDir(hqRoot, slug)], target);
+    }
+    catch (error) {
+        if (error instanceof WriteBoundsError)
+            return 0;
+        throw error;
+    }
+    const fd = fs.openSync(target, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW);
+    try {
+        fs.writeSync(fd, `${JSON.stringify({ queued_at: now.toISOString(), files: inside })}\n`);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const lines = fs.readFileSync(target, "utf8").split("\n").filter((line) => line.trim());
+    if (lines.length > MAX_QUEUED_TOUCHES) {
+        // Best-effort trim, as for the sibling's pending queue: it can race a
+        // concurrent append, but only once the file is already over its cap.
+        safeWriteFile(hqRoot, [companyStateDir(hqRoot, slug)], target, `${lines.slice(-MAX_QUEUED_TOUCHES).join("\n")}\n`);
+    }
+    return inside.length;
+}
+/**
+ * Record that a company-less run borrowed `slug`, so the next such run prefers
+ * a company that has waited longer.
+ */
+export function markBorrowed(hqRoot, slug, now) {
+    const target = path.join(companyStateDir(hqRoot, slug), QUEUED_TOUCHES_BORROWED_FILE);
+    safeWriteFile(hqRoot, [companyStateDir(hqRoot, slug)], target, `${now.toISOString()}\n`);
+}
+/** `queued_at` of the oldest record, or the file mtime when no line has one. */
+function firstQueuedMs(file, mtimeMs) {
+    for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.queued_at !== "string")
+                continue;
+            const ms = Date.parse(parsed.queued_at);
+            if (!Number.isNaN(ms))
+                return ms;
+        }
+        catch {
+            // A partial line is not a record; a later valid line still counts.
+        }
+    }
+    return mtimeMs;
+}
+/** When this company was last borrowed, or -Infinity when it never was. */
+function borrowedMs(hqRoot, slug) {
+    const file = path.join(companyStateDir(hqRoot, slug), QUEUED_TOUCHES_BORROWED_FILE);
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch {
+        return Number.NEGATIVE_INFINITY;
+    }
+    if (!stat.isFile())
+        return Number.NEGATIVE_INFINITY;
+    const ms = Date.parse(fs.readFileSync(file, "utf8").trim());
+    return Number.isNaN(ms) ? Number.NEGATIVE_INFINITY : ms;
+}
+/**
+ * The manifest company whose queued touches have waited longest, or null.
+ * The order key is the later of the first queued record and the last borrow,
+ * so a company a company-less run just borrowed goes to the back. A run whose
+ * own payload names no company uses it for its ontology step.
+ */
+export function oldestQueuedCompany(hqRoot) {
+    let entries;
+    try {
+        entries = fs.readdirSync(ontologyStateBase(hqRoot));
+    }
+    catch {
+        return null;
+    }
+    let oldest = null;
+    for (const slug of entries.sort()) {
+        let stat;
+        try {
+            stat = fs.lstatSync(queuedTouchesPath(hqRoot, slug));
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile() || stat.size === 0)
+            continue;
+        if (!resolveOntologyCompany(hqRoot, slug).ok)
+            continue;
+        const key = Math.max(firstQueuedMs(queuedTouchesPath(hqRoot, slug), stat.mtimeMs), borrowedMs(hqRoot, slug));
+        if (!oldest || key < oldest.key)
+            oldest = { slug, key };
+    }
+    return oldest?.slug ?? null;
+}
+/**
+ * Take the company's queued touches by renaming the file into the run
+ * directory, then return the HQ-relative paths it lists. Renaming is atomic,
+ * so a touch recorded during the claim lands in a fresh file for a later run.
+ */
+export function claimQueuedTouches(hqRoot, company, runDir) {
+    const queuedPath = queuedTouchesPath(hqRoot, company.slug);
+    try {
+        assertSafeTarget(hqRoot, [companyStateDir(hqRoot, company.slug)], queuedPath);
+    }
+    catch (error) {
+        if (error instanceof WriteBoundsError)
+            return [];
+        throw error;
+    }
+    const claimPath = path.join(runDir, QUEUED_TOUCHES_CLAIM_FILE);
+    try {
+        fs.renameSync(queuedPath, claimPath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const files = [];
+    for (const line of fs.readFileSync(claimPath, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (Array.isArray(parsed.files)) {
+                for (const file of parsed.files)
+                    if (typeof file === "string")
+                        files.push(file);
+            }
+        }
+        catch {
+            // A partial line must not drop the valid lines around it.
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=queued-touches.js.map

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

@@ -0,0 +1,7 @@
+/** 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

@@ -0,0 +1,40 @@
+/** 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,
+    });
+}
+//# sourceMappingURL=timeout-guard-native.js.map

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

@@ -20,7 +20,7 @@
  *
  * Exit codes: 0 = allow, 2 = block.
  */
-import { type FlagReader } from "../flag-registry.js";
+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`
@@ -55,11 +55,11 @@ export interface TimeoutGuardDeps {
     flagReader?: FlagReader;
 }
 /** Whether the guard is active for this identity (rollout gate). */
-export declare function isGatedUser(email: string | undefined, flagReader?: FlagReader): boolean;
+export declare function isGatedUser(email: string | undefined, flagReader?: FlagReader): Promise<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
  * missing identity fails OPEN (allow), because a hook must not break tool calls.
  */
-export declare function timeoutGuardCommand(stdin: string, deps?: TimeoutGuardDeps): number;
+export declare function timeoutGuardCommand(stdin: string, deps?: TimeoutGuardDeps): Promise<number>;
 //# sourceMappingURL=timeout-guard.d.ts.map

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

@@ -20,9 +20,6 @@
  *
  * Exit codes: 0 = allow, 2 = block.
  */
-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
@@ -153,8 +150,14 @@ supervise yourself.)
 
 Policy: hq-foreground-timeout-killed-by-harness-deadline.
 Bypass for one sanctioned foreground run: prefix HQ_ALLOW_LONG_FOREGROUND=1.`;
-function defaultEmail() {
+async function defaultEmail() {
     try {
+        // The cached identity is needed only for commands that would otherwise
+        // block. Keep hq-cloud and the JWT decoder out of the common allow path.
+        const [{ loadCachedTokens }, { peekIdToken }] = await Promise.all([
+            import("@indigoai-us/hq-cloud"),
+            import("../../utils/id-token.js"),
+        ]);
         const cached = loadCachedTokens();
         if (!cached)
             return undefined;
@@ -166,23 +169,35 @@ function defaultEmail() {
     }
 }
 /** Whether the guard is active for this identity (rollout gate). */
-export function isGatedUser(email, flagReader) {
+export async 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);
+    if (flagReader) {
+        try {
+            return flagReader.isEnabled("cli.foreground-timeout-guard", lookup);
+        }
+        catch {
+            return legacyFallback();
+        }
+    }
+    try {
+        const { resolveProcessFlagGate } = await import("../flag-registry.js");
+        return resolveProcessFlagGate("cli.foreground-timeout-guard", lookup, legacyFallback);
+    }
+    catch {
+        return legacyFallback();
+    }
 }
 /**
  * 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
  * missing identity fails OPEN (allow), because a hook must not break tool calls.
  */
-export function timeoutGuardCommand(stdin, deps = {}) {
+export async function timeoutGuardCommand(stdin, deps = {}) {
     const env = deps.env ?? process.env;
     const err = deps.stderr ?? process.stderr;
     let payload;
@@ -201,15 +216,15 @@ export function timeoutGuardCommand(stdin, deps = {}) {
         return 0;
     if (/(^|\s)HQ_ALLOW_LONG_FOREGROUND=1(\s|$)/.test(command))
         return 0;
-    // Rollout gate: only act for @getindigo.ai identities.
-    const getEmail = deps.getEmail ?? defaultEmail;
-    if (!isGatedUser(getEmail(), deps.flagReader))
-        return 0;
     const runInBackground = ti.run_in_background === true;
     const toolTimeoutMs = typeof ti.timeout === "number" ? ti.timeout : undefined;
     const verdict = evaluateTimeoutGuard({ command, toolTimeoutMs, runInBackground });
     if (!verdict.block)
         return 0;
+    // Rollout gate: only act for @getindigo.ai identities.
+    const getEmail = deps.getEmail ?? defaultEmail;
+    if (!await isGatedUser(await getEmail(), deps.flagReader))
+        return 0;
     err.write(`${BLOCK_MESSAGE(verdict.reason ?? "declared timeout exceeds the harness ceiling")}\n`);
     return 2;
 }

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

@@ -6,7 +6,9 @@
  * 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, type FlagSnapshot } from "@indigoai-us/hq-flags-client";
+import { createFlagClient, type FlagClient, type FlagLookupOptions, type FlagSnapshot } from "@indigoai-us/hq-flags-client";
+export { resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
+export type { ProcessFlagCompanyContext } from "./process-flag-company-context.js";
 export { FLAG_REGISTRY_ENDPOINT_ENV } from "./flag-registry-endpoint.js";
 /** The synchronous capability that command gate call sites need. */
 export type FlagReader = Pick<FlagClient, "isEnabled">;
@@ -22,12 +24,13 @@ export interface FlagRegistryDependencies {
     workerSource?: string;
     captureWorkerFailure?: (error: Error, tags: Record<string, string>) => void;
 }
-export interface ProcessFlagCompanyContext {
-    companyUid?: string;
-    companySlug?: string;
+export interface CompanyFlagGateDependencies {
+    endpoint?: string;
+    requestTimeoutMs?: number;
+    createClient?: typeof createFlagClient;
 }
-/** Resolve the same company identity used by the process-wide flag reader. */
-export declare function resolveProcessFlagCompanyContext(env?: NodeJS.ProcessEnv): ProcessFlagCompanyContext;
+/** Create the same snapshot-backed reader used by process gates. */
+export declare function createProcessSnapshotReader(companyIdentifiers: string[], getSnapshot?: () => FlagSnapshot | null, env?: NodeJS.ProcessEnv): FlagReader;
 /**
  * Begin one registry refresh without awaiting it or retaining the CLI process.
  *
@@ -43,7 +46,9 @@ export declare function kickFlagRegistryReadiness(dependencies?: FlagRegistryDep
  * `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;
+export declare function resolveFlagGate(reader: FlagReader | null | undefined, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean, env?: NodeJS.ProcessEnv): boolean;
+/** Resolve one explicit company's flag without relying on process-wide binding. */
+export declare function resolveCompanyFlagGate(companyUid: string, idToken: string, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean, dependencies?: CompanyFlagGateDependencies): Promise<boolean>;
 /** Resolve a process gate against the shared snapshot reader, when configured. */
 export declare function resolveProcessFlagGate(flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean): boolean;
 /**

package/dist/lib/flag-registry.js

@@ -7,99 +7,43 @@
  */
 import { Worker } from "node:worker_threads";
 import * as Sentry from "@sentry/node";
-import { isFlagSnapshot, readLocalOverride, resolveFlag, } from "@indigoai-us/hq-flags-client";
-import { readMachineCompanyBinding } from "./work-context/company.js";
-import { readSessionState } from "./work-context/state.js";
-import { workContextRoot } from "./work-context/paths.js";
-import { readCompaniesManifestMap } from "./work-context/repo-remote.js";
-import { resolveDefaultHqRoot } from "../utils/cognito-session.js";
+import { createFlagClient, isFlagSnapshot, readLocalOverride, resolveFlag, } from "@indigoai-us/hq-flags-client";
 import { resolveFlagRegistryEndpoint, } from "./flag-registry-endpoint.js";
 import { FLAG_REGISTRY_WORKER_SOURCE } from "./flag-registry-worker-source.generated.js";
+import { resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
+import { writeFlagSnapshotFile } from "./flag-snapshot-file.js";
+export { resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
 export { FLAG_REGISTRY_ENDPOINT_ENV } from "./flag-registry-endpoint.js";
 const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
-const COMPANY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-let heldSnapshot = null;
-let processReader = null;
-function processLocalOverride(flagKey) {
-    return readLocalOverride(flagKey, process.env);
-}
-function localOverrideOrFallback(flagKey, legacyFallback) {
-    return processLocalOverride(flagKey) ?? legacyFallback();
-}
 function normalizedCompanyUid(value) {
     const candidate = value?.trim() ?? "";
     return COMPANY_UID_RE.test(candidate) ? candidate : undefined;
 }
-function normalizedCompanySlug(value) {
-    const candidate = value?.trim() ?? "";
-    return COMPANY_SLUG_RE.test(candidate) ? candidate : undefined;
-}
-/**
- * Resolve only an explicit machine/session company binding. Device defaults
- * and cwd/repository heuristics do not scope process-wide feature flags.
- */
-function processCompanyContext(env = process.env) {
-    const explicitUid = normalizedCompanyUid(env.HQ_COMPANY_UID);
-    const explicitSlug = normalizedCompanySlug(env.HQ_COMPANY_SLUG);
-    if (explicitUid || explicitSlug) {
-        return { companyUid: explicitUid, companySlug: explicitSlug };
-    }
-    const machine = readMachineCompanyBinding(env);
-    const spawnValue = env.HQ_SPAWN_COMPANY?.trim();
-    const spawnSlug = normalizedCompanySlug(spawnValue);
-    const machineContext = spawnValue && COMPANY_UID_RE.test(spawnValue)
-        ? { companyUid: spawnValue }
-        : spawnSlug
-            ? { companySlug: spawnSlug }
-            : {
-                companyUid: normalizedCompanyUid(machine?.uid),
-                companySlug: normalizedCompanySlug(machine?.slug),
-            };
-    if (machineContext.companyUid || machineContext.companySlug)
-        return machineContext;
-    const sessionId = env.HQ_SESSION_ID?.trim();
-    if (!sessionId)
-        return {};
-    const session = readSessionState(sessionId, workContextRoot(undefined, env));
-    if (session?.contextStatus !== "bound" || session.companyConfidence === "device_default") {
-        return {};
-    }
-    return {
-        companyUid: normalizedCompanyUid(session.companyUid),
-        companySlug: normalizedCompanySlug(session.companySlug),
-    };
-}
-function companyUidForContext(context, env = process.env) {
-    if (context.companyUid)
-        return context.companyUid;
-    if (!context.companySlug)
-        return undefined;
-    const hqRoot = resolveDefaultHqRoot({ env });
-    const manifestUid = readCompaniesManifestMap(hqRoot)?.[context.companySlug]?.cloud_uid;
-    return typeof manifestUid === "string" ? normalizedCompanyUid(manifestUid) : undefined;
+let heldSnapshot = null;
+let processReader = null;
+function processLocalOverride(flagKey, env = process.env) {
+    return readLocalOverride(flagKey, env);
 }
-/** Resolve the same company identity used by the process-wide flag reader. */
-export function resolveProcessFlagCompanyContext(env = process.env) {
-    const context = processCompanyContext(env);
-    const companyUid = companyUidForContext(context, env);
-    return {
-        ...(companyUid ? { companyUid } : {}),
-        ...(context.companySlug ? { companySlug: context.companySlug } : {}),
-    };
+function localOverrideOrFallback(flagKey, legacyFallback, env = process.env) {
+    return processLocalOverride(flagKey, env) ?? legacyFallback();
 }
-function processSnapshotReader(companyIdentifiers) {
+/** Create the same snapshot-backed reader used by process gates. */
+export function createProcessSnapshotReader(companyIdentifiers, getSnapshot = () => heldSnapshot, env = process.env) {
     return {
         isEnabled(flagKey, lookup = {}) {
             return resolveFlag({
                 flagKey,
-                env: process.env,
-                snapshot: heldSnapshot,
+                env,
+                snapshot: getSnapshot(),
                 companyIdentifiers,
                 lookup,
             }).value;
         },
     };
 }
+function processSnapshotReader(companyIdentifiers) {
+    return createProcessSnapshotReader(companyIdentifiers);
+}
 /**
  * Begin one registry refresh without awaiting it or retaining the CLI process.
  *
@@ -150,6 +94,19 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
         worker.on("message", (value) => {
             if (isFlagSnapshot(value)) {
                 heldSnapshot = value;
+                if (companyUid) {
+                    try {
+                        writeFlagSnapshotFile(companyUid, value.flags);
+                    }
+                    catch (error) {
+                        Sentry.captureException(error, {
+                            tags: {
+                                component: "flag-snapshot-cache-write",
+                                company_uid_present: "true",
+                            },
+                        });
+                    }
+                }
             }
         });
         // A failed background refresh must stay invisible to an offline CLI.
@@ -169,15 +126,49 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
  * `isEnabled` itself is synchronous and snapshot-only; any reader failure
  * falls through to the exact legacy predicate owned by the caller.
  */
-export function resolveFlagGate(reader, flagKey, lookup, legacyFallback) {
+export function resolveFlagGate(reader, flagKey, lookup, legacyFallback, env = process.env) {
     if (!reader)
-        return localOverrideOrFallback(flagKey, legacyFallback);
+        return localOverrideOrFallback(flagKey, legacyFallback, env);
     try {
         return reader.isEnabled(flagKey, lookup);
     }
     catch {
+        return localOverrideOrFallback(flagKey, legacyFallback, env);
+    }
+}
+/** Resolve one explicit company's flag without relying on process-wide binding. */
+export async function resolveCompanyFlagGate(companyUid, idToken, flagKey, lookup, legacyFallback, dependencies = {}) {
+    const localOverride = processLocalOverride(flagKey);
+    if (localOverride !== null)
+        return localOverride;
+    const targetCompanyUid = normalizedCompanyUid(companyUid);
+    if (!targetCompanyUid || idToken.trim() === "") {
         return localOverrideOrFallback(flagKey, legacyFallback);
     }
+    let client;
+    try {
+        client = (dependencies.createClient ?? createFlagClient)({
+            endpoint: resolveFlagRegistryEndpoint(dependencies.endpoint, process.env),
+            getToken: () => idToken,
+            companyUid: targetCompanyUid,
+            refreshIntervalMs: 0,
+            requestTimeoutMs: dependencies.requestTimeoutMs ?? 1_200,
+            onError: (error) => {
+                const errorClass = error instanceof Error ? error.name : "unknown";
+                console.error(`hq: Could not resolve a company flag (${errorClass}); using its fallback.`);
+            },
+        });
+        await client.ready();
+        return resolveFlagGate(client, flagKey, lookup, legacyFallback);
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown";
+        console.error(`hq: Could not resolve a company flag (${errorClass}); using its fallback.`);
+        return localOverrideOrFallback(flagKey, legacyFallback);
+    }
+    finally {
+        client?.close();
+    }
 }
 /** Resolve a process gate against the shared snapshot reader, when configured. */
 export function resolveProcessFlagGate(flagKey, lookup, legacyFallback) {

package/dist/lib/flag-snapshot-file.d.ts

@@ -0,0 +1,20 @@
+/** Private, synchronous, offline snapshot used by the native CLI fast route. */
+export declare const FLAG_SNAPSHOT_MAX_AGE_MS: number;
+export interface PersistedFlagSnapshot {
+    company_uid: string;
+    fetched_at: string;
+    flags: Record<string, boolean>;
+}
+export declare function flagSnapshotPath(companyUid: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** Write just the validated flag decisions and company scope, never auth data. */
+export declare function writeFlagSnapshotFile(companyUid: string, flags: Readonly<Record<string, unknown>>, options?: {
+    env?: NodeJS.ProcessEnv;
+    fetchedAt?: string;
+}): string;
+/** Return null for every miss, malformed file, company mismatch, or stale file. */
+export declare function readFlagSnapshotFile(companyUid: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    now?: number;
+    maxAgeMs?: number;
+}): PersistedFlagSnapshot | null;
+//# sourceMappingURL=flag-snapshot-file.d.ts.map