@indigoai-us/hq-cli 5.275.0 → 5.277.0

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/claude-balance.d.ts

@@ -3,6 +3,7 @@ import type { HostCapacityAccount, HostCapacitySnapshot } from "./host-capacity.
 import type { LaneHost, LaneRecord, LanesConfig } from "./types.js";
 export declare const BALANCE_LIVE_STATES: readonly ["running", "queued", "awaiting_input"];
 export declare const BALANCE_MOVABLE_STATES: readonly ["interrupted", "done", "awaiting_input"];
+export declare const CLAUDE_RECENT_USAGE_WINDOW_MS: number;
 export interface BalanceHostSnapshot {
     capacity: HostCapacitySnapshot;
     lanes: readonly LaneRecord[];
@@ -39,11 +40,12 @@ export interface ClaudeAccountLoad {
     live_lanes: number;
     counts_complete: boolean;
     usage: NonNullable<HostCapacityAccount["usage"]> | null;
+    recent_usage_at: string | null;
     hosts: AccountHostLoad[];
 }
 export interface ClaudeAccountSelection {
     account: string;
-    signal: "usage" | "lane_count" | "explicit";
+    signal: "usage" | "recent_usage" | "lane_count" | "explicit";
     reason: "least_loaded" | "explicit";
     target_host: LaneHost;
     considered: ClaudeAccountLoad[];
@@ -72,6 +74,9 @@ export declare function selectClaudeAccount(input: {
     model?: string;
     /** Keep the recorded account eligible for its already-running CLI model. */
     recordedModelAccount?: string;
+    /** Recent completed-run tiebreak; callers pass the default-off hq-flags result. */
+    recentUsageEnabled?: boolean;
+    now?: Date;
     explicitAccount?: string;
     unavailableHosts?: readonly BalanceHostGap[];
 }): ClaudeAccountSelection;

package/dist/lib/lanes/claude-balance.js

@@ -1,6 +1,7 @@
 import { LanesError } from "./errors.js";
 export const BALANCE_LIVE_STATES = ["running", "queued", "awaiting_input"];
 export const BALANCE_MOVABLE_STATES = ["interrupted", "done", "awaiting_input"];
+export const CLAUDE_RECENT_USAGE_WINDOW_MS = 5 * 60 * 60 * 1000;
 function sameHost(a, b) {
     return a.kind === b.kind && a.id === b.id;
 }
@@ -74,10 +75,31 @@ function usageScore(usage) {
         return null;
     return Math.max(usage.five_hour_percent, usage.weekly_percent);
 }
-function selectionSignal(loads) {
-    return loads.length > 0 && loads.every((load) => usageScore(load.usage) !== null)
-        ? "usage"
-        : "lane_count";
+function recentUsageAt(hosts, account, now) {
+    if (hosts.some((host) => !host.laneListAvailable))
+        return null;
+    const nowMs = now.getTime();
+    const cutoff = nowMs - CLAUDE_RECENT_USAGE_WINDOW_MS;
+    let latestAt = null;
+    let latestMs = cutoff - 1;
+    for (const host of hosts) {
+        for (const lane of host.lanes) {
+            if (lane.provider !== "claude" || lane.account !== account ||
+                lane.last_run_usage === undefined || lane.last_run_usage_at === undefined)
+                continue;
+            const atMs = Date.parse(lane.last_run_usage_at);
+            if (!Number.isFinite(atMs) || atMs < cutoff || atMs > nowMs || atMs <= latestMs)
+                continue;
+            latestMs = atMs;
+            latestAt = lane.last_run_usage_at;
+        }
+    }
+    return latestAt;
+}
+function selectionSignal(loads, recentUsageEnabled, laneSnapshotsComplete) {
+    if (loads.length > 0 && loads.every((load) => usageScore(load.usage) !== null))
+        return "usage";
+    return recentUsageEnabled && laneSnapshotsComplete ? "recent_usage" : "lane_count";
 }
 function targetIneligibilityReason(accountId, globalEnabled, allowedAccounts, target) {
     if (!globalEnabled)
@@ -120,6 +142,7 @@ function buildLoads(input) {
             live_lanes: knownCounts.reduce((sum, count) => sum + count, 0),
             counts_complete: hosts.every((host) => host.live_lanes !== null && host.count_source !== "capacity_partial"),
             usage: input.target.capacity.providers.claude.accounts[account]?.usage ?? null,
+            recent_usage_at: recentUsageAt(input.hosts, account, input.now),
             hosts,
         };
     });
@@ -133,7 +156,8 @@ export function selectClaudeAccount(input) {
             unavailable_hosts: input.unavailableHosts ?? [],
         });
     }
-    const { loads, skipped } = buildLoads({ ...input, target });
+    const now = input.now ?? new Date();
+    const { loads, skipped } = buildLoads({ ...input, target, now });
     if (input.explicitAccount !== undefined) {
         const selected = loads.find((load) => load.account === input.explicitAccount);
         if (!selected || !selected.eligible) {
@@ -173,14 +197,28 @@ export function selectClaudeAccount(input) {
             unavailable_hosts: input.unavailableHosts ?? [],
         });
     }
-    const signal = selectionSignal(eligible);
+    const signal = selectionSignal(eligible, input.recentUsageEnabled === true, input.hosts.every((host) => host.laneListAvailable) && (input.unavailableHosts?.length ?? 0) === 0);
     eligible.sort((a, b) => {
         if (signal === "usage") {
             const byUsage = usageScore(a.usage) - usageScore(b.usage);
             if (byUsage !== 0)
                 return byUsage;
         }
-        return a.live_lanes - b.live_lanes || a.account.localeCompare(b.account);
+        const byLiveLanes = a.live_lanes - b.live_lanes;
+        if (byLiveLanes !== 0)
+            return byLiveLanes;
+        if (signal === "recent_usage") {
+            if (a.recent_usage_at === null && b.recent_usage_at !== null)
+                return -1;
+            if (a.recent_usage_at !== null && b.recent_usage_at === null)
+                return 1;
+            if (a.recent_usage_at !== null && b.recent_usage_at !== null) {
+                const byRecentUsage = Date.parse(a.recent_usage_at) - Date.parse(b.recent_usage_at);
+                if (byRecentUsage !== 0)
+                    return byRecentUsage;
+            }
+        }
+        return a.account.localeCompare(b.account);
     });
     return {
         account: eligible[0].account,
@@ -196,7 +234,7 @@ export function accountLoadsForReport(input) {
     const first = input.hosts[0];
     if (!first)
         return [];
-    return buildLoads({ hosts: input.hosts, target: first, config: input.config }).loads.map((load) => ({
+    return buildLoads({ hosts: input.hosts, target: first, config: input.config, now: new Date() }).loads.map((load) => ({
         ...load,
         eligible: false,
         ineligible_reason: undefined,

package/dist/lib/lanes/config.js

@@ -252,6 +252,21 @@ function parsePreferredAccounts(provider, value, accounts) {
     return [...preferred];
 }
 export function assertUniqueAccountHomes(provider, accounts) {
+    // An override must not let one account reuse another account's shared default home.
+    const declaredHomes = new Map();
+    for (const [id, account] of Object.entries(accounts)) {
+        const homes = new Set([
+            account.home,
+            ...Object.values(account.hosts ?? {}).map(({ home }) => home),
+        ]);
+        for (const home of homes) {
+            const prior = declaredHomes.get(home);
+            if (prior !== undefined && prior !== id) {
+                throw new LanesConfigError("duplicate_account_home", `providers.${provider} accounts ${JSON.stringify(prior)} and ${JSON.stringify(id)} declare the same home ${home}`, { provider, accounts: [prior, id], home });
+            }
+            declaredHomes.set(home, id);
+        }
+    }
     const hostnames = new Set(Object.values(accounts).flatMap((account) => Object.keys(account.hosts ?? {})));
     const check = (hostname) => {
         const seen = new Map();

package/dist/lib/lanes/hire-grant-dispatch.d.ts

@@ -18,6 +18,8 @@ export interface OutpostHireGrantContext {
     superseded_message_caller_id?: string;
     superseded_message_session_id?: string;
 }
+/** Select the owner records needed to reproduce the primary's grant hierarchy. */
+export declare function selectOutpostHireGrantHierarchy(targetLaneId: string, lanes: readonly LaneRecord[]): LaneRecord[];
 /** Encode only the owner-relevant hierarchy from the primary's complete store. */
 export declare function createOutpostHireGrantContext(target: LaneRecord, lanes: readonly LaneRecord[], supersededMessageCallerId?: string, supersededMessageSessionId?: string): string;
 /** Decode and validate an owner grant context, binding it to the target lane. */

package/dist/lib/lanes/hire-grant-dispatch.js

@@ -15,6 +15,47 @@ function copySenior(senior) {
         ? { kind: senior.kind }
         : { kind: senior.kind, id: senior.id };
 }
+// Terminal relatives are included so the owner's final state overwrites a stale
+// primary copy; the context builder counts only alive children afterwards.
+function directChildren(lanes, parentLaneId) {
+    return lanes.filter((lane) => lane.senior.kind === "lane" && lane.senior.id === parentLaneId);
+}
+/** Select the owner records needed to reproduce the primary's grant hierarchy. */
+export function selectOutpostHireGrantHierarchy(targetLaneId, lanes) {
+    const current = lanes.find((lane) => lane.lane_id === targetLaneId);
+    if (!current)
+        return [];
+    const relevant = new Set([current.lane_id]);
+    if (current.senior.kind === "lane" && current.senior.id) {
+        relevant.add(current.senior.id);
+        for (const sibling of directChildren(lanes, current.senior.id)) {
+            relevant.add(sibling.lane_id);
+        }
+    }
+    for (const child of directChildren(lanes, current.lane_id)) {
+        relevant.add(child.lane_id);
+    }
+    const companyUid = current.company?.uid;
+    const projectId = current.project_id;
+    if (companyUid && projectId) {
+        // A superseded-message caller must be checked against the same project and
+        // company rows that the complete hierarchy builder sees.
+        for (const candidate of lanes) {
+            if (candidate.company?.uid === companyUid && candidate.project_id === projectId) {
+                relevant.add(candidate.lane_id);
+            }
+        }
+    }
+    if (current.senior.kind === "session" && companyUid) {
+        for (const candidate of lanes) {
+            if (candidate.company?.uid === companyUid && ((current.worker_profile !== undefined && candidate.worker_profile === current.worker_profile) ||
+                (projectId !== undefined && candidate.project_id === projectId && (candidate.hire_grant ?? 0) > 0))) {
+                relevant.add(candidate.lane_id);
+            }
+        }
+    }
+    return lanes.filter((lane) => relevant.has(lane.lane_id));
+}
 function snapshot(lane) {
     return {
         lane_id: lane.lane_id,

package/dist/lib/lanes/index.d.ts

@@ -10,7 +10,7 @@ export type { AdmissionCapReason, AdmissionHost } from "./admission.js";
 export { buildHostCapacitySnapshot, chooseHostForLane, parseHostCapacitySnapshot, } from "./host-capacity.js";
 export type { HostCapacityAccount, HostCapacityProvider, HostCapacitySnapshot, HostPlacementChoice, } from "./host-capacity.js";
 export { CONFIG_SCHEMA_VERSION, ENVELOPE_DECISIONS, ENVELOPE_SCHEMA_VERSION, HISTORY_CAP, HOST_KINDS, LANE_PROVIDERS, LANE_SCHEMA_VERSION, LANE_STORY_STATUSES, LANE_STATES, LIVENESS_STATES, QUESTION_BODY_STORES, QUESTION_SCHEMA_VERSION, QUESTION_STATUSES, QUEUED_REASONS, RAISED_VIA, ROUTING_REASONS, SENIOR_KINDS, STORY_STATUSES, TERMINAL_LANE_STATES, isEnvelopeDecision, isHostKind, isLaneProvider, isLaneState, isLivenessState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseLaneEnvelope, parseLaneProvider, parseLaneState, parseLivenessState, parseMajorSchema, parseQuestionStatus, parseSeniorKind, } from "./types.js";
-export type { AccountConfig, AttributionHistoryEntry, EnvelopeDecision, EnvelopeQuestion, HostKind, LaneCompanyRef, LaneAccountSelection, LaneAccountSelectionConsidered, LaneAccountSelectionHostCount, LaneEnvelope, LaneHost, LaneProvider, LanePlacementPolicy, LaneRecord, LaneStory, LaneStoryStatus, PendingResume, AccountHistoryEntry, LaneState, LanesConfig, LastEnvelopeRef, LivenessState, LivenessWindows, ProviderConfig, QuestionAnswer, QuestionBodyRef, QuestionRecord, QuestionStatus, QueuedReason, RaisedVia, RoutingHistoryEntry, RoutingReason, SeniorHistoryEntry, SeniorKind, SeniorRef, WorkerProfileRepinHistoryEntry, StoryStatus, TerminalLaneState, ThrottleConfig, } from "./types.js";
+export type { AccountConfig, AttributionHistoryEntry, EnvelopeDecision, EnvelopeQuestion, HostKind, LaneCompanyRef, LaneAccountSelection, LaneAccountSelectionConsidered, LaneAccountSelectionHostCount, LaneEnvelope, LaneHost, LaneProvider, LanePlacementPolicy, LaneRecord, LaneStory, LaneStoryStatus, PendingResume, AccountHistoryEntry, LaneState, LanesConfig, LastEnvelopeRef, LivenessState, LivenessWindows, ProviderConfig, QuestionAnswer, QuestionBodyRef, QuestionRecord, QuestionStatus, QueuedReason, RaisedVia, RoutingHistoryEntry, RoutingReason, SeniorHistoryEntry, SeniorKind, SeniorRef, WorkerProfileRepinHistoryEntry, LaneSettingsHistoryEntry, StoryStatus, TerminalLaneState, ThrottleConfig, } from "./types.js";
 export { ACTIVE_LANE_STORY_STATUSES, activeLaneStories, laneStories, laneStory, storyKey, storyStatusForEnvelope, storyWarning, withCurrentStory, withLaneStories, } from "./stories.js";
 export { DEFAULT_ACCOUNT_HOMES, DEFAULT_AUTO_COMPACT_TOKENS, DEFAULT_COMPACT_AFTER_MS, DEFAULT_CPU_BUSY_PAUSE, DEFAULT_CPU_BUSY_RESUME, DEFAULT_LIVE_WITHIN_MS, DEFAULT_LIVENESS_WINDOWS, DEFAULT_MAX_QUEUED, DEFAULT_MIN_AVAILABLE_MEM_MB, DEFAULT_PROVIDER_MAX_RUNNING, DEFAULT_SILENT_LOST_MS, DEFAULT_TURN_START_LOST_MS, LANES_CONFIG_REL, accountMaxRunning, canonicalizeHome, documentedDefaultConfig, expandHome, lanesConfigPath, loadLanesConfig, parseLanesConfig, providerCompactAfterMs, providerAutoCompactTokens, providerQuotaDefaultHoldMs, DEFAULT_QUOTA_HOLD_MS, writeLanesConfig, } from "./config.js";
 export type { ConfigLoadDeps, ConfigWriteDeps } from "./config.js";

package/dist/lib/lanes/keep-alive.d.ts

@@ -4,6 +4,9 @@ export declare const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
 /** Missing or unreadable registry values retain the legacy supersession behavior. */
 export declare const LANE_SUPERSESSION_LINEAGE_AWARE_FLAG = "lanes.supersession-lineage-aware";
 export declare const LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED = false;
+/** Missing or unreadable registry values keep rejecting superseded messages. */
+export declare const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_FLAG = "lanes.running-superseded-message-delivery";
+export declare const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_DEFAULT_ENABLED = false;
 export declare const LEAD_LANE_KEEP_ALIVE_MAX_RESUMES = 24;
 export declare const LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS: number;
 export declare const LEAD_LANE_KEEP_ALIVE_MAX_BACKOFF_MS: number;

package/dist/lib/lanes/keep-alive.js

@@ -8,6 +8,9 @@ export const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
 /** Missing or unreadable registry values retain the legacy supersession behavior. */
 export const LANE_SUPERSESSION_LINEAGE_AWARE_FLAG = "lanes.supersession-lineage-aware";
 export const LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED = false;
+/** Missing or unreadable registry values keep rejecting superseded messages. */
+export const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_FLAG = "lanes.running-superseded-message-delivery";
+export const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_DEFAULT_ENABLED = false;
 export const LEAD_LANE_KEEP_ALIVE_MAX_RESUMES = 24;
 export const LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS = 5 * 60 * 1000;
 export const LEAD_LANE_KEEP_ALIVE_MAX_BACKOFF_MS = 60 * 60 * 1000;

package/dist/lib/lanes/outpost-dispatch.d.ts

@@ -82,6 +82,10 @@ export declare function buildOutpostCapacityCommand(): string;
 /** Read lane records owned by an Outpost, using its configured HQ binary when set. */
 export declare function buildOutpostLaneListCommand(input?: {
     hqBinary?: string;
+    laneIds?: readonly string[];
+    active?: boolean;
+    hierarchy?: string;
+    snapshot?: boolean;
 }): string;
 /** Read questions on one Outpost, scoped to a company when supplied. */
 export declare function buildOutpostQuestionListCommand(input?: {

package/dist/lib/lanes/outpost-dispatch.js

@@ -67,12 +67,21 @@ export function buildOutpostCapacityCommand() {
 }
 /** Read lane records owned by an Outpost, using its configured HQ binary when set. */
 export function buildOutpostLaneListCommand(input = {}) {
-    return withRemoteHqDir(joinCommandParts([
+    const args = [
         input.hqBinary?.trim() || "hq",
         "lanes",
         "list",
         "--json",
-    ]));
+    ];
+    for (const laneId of input.laneIds ?? [])
+        args.push("--lane", laneId);
+    if (input.active)
+        args.push("--active");
+    if (input.hierarchy !== undefined)
+        args.push("--hierarchy", input.hierarchy);
+    if (input.snapshot)
+        args.push("--snapshot");
+    return withRemoteHqDir(joinCommandParts(args));
 }
 /** Read questions on one Outpost, scoped to a company when supplied. */
 export function buildOutpostQuestionListCommand(input = {}) {