@indigoai-us/hq-cli 5.185.0 → 5.185.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [5.185.1] — 2026-09-25
+
+### Fixed
+
+- `lanes.hire-grants` resolves its company-scoped hq-flags value before gating.
+  A valid local override wins; missing rows or failed reads leave enforcement
+  off. Backfills check the unscoped value and each target company's value
+  before writing. `hire_grant_exhausted` names the grantor and includes the
+  same recovery message in JSON and on stderr.
+
 ## [5.185.0] — 2026-09-25
 
 ### Fixed

package/dist/commands/lanes.d.ts

@@ -79,7 +79,7 @@ export interface LanesCommandDeps {
     /** Test seam for the default-off outpost placement rollout flag. */
     lanePlacementEnabled?: () => boolean;
     /** Test seam for the default-off lane hire-grants rollout gate. */
-    laneHireGrantsEnabled?: () => boolean;
+    laneHireGrantsEnabled?: (company?: LaneCompanyRef | null) => boolean | Promise<boolean>;
 }
 export declare const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
 export declare function parseSeniorRef(raw: string): SeniorRef;

package/dist/commands/lanes.js

@@ -13,6 +13,7 @@ import * as path from "node:path";
 import { registerOutpostPrunerCommand } from "./outpost-pruner.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
+import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
 import { OUTPOST_DIR, OUTPOST_ID_PATH, readOutpostIdentity, resolveAdmissionHost, } from "../lib/lanes/admission-host.js";
 export { OUTPOST_DIR, OUTPOST_ID_PATH, readOutpostIdentity } from "../lib/lanes/admission-host.js";
@@ -52,8 +53,8 @@ export const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
 function defaultLanePlacementEnabled() {
     return resolveProcessFlagGate(LANE_OUTPOST_LOAD_BALANCING_FLAG, { fallback: false }, () => false);
 }
