@indigoai-us/hq-cli 5.274.1 → 5.276.0

package/dist/lib/daemon/supervisor.js

@@ -13,7 +13,11 @@
  * - restart/trigger/stop requests from the CLI are polled and applied; a
  *   request for a unit that is not planned yet re-reads the plan first;
  * - stop() sends SIGTERM to every child, escalates to SIGKILL after
- *   STOP_ESCALATION_MS, and resolves once every child has exited.
+ *   STOP_ESCALATION_MS, and resolves once every child has exited;
+ * - release() instead leaves every child running and reports the long-running
+ *   ones, so the next daemon can adopt them (`adopt`). Adopted units whose
+ *   command is unchanged keep running; changed ones are replaced one at a
+ *   time, draining first when the unit has a drain signal.
  *
  * Processes, time, and state output are injected; `run.ts` wires the real ones.
  */
@@ -21,11 +25,24 @@ export const BACKOFF_BASE_MS = 1_000;
 export const BACKOFF_MAX_MS = 60_000;
 export const HEALTHY_RUN_MS = 60_000;
 export const STOP_ESCALATION_MS = 10_000;
+/** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
+export const HANDOFF_STAGGER_MS = 15_000;
+/** How long a draining unit may take to finish its work before it gets SIGTERM. */
+export const HANDOFF_DRAIN_MAX_MS = 15 * 60_000;
 export function backoffMs(attempt) {
     return Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** Math.max(0, attempt));
 }
-function planKey(plan) {
-    return JSON.stringify([plan.kind, plan.restart, plan.intervalSec, plan.initialDelaySec, plan.command, plan.env]);
+/**
+ * What a unit's process was started from; a unit whose key changes is
+ * restarted. The CLI version counts only for `hq` commands, so a CLI update
+ * leaves hq-cloud runners, other programs, and units marked
+ * `keepAcrossCliUpdates` running.
+ */
+export function planKey(plan, cliVersion) {
+    const fields = [plan.kind, plan.restart, plan.intervalSec, plan.initialDelaySec, plan.command, plan.env];
+    if (cliVersion !== undefined && plan.command?.type === "hq" && !plan.keepAcrossCliUpdates)
+        fields.push(cliVersion);
+    return JSON.stringify(fields);
 }
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
@@ -42,6 +59,10 @@ export function createSupervisor(deps) {
     let started = false;
     let reconcileTimer;
     let requestTimer;
+    /** Adopted units whose command changed, replaced one at a time. */
+    const handoffQueue = [];
+    let handoffActive = false;
+    let handoffTimer;
     /** Every child process not yet known to have exited, including ones the slots have let go of. */
     const live = new Set();
     let drained = null;
@@ -75,8 +96,20 @@ export function createSupervisor(deps) {
         delete slot.state.pid;
         delete slot.state.nextRunAt;
     };
-    /** Stop the slot's child (if any), then run `then` once it has exited. */
-    const terminate = (slot, then) => {
+    const signalChild = (slot, child, signal) => {
+        try {
+            child.kill(signal);
+        }
+        catch (err) {
+            deps.log("error", `could not send ${signal} to ${slot.plan.id}: ${errorMessage(err)}`);
+        }
+    };
+    /**
+     * Stop the slot's child (if any), then run `then` once it has exited. With
+     * `drain`, a unit that has a drain signal gets it first and SIGTERM only
+     * after HANDOFF_DRAIN_MAX_MS; SIGKILL follows SIGTERM after STOP_ESCALATION_MS.
+     */
+    const terminate = (slot, then, drain = false) => {
         clearTimer(slot);
         const child = slot.child;
         if (!child) {
@@ -85,24 +118,32 @@ export function createSupervisor(deps) {
         }
         slot.expectingExit = true;
         slot.afterExit = then;
-        slot.killTimer = setT(() => {
-            slot.killTimer = undefined;
-            if (slot.child === child) {
+        if (slot.killTimer !== undefined)
+            clearT(slot.killTimer);
+        const escalateToKill = () => {
+            slot.killTimer = setT(() => {
+                slot.killTimer = undefined;
+                if (slot.child !== child)
+                    return;
                 deps.log("warn", `${slot.plan.id} ignored SIGTERM; sending SIGKILL`);
-                try {
-                    child.kill("SIGKILL");
-                }
-                catch (err) {
-                    deps.log("error", `could not SIGKILL ${slot.plan.id}: ${errorMessage(err)}`);
-                }
-            }
-        }, STOP_ESCALATION_MS);
-        try {
-            child.kill("SIGTERM");
-        }
-        catch (err) {
-            deps.log("error", `could not stop ${slot.plan.id}: ${errorMessage(err)}`);
+                signalChild(slot, child, "SIGKILL");
+            }, STOP_ESCALATION_MS);
+        };
+        const drainSignal = drain ? slot.plan.drainSignal : undefined;
+        if (drainSignal) {
+            slot.killTimer = setT(() => {
+                slot.killTimer = undefined;
+                if (slot.child !== child)
+                    return;
+                deps.log("warn", `${slot.plan.id} did not finish draining; sending SIGTERM`);
+                escalateToKill();
+                signalChild(slot, child, "SIGTERM");
+            }, HANDOFF_DRAIN_MAX_MS);
+            signalChild(slot, child, drainSignal);
+            return;
         }
+        escalateToKill();
+        signalChild(slot, child, "SIGTERM");
     };
     const scheduleRestart = (slot) => {
         if (stopped)
@@ -198,6 +239,7 @@ export function createSupervisor(deps) {
             return;
         }
         slot.child = child;
+        slot.childKey = slot.key;
         slot.childStartedAt = now();
         slot.state.status = "running";
         slot.state.startedAt = slot.childStartedAt;
@@ -263,6 +305,7 @@ export function createSupervisor(deps) {
             return;
         }
         slot.child = child;
+        slot.childKey = slot.key;
         slot.childStartedAt = now();
         slot.state.status = "running";
         delete slot.state.reason;
@@ -290,7 +333,7 @@ export function createSupervisor(deps) {
     };
     const newSlot = (plan) => ({
         plan,
-        key: planKey(plan),
+        key: planKey(plan, deps.cliVersion),
         attempts: 0,
         expectingExit: false,
         busy: false,
@@ -334,7 +377,9 @@ export function createSupervisor(deps) {
                 continue;
             }
             next.set(plan.id, existing);
-            const key = planKey(plan);
+            const adopted = existing.adopted === true;
+            existing.adopted = false;
+            const key = planKey(plan, deps.cliVersion);
             const wasBlocked = existing.plan.blocked !== undefined;
             const changed = key !== existing.key;
             existing.plan = plan;
@@ -358,6 +403,10 @@ export function createSupervisor(deps) {
                 else
                     activate(existing);
             }
+            else if (changed && adopted && existing.child) {
+                deps.log("info", `will replace ${plan.id}: it runs an older CLI or command`);
+                handoffQueue.push(existing);
+            }
             else if (changed) {
                 deps.log("info", `restarting ${plan.id}: its command changed`);
                 existing.attempts = 0;
@@ -367,6 +416,93 @@ export function createSupervisor(deps) {
         }
         slots = next;
         emit();
+        pumpHandoff();
+    };
+    /** Replace the next queued adopted unit once the previous replacement has settled. */
+    const pumpHandoff = () => {
+        if (stopped || handoffActive)
+            return;
+        let slot;
+        while ((slot = handoffQueue.shift())) {
+            // Skip units that left the plan, were paused, or already restarted on their own.
+            if (slots.get(slot.plan.id) === slot && !slot.plan.blocked && slot.child && slot.childKey !== slot.key)
+                break;
+        }
+        if (!slot)
+            return;
+        const target = slot;
+        handoffActive = true;
+        deps.log("info", `replacing ${target.plan.id}${target.plan.drainSignal ? " once it finishes its current work" : ""}`);
+        target.attempts = 0;
+        target.state.restarts = 0;
+        terminate(target, () => activate(target), true);
+        const settle = (delay) => {
+            handoffTimer = setT(() => {
+                handoffTimer = undefined;
+                if (stopped)
+                    return;
+                const gone = slots.get(target.plan.id) !== target || target.plan.blocked !== undefined;
+                if (!gone && target.expectingExit)
+                    return settle(HANDOFF_STAGGER_MS);
+                if (!gone && target.child) {
+                    const ranFor = now() - (target.childStartedAt ?? now());
+                    if (ranFor < HANDOFF_STAGGER_MS)
+                        return settle(HANDOFF_STAGGER_MS - ranFor);
+                }
+                else if (!gone && target.state.status === "backoff") {
+                    return settle(HANDOFF_STAGGER_MS);
+                }
+                handoffActive = false;
+                pumpHandoff();
+            }, delay);
+        };
+        settle(HANDOFF_STAGGER_MS);
+    };
+    /** Stop a process the plan has no place for. */
+    const stopStray = (id, child) => {
+        const slot = newSlot({ id, service: id, description: id, kind: "long-running", restart: "always", command: null, env: {} });
+        slot.child = child;
+        watch(slot, child);
+        terminate(slot);
+    };
+    /** Take over the previous daemon's services before the first plan read starts anything. */
+    const adoptPrevious = () => {
+        const adopt = deps.adopt ?? [];
+        if (adopt.length === 0)
+            return;
+        let plans = [];
+        try {
+            const result = deps.plan();
+            if (!Array.isArray(result))
+                throw new Error("plan did not return a list of units");
+            plans = result;
+        }
+        catch (err) {
+            deps.log("error", `could not plan units; stopping the services left by the previous daemon: ${errorMessage(err)}`);
+        }
+        const byId = new Map(plans.map((p) => [p.id, p]));
+        for (const unit of adopt) {
+            const plan = byId.get(unit.id);
+            if (!plan || plan.kind !== "long-running" || slots.has(unit.id)) {
+                deps.log("info", `stopping ${unit.id} left by the previous daemon: no longer planned as a service`);
+                stopStray(unit.id, unit.child);
+                continue;
+            }
+            // Recorded as runnable, so the first plan read pauses it when it is now blocked.
+            const slot = newSlot({ ...plan, blocked: undefined });
+            slot.key = unit.key;
+            slot.adopted = true;
+            slot.child = unit.child;
+            slot.childKey = unit.key;
+            slot.childStartedAt = now();
+            slot.state.status = "running";
+            slot.state.startedAt = slot.childStartedAt;
+            if (unit.child.pid !== undefined)
+                slot.state.pid = unit.child.pid;
+            watch(slot, unit.child);
+            slots.set(unit.id, slot);
+            deps.log("info", `adopted ${unit.id} (pid ${unit.child.pid ?? "?"}) from the previous daemon`);
+        }
     };
     const handleRequest = (req) => {
         if (req.action === "restart-daemon") {
@@ -461,6 +597,7 @@ export function createSupervisor(deps) {
             if (started)
                 return;
             started = true;
+            adoptPrevious();
             reconcile();
             reconcileTimer = setT(reconcileLoop, reconcileMs);
             requestTimer = setT(pollRequests, requestPollMs);
@@ -473,6 +610,8 @@ export function createSupervisor(deps) {
                 clearT(reconcileTimer);
             if (requestTimer !== undefined)
                 clearT(requestTimer);
+            if (handoffTimer !== undefined)
+                clearT(handoffTimer);
             for (const slot of slots.values()) {
                 clearTimer(slot);
                 slot.child = undefined;
@@ -519,6 +658,34 @@ export function createSupervisor(deps) {
         },
         reconcile,
         state: snapshot,
+        release() {
+            const released = [];
+            for (const slot of slots.values()) {
+                const pid = slot.child?.pid;
+                if (slot.plan.kind === "long-running" && pid !== undefined && slot.childKey !== undefined) {
+                    released.push({ id: slot.plan.id, pid, key: slot.childKey });
+                }
+            }
+            stopped = true;
+            if (reconcileTimer !== undefined)
+                clearT(reconcileTimer);
+            if (requestTimer !== undefined)
+                clearT(requestTimer);
+            if (handoffTimer !== undefined)
+                clearT(handoffTimer);
+            for (const slot of slots.values()) {
+                clearTimer(slot);
+                if (slot.killTimer !== undefined)
+                    clearT(slot.killTimer);
+                slot.killTimer = undefined;
+                slot.child = undefined;
+                slot.state.status = "stopped";
+                delete slot.state.pid;
+                delete slot.state.nextRunAt;
+            }
+            emit();
+            return released;
+        },
     };
 }
 //# sourceMappingURL=supervisor.js.map

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

package/dist/lib/flag-snapshot-file.js

@@ -0,0 +1,91 @@
+/** Private, synchronous, offline snapshot used by the native CLI fast route. */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const FLAG_SNAPSHOT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+export function flagSnapshotPath(companyUid, env = process.env) {
+    if (!COMPANY_UID_RE.test(companyUid))
+        return undefined;
+    const cacheHome = env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), ".cache");
+    return path.join(cacheHome, "hq", "flags", `snapshot-${companyUid}.json`);
+}
+/** Write just the validated flag decisions and company scope, never auth data. */
+export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
+    const file = flagSnapshotPath(companyUid, options.env);
+    if (!file)
+        throw new Error("Cannot persist a flag snapshot without a valid company uid");
+    const normalizedFlags = Object.fromEntries(Object.entries(flags).filter((entry) => Boolean(entry[0].trim()) && typeof entry[1] === "boolean"));
+    const snapshot = {
+        company_uid: companyUid,
+        fetched_at: options.fetchedAt ?? new Date().toISOString(),
+        flags: normalizedFlags,
+    };
+    if (!Number.isFinite(Date.parse(snapshot.fetched_at))) {
+        throw new Error("Cannot persist a flag snapshot with an invalid fetched_at timestamp");
+    }
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    fs.chmodSync(directory, 0o700);
+    const temporary = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    let fd;
+    try {
+        fd = fs.openSync(temporary, "wx", 0o600);
+        fs.writeFileSync(fd, `${JSON.stringify(snapshot)}\n`, "utf8");
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    catch (error) {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch (cleanupError) {
+            if (cleanupError.code !== "ENOENT")
+                throw cleanupError;
+        }
+        throw error;
+    }
+    return file;
+}
+/** Return null for every miss, malformed file, company mismatch, or stale file. */
+export function readFlagSnapshotFile(companyUid, options = {}) {
+    const file = flagSnapshotPath(companyUid, options.env);
+    if (!file)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const value = parsed;
+    if (Object.keys(value).sort().join(",") !== "company_uid,fetched_at,flags" ||
+        value.company_uid !== companyUid ||
+        typeof value.fetched_at !== "string" ||
+        !value.flags || typeof value.flags !== "object" || Array.isArray(value.flags))
+        return null; // Expected on missing, malformed, unreadable, or cross-company cache data.
+    const fetchedAt = Date.parse(value.fetched_at);
+    const age = (options.now ?? Date.now()) - fetchedAt;
+    if (!Number.isFinite(fetchedAt) || age < 0 || age > (options.maxAgeMs ?? FLAG_SNAPSHOT_MAX_AGE_MS)) {
+        return null;
+    }
+    const flags = value.flags;
+    for (const enabled of Object.values(flags)) {
+        if (typeof enabled !== "boolean")
+            return null;
+    }
+    return {
+        company_uid: companyUid,
+        fetched_at: value.fetched_at,
+        flags: flags,
+    };
+}
+//# sourceMappingURL=flag-snapshot-file.js.map

package/dist/lib/lanes/host-capacity.js

@@ -10,7 +10,13 @@ function admissionHost(host) {
 /** Snapshot the same per-host running-slot predicate used by lane admission. */
 export function buildHostCapacitySnapshot(input) {
     const at = input.now.getTime();
-    const onHost = input.lanes.filter((lane) => laneRunsOnHost(lane, admissionHost(input.host)));
+    const localHostname = input.hostname?.trim();
+    const onHost = input.lanes.filter((lane) => laneRunsOnHost(lane, admissionHost(input.host)) ||
+        (input.host.kind === "outpost" &&
+            localHostname !== undefined &&
+            localHostname !== "" &&
+            lane.host.kind === "local" &&
+            lane.host.id === localHostname));
     const providers = {};
     for (const provider of ["claude", "codex", "grok"]) {
         const providerConfig = input.config.providers[provider];