-function defaultLaneHireGrantsEnabled() {
-    return resolveProcessFlagGate(LANE_HIRE_GRANTS_FLAG, { fallback: false }, () => false);
+function defaultLaneHireGrantsEnabled(company) {
+    return readLanesRegistryFlag(LANE_HIRE_GRANTS_FLAG, { company });
 }
 function withoutProviderHome(value) {
     if (Array.isArray(value))
@@ -73,6 +74,9 @@ function printJson(value) {
 }
 function failJson(err) {
     if (isLanesError(err)) {
+        if (err.error === "hire_grant_exhausted") {
+            process.stderr.write(`hq lanes: ${err.message}\n`);
+        }
         printJson(err.toJSON());
         process.exit(1);
     }
@@ -515,12 +519,14 @@ const OUTPOST_HIRE_SUMMARY_WAIT_MS = 15_000;
 const OUTPOST_HIRE_SUMMARY_CONCURRENCY = 4;
 async function laneHirePresentation(ctx, lane, lanes) {
     const local = laneHireFields(lane, lanes);
-    if (!ctx.laneHireGrantsEnabled() ||
-        lane.host.kind !== "outpost" ||
+    if (lane.host.kind !== "outpost" ||
         isTerminalLaneState(lane.state) ||
         laneRunsHere(lane, reconcileHostFromCtx(ctx))) {
         return { ...local, hire_source: "local" };
     }
+    if (!await ctx.laneHireGrantsEnabled(lane.company)) {
+        return { ...local, hire_source: "local" };
+    }
     try {
         return { ...(await ownerLaneHireFields(ctx, lane)), hire_source: "owner" };
     }
@@ -548,14 +554,15 @@ async function mapWithConcurrency(values, concurrency, map) {
     await Promise.all(workers);
     return results;
 }
-function withResumeHireAdmission(ctx, lane, fn) {
+async function withResumeHireAdmission(ctx, lane, fn) {
     const hqRoot = ctx.hqRoot();
-    if (!ctx.laneHireGrantsEnabled() ||
-        !isTerminalLaneState(lane.state) ||
+    if (!isTerminalLaneState(lane.state) ||
         lane.senior.kind !== "lane" ||
         !lane.senior.id) {
         return fn();
     }
+    if (!await ctx.laneHireGrantsEnabled(lane.company))
+        return fn();
     return withHireGrantAdmission(hqRoot, lane.senior.id, ({ parent, children, parentGrant, availableChildGrant }) => {
         const current = readLane(hqRoot, lane.lane_id);
         // A different resume already reactivated this lane; it occupies the slot
@@ -588,11 +595,33 @@ function withResumeHireAdmission(ctx, lane, fn) {
 }
 function hireGrantCapacityError(parent, children) {
     const grant = parent.hire_grant ?? 0;
-    return new LanesError("hire_grant_exhausted", `Senior lane ${parent.lane_id} has hire grant ${grant} and ${children.length} alive direct children (${children.map((child) => child.lane_id).join(", ") || "none"}). Ask its senior for more: write an ask envelope with the desired total grant and why; the senior runs hq lanes grant ${parent.lane_id} --hire <n>.`, {
+    const grantor = (parent.senior.kind === "lane" || parent.senior.kind === "session") &&
+        parent.senior.id
+        ? { kind: parent.senior.kind, id: parent.senior.id }
+        : null;
+    const grantorReason = grantor
+        ? undefined
+        : parent.senior.kind === "user"
+            ? "senior_is_user"
+            : "parent_senior_missing_id";
+    const capacity = children.length === grant
+        ? `is at its hire grant (${children.length} of ${grant} alive children)`
+        : `has exhausted its hire grant (${children.length} alive children; grant ${grant})`;
+    const grantCommand = `hq lanes grant ${parent.lane_id} --hire <n>`;
+    const authorityGuidance = grantor
+        ? `Its senior ${grantor.kind} ${grantor.id} can raise it with: ${grantCommand}`
+        : parent.senior.kind === "user"
+            ? `Its senior is the user and can raise it with: ${grantCommand}`
+            : `No senior is recorded, so an operator must resolve ownership before running: ${grantCommand}`;
+    const message = `Lane ${parent.lane_id} ${capacity}. ${authorityGuidance}`;
+    return new LanesError("hire_grant_exhausted", message, {
         senior_lane_id: parent.lane_id,
         parent_grant: grant,
         alive_children: children.map((child) => child.lane_id),
         alive_child_count: children.length,
+        grantor,
+        ...(grantorReason ? { grantor_reason: grantorReason } : {}),
+        message,
         ask_guidance: {
             envelope: "decision=ask; include the desired total grant and the reason",
             senior_command: `hq lanes grant ${parent.lane_id} --hire <n>`,
@@ -1858,7 +1887,12 @@ async function runCreate(ctx, opts) {
     }
     const senior = opts.senior ? parseSeniorRef(opts.senior) : defaultSenior(ctx);
     assertSeniorExists(hqRoot, senior, ctx);
-    const hireGrantsEnabled = ctx.laneHireGrantsEnabled();
+    // Resolve tenant context before the registry read so the flag evaluator
+    // applies the same company scope as this lane.
+    const company = companyFlag
+        ? await ctx.resolveCompany(companyFlag)
+        : null;
+    const hireGrantsEnabled = await ctx.laneHireGrantsEnabled(company);
     if (requestedHireGrant !== undefined &&
         !callerMatchesSenior(ctx, senior)) {
         throw new LanesError("hire_grant_unauthorized", `Only senior ${seniorKey(senior)} may set a lane's hire grant`, { senior, hire_grant: requestedHireGrant });
@@ -1874,9 +1908,6 @@ async function runCreate(ctx, opts) {
         throw new LanesError("max_lane_depth", `Lane depth ${laneDepth} exceeds cap ${MAX_LANE_DEPTH}`, { depth: laneDepth, max: MAX_LANE_DEPTH });
     }
     // A no-company lane must not call company resolution (openMeshTransport).
-    const company = companyFlag
-        ? await ctx.resolveCompany(companyFlag)
-        : null;
     let meshCompany = company;
     if (meshCompanyFlag) {
         const resolvedMeshCompany = await ctx.resolveCompany(meshCompanyFlag);
@@ -3024,6 +3055,17 @@ async function runList(ctx, opts) {
         return true;
     })
         .sort(compareLaneQueueOrder);
+    const companyContexts = new Map();
+    for (const lane of selectedLanes) {
+        if (lane.host.kind !== "outpost" ||
+            isTerminalLaneState(lane.state) ||
+            laneRunsHere(lane, host)) {
+            continue;
+        }
+        const company = lane.company;
+        companyContexts.set(JSON.stringify([company?.uid ?? null, company?.slug ?? null]), company);
+    }
+    await Promise.all([...companyContexts.values()].map((company) => ctx.laneHireGrantsEnabled(company)));
     const hireByLane = new Map(await mapWithConcurrency(selectedLanes, OUTPOST_HIRE_SUMMARY_CONCURRENCY, async (lane) => [
         lane.lane_id,
         await laneHirePresentation(ctx, lane, allLanes),
@@ -3545,6 +3587,7 @@ async function runGrant(ctx, laneId, opts) {
         await dispatchOutpostLaneCommand(ctx, initial, "grant", { hire: String(hireGrant) });
         return;
     }
+    const enforce = await ctx.laneHireGrantsEnabled(initial.company);
     const lockedLaneIds = [
         laneId,
         ...(initial.senior.kind === "lane" && initial.senior.id
@@ -3557,7 +3600,6 @@ async function runGrant(ctx, laneId, opts) {
             throw new LanesError("hire_grant_unauthorized", `Only senior ${seniorKey(current.senior)} may change lane ${laneId}'s hire grant`, { lane_id: laneId, senior: current.senior });
         }
         const hierarchy = loadAllLanes(hqRoot);
-        const enforce = ctx.laneHireGrantsEnabled();
         if (enforce && current.senior.kind === "lane") {
             if (!current.senior.id) {
                 throw new LanesError("hire_grant_senior_invalid", `Lane ${laneId} has a lane senior without an id`, {
@@ -3611,7 +3653,7 @@ async function runBackfillGrants(ctx, opts) {
     }
     const apply = Boolean(opts.apply);
     const hqRoot = ctx.hqRoot();
-    if (apply && ctx.laneHireGrantsEnabled()) {
+    if (apply && await ctx.laneHireGrantsEnabled(null)) {
         throw new LanesError("hire_grant_backfill_gate_enabled", "Backfill must be applied and verified before lanes.hire-grants is enabled", { flag: LANE_HIRE_GRANTS_FLAG });
     }
     if (apply && ctx.env.HQ_LANE_ID?.trim()) {
@@ -3642,6 +3684,24 @@ async function runBackfillGrants(ctx, opts) {
     }
     let rows = planHireGrantBackfill(allLanes, profileMaxConcurrent);
     if (apply) {
+        const lanesById = new Map(allLanes.map((lane) => [lane.lane_id, lane]));
+        const targetCompanies = new Map();
+        for (const row of rows) {
+            if (row.action === "unchanged")
+                continue;
+            const lane = lanesById.get(row.lane_id);
+            if (!lane) {
+                throw new LanesError("hire_grant_backfill_target_changed", `Backfill target lane ${row.lane_id} is unavailable`, { lane_id: row.lane_id });
+            }
+            const company = lane.company;
+            if (!company)
+                continue;
+            targetCompanies.set(JSON.stringify([company.uid ?? null, company.slug ?? null]), company);
+        }
+        const companyGates = await Promise.all([...targetCompanies.values()].map((company) => ctx.laneHireGrantsEnabled(company)));
+        if (companyGates.some(Boolean)) {
+            throw new LanesError("hire_grant_backfill_gate_enabled", "Backfill must be applied and verified before lanes.hire-grants is enabled", { flag: LANE_HIRE_GRANTS_FLAG });
+        }
         const shortfalls = rows.filter((row) => row.grant_shortfall > 0);
         if (shortfalls.length > 0) {
             throw new LanesError("hire_grant_backfill_allocation_shortfall", "Existing parent grants do not cover the grants allocated to alive children; resolve these rows before applying the backfill", { lanes: shortfalls });
@@ -4009,7 +4069,7 @@ async function prepareAccountMove(ctx, lane, input) {
         if (admission.action === "refuse" && admission.error)
             throw admission.error;
         const queued = admission.action === "queue";
-        const moved = withResumeHireAdmission(ctx, lane, () => casUpdateLane(hqRoot, laneId, (current) => {
+        const moved = await withResumeHireAdmission(ctx, lane, () => casUpdateLane(hqRoot, laneId, (current) => {
             // The copy and every check above were made from `lane`; a record
             // that moved on since (another move, a spawn, a cancel) invalidates
             // them, so the write is refused rather than applied to a state it
@@ -4061,7 +4121,7 @@ async function runMessage(ctx, laneId, opts) {
     assertLaneRunsHereForOperatorMutation(ctx, lane, "message");
     // Check before transcript recovery, account probing, or message writes.
     // The final state transition repeats this check under the senior lock.
-    withResumeHireAdmission(ctx, lane, () => undefined);
+    await withResumeHireAdmission(ctx, lane, () => undefined);
     lane = laneWithRecoveredProviderSession(hqRoot, lane);
     // An account move is refused on its own terms first: a running lane and a
     // provider without session resume get the move's named errors, not the
@@ -4341,7 +4401,7 @@ async function runResume(ctx, laneId, opts) {
     }
     // Fail before provider/session work if a terminal child would consume a
     // slot that its senior has already assigned elsewhere.
-    withResumeHireAdmission(ctx, lane, () => undefined);
+    await withResumeHireAdmission(ctx, lane, () => undefined);
     assertLaneRunsHereForOperatorMutation(ctx, lane, "resume");
     lane = laneWithRecoveredProviderSession(hqRoot, lane);
     if (opts.model !== undefined && opts.account === undefined) {
@@ -4913,14 +4973,19 @@ async function runReparent(ctx, laneId, opts) {
     const nextSenior = parseSeniorRef(opts.senior);
     assertSeniorExists(hqRoot, nextSenior, ctx);
     const initial = readLane(hqRoot, laneId);
+    const needsHireGrantGate = nextSenior.kind === "lane" &&
+        seniorKey(initial.senior) !== seniorKey(nextSenior);
+    const hireGrantsEnabled = needsHireGrantGate
+        ? await ctx.laneHireGrantsEnabled(initial.company)
+        : false;
     const lockIds = [
         laneId,
         ...(initial.senior.kind === "lane" && initial.senior.id ? [initial.senior.id] : []),
         ...(nextSenior.kind === "lane" && nextSenior.id ? [nextSenior.id] : []),
     ];
-    withLaneHireLocks(hqRoot, lockIds, () => runReparentLocked(ctx, laneId, opts));
+    withLaneHireLocks(hqRoot, lockIds, () => runReparentLocked(ctx, laneId, opts, hireGrantsEnabled));
 }
-function runReparentLocked(ctx, laneId, opts) {
+function runReparentLocked(ctx, laneId, opts, hireGrantsEnabled) {
     const hqRoot = ctx.hqRoot();
     if (!opts.senior) {
         throw new LanesError("missing_senior", "--senior is required", {});
@@ -4934,7 +4999,7 @@ function runReparentLocked(ctx, laneId, opts) {
     }
     const seniorCompany = companyOfSenior(hqRoot, nextSenior, ctx);
     assertSameTenant(lane.company, nextSenior, seniorCompany, { lane_id: laneId });
-    if (ctx.laneHireGrantsEnabled() &&
+    if (hireGrantsEnabled &&
         nextSenior.kind === "lane" &&
         seniorKey(lane.senior) !== seniorKey(nextSenior)) {
         const parent = readLane(hqRoot, nextSenior.id);

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

@@ -0,0 +1,27 @@
+import { type FlagClientOptions, type FlagResolution } from "@indigoai-us/hq-flags-client";
+import type { LaneCompanyRef } from "./types.js";
+export declare const LANES_FLAG_API_DEFAULT_ENDPOINT = "https://hqapi.hq.computer";
+export declare const LANES_FLAG_READ_TIMEOUT_MS = 5000;
+export interface LanesFlagClient {
+    ready(): Promise<void>;
+    explain(flagKey: string, options?: {
+        fallback?: boolean;
+    }): FlagResolution;
+    close(): void;
+}
+export type LanesFlagClientFactory = (options: FlagClientOptions) => LanesFlagClient;
+export interface ReadLanesFlagOptions {
+    company?: LaneCompanyRef | null;
+    env?: NodeJS.ProcessEnv;
+    createClient?: LanesFlagClientFactory;
+    getToken?: () => string | Promise<string>;
+    reportFailure?: (error: unknown) => void;
+}
+/**
+ * Read a lanes flag once for each company identity in this CLI process. The
+ * cache contains only an in-flight or settled boolean promise; it is never
+ * written to disk. A local override is checked on every call and wins first.
+ */
+export declare function readLanesRegistryFlag(flagKey: string, options?: ReadLanesFlagOptions): Promise<boolean>;
+export declare function _resetLanesRegistryFlagCacheForTests(): void;
+//# sourceMappingURL=registry-flag.d.ts.map

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

@@ -0,0 +1,129 @@
+import { createFlagClient, readLocalOverride, } from "@indigoai-us/hq-flags-client";
+import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+export const LANES_FLAG_API_DEFAULT_ENDPOINT = "https://hqapi.hq.computer";
+export const LANES_FLAG_READ_TIMEOUT_MS = 5_000;
+const registryReads = new Map();
+class MissingFlagTokenError extends Error {
+    constructor() {
+        super("No cached HQ identity token is available");
+        this.name = "MissingFlagTokenError";
+    }
+}
+class MissingFlagRowError extends Error {
+    constructor(flagKey) {
+        super(`The hq-flags registry did not resolve ${flagKey}`);
+        this.name = "MissingFlagRowError";
+    }
+}
+function errorClass(error) {
+    return error instanceof Error ? error.name : "UnknownError";
+}
+function reportReadFailure(flagKey, error) {
+    const suffix = flagKey.replace(/^lanes\./, "").replaceAll(/[^a-zA-Z0-9]+/g, "_");
+    process.stderr.write(`${JSON.stringify({
+        event: `lanes.${suffix}.flag_read_failed`,
+        flag: flagKey,
+        error: errorClass(error),
+        fallback: false,
+    })}\n`);
+}
+function cacheKey(flagKey, company, endpoint) {
+    return JSON.stringify([
+        flagKey,
+        endpoint,
+        company?.uid ?? null,
+        company?.slug ?? null,
+    ]);
+}
+/**
+ * Read a lanes flag once for each company identity in this CLI process. The
+ * cache contains only an in-flight or settled boolean promise; it is never
+ * written to disk. A local override is checked on every call and wins first.
+ */
+export async function readLanesRegistryFlag(flagKey, options = {}) {
+    const env = options.env ?? process.env;
+    const localOverride = readLocalOverride(flagKey, env);
+    if (localOverride !== null)
+        return localOverride;
+    const endpoint = env.HQ_FLAGS_API_URL?.trim() || LANES_FLAG_API_DEFAULT_ENDPOINT;
+    const key = cacheKey(flagKey, options.company, endpoint);
+    const cached = registryReads.get(key);
+    if (cached)
+        return cached;
+    const pending = readRegistryValue(flagKey, endpoint, options);
+    registryReads.set(key, pending);
+    return pending;
+}
+async function readRegistryValue(flagKey, endpoint, options) {
+    const company = options.company;
+    const companyUid = company?.uid?.trim();
+    const companySlug = company?.slug?.trim();
+    let client;
+    let enabled = false;
+    let failed = false;
+    let reported = false;
+    const reportFailure = (error) => {
+        failed = true;
+        if (reported)
+            return;
+        reported = true;
+        (options.reportFailure ?? ((cause) => reportReadFailure(flagKey, cause)))(error);
+    };
+    try {
+        const acquireToken = options.getToken ?? (async () => {
+            try {
+                return await ensureCognitoIdToken({ interactive: false });
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message.startsWith("No valid HQ session")) {
+                    throw new MissingFlagTokenError();
+                }
+                throw error;
+            }
+        });
+        const getToken = async () => {
+            const token = await acquireToken();
+            if (typeof token !== "string" || token.trim().length === 0) {
+                throw new MissingFlagTokenError();
+            }
+            return token;
+        };
+        client = (options.createClient ?? createFlagClient)({
+            endpoint,
+            getToken,
+            env: {},
+            refreshIntervalMs: 0,
+            requestTimeoutMs: LANES_FLAG_READ_TIMEOUT_MS,
+            ...(companyUid ? { companyUid } : {}),
+            ...(companySlug ? { companyIdentifiers: [companySlug] } : {}),
+            onError: reportFailure,
+        });
+        await client.ready();
+        const resolution = client.explain(flagKey, { fallback: false });
+        if (failed)
+            return false;
+        if (resolution.source !== "snapshot" && resolution.source !== "local-override") {
+            reportFailure(new MissingFlagRowError(flagKey));
+        }
+        else {
+            enabled = resolution.value;
+        }
+    }
+    catch (error) {
+        reportFailure(error);
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch (error) {
+            reportFailure(error);
+        }
+    }
+    return failed ? false : enabled;
+}
+export function _resetLanesRegistryFlagCacheForTests() {
+    registryReads.clear();
+}
+//# sourceMappingURL=registry-flag.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.185.0",
+  "version": "5.185.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